I am having fun pushing forward the APIs.json specification, while also building the next iteration of APis.io. The v1.0 of APIs.io is still powering the website right now, but I am exploring what is possible with the specification and search with a v2.0 of the APIs.io search engine I simply call explore. I will swap out v1.0 with v2.0 here shortly, but I wanted to gather my thoughts on my approach before I begin the next round of harvesting and cleaning data.
I need another round of automated tagging, cleaning up descriptions, and of course finding more APIs, but the ability to browse apis by provider, by tags, and now by rules, demonstrates three of the dimensions in which I am thinking about when it comes to API discovery powered by APIs.json indexes with search and ratings overlays. The search on the homepage of this project hasn’t caught up the information that is available when browsing, but if you click on the apis, tags, or rules listing in the top-level nav, or view a provider like Factset, you’ll see what I mean. Factset is one of a handful of providers like Stripe and Twilio, where I have a robust APIs.json with accompanying OpenAPI—-something that has potential for rich APIs.io search and API Evangelist ratings.
What I really, really, really like about this approach can be seen with the APIs.json Artisanal entry for Factset, and then the resulting APIs.io rendering where the overlays are applied, but still rendered as APIs.json. It is a lot to take in. I know. Try thinking about it across 80+ API providers in there, where some have one API, and others like AWS have 300+. That is why I like it. It works at scale. It allows me to harvest and manage APIs.json indexes for API providers. It allows me to also manage the OpenAPIs for each individual API. I can then apply an APIs.io search overlay enhancing summaries, descriptions, and tags, but then enrich with an API Evangelist ratings—which are stored as overlays in the root APIs.json Artisanal project, but then overlaid when publishing to the APIs.io explore edition of our API search engine.
It is slick. It is clean. I like it. I already have auto-tagging of APIs using their API paths and summaries—-this is part of the APIs.io search overlay process. Which helped me add the browse by tags. Now API Evangelist automatically scans the Artisanal repository and adds a ratings overlay. I have a lot more work to do on the rules and the scoring, but it helps me make my API ratings more browseable—-which adds an interesting dimension to think about things. Next I am going to add search and browse by properties-—things like SDKs, Tutorials, and the other properties that your APIs.json lets you index. APIs.io APIs, Properties, Tags, and Rules. That will be the title of my next post, where I work the analysis of the properties available across these APIs, and how they intersect with the tag vocabulary and the rules applied to the surface area of APIs.
Fun stuff. I’ll work on the browse by property next. Then I will play catch up on the search, allowing it to search by name, description, and tags of each API, as well as the properties. And when any of the properties are OpenAPI, I can also introduce the summaries, descriptions, and tags for the actual API. This provides a very rich dimension. It is a dimension that then allows me to run my API Evangelist ratings system against. It all makes for a very rich set of API indexes. Alongside properties and updating the search, I will automate the harvesting of new APIs using the ever growing tag vocabulary I am defining. This will add new APIs to the index, and I also have begun automating the discovery of blogs, plans, pricing, support, and other properties of APIs. The holy grail is auto-discovery and auto-generation of OpenAPIs. Which doesn’t always exist. That is when you start parsing the docs page and auto-generating the OpenAPIs—-something I have done before, but will improve upon in this next sprint.
I have set aside any work on the visual rendering of data for about six months. I have been hyper focused on the structure and process around the APIs.json Artisanal index and how to effectively render it for searching by apis, properties, tags, and rules. Ultimately I think the critical mass of API providers (managing their own apis.json + OpenAPI indexes) with the rich summaries, descriptions, tags, and properties, as well as ratings will be what shifts both APIs.io and APIs.json into a higher gear. Although there is a lot more polishing needed, the base structure is there. I just need to scale the number of APIs in the index, and the number of OpenAPIs I have across them. Then I can keep dialing in the tag and rule vocabulary to keep the API search delivering value. I learned a lot during this round of work. The properties and now overlays of APIs.json really made all of this possible, and I think the search and ratings overlays are just the beginning. Historically the power of APIs.json was in the evolution of human-readable properties to be machine-readable properties—-now, with overlays, multiple API service or tooling providers can overlay value across many different API operations–cause it takes a village ya know!
This is all still just an exploration into what is possible. I have a vision of where I’d like to see this work goes, but I learn the most profiling APIs. My goal is to automate and scale everything I can. But there will always be some low-level human jobs across this work, and of course I am exploring what AI can help with. Ultimately I am looking to keep the tasks I tackle as the ones that require my eye for what matters, and automate and queue up the rest for outsourcing. This leaves me doing the thing I like most—-profiling APIs and learning what it is they do well, and how they contribute (or not) to the overall API landscape.
