We are working on taking some older research from the API Evangelist on API rating and ranking systems and distilling it down into a simple way to help validate and qualify APIs across the API life cycle. Breaking down a human-readable set of properties for APIs we collect from across the landscape, in a series of machine-readable modules that help us identify the maturity of APIs across the entire API life cycle. Helping with not only API discovery, but also understanding how mature, reliable, and active enterprise services are.
Our approach to rating and ranking API resources centers on identifying the existing building blocks of API operations, and healthy API-driven services, and think more deeply about how we place value on these elements. Helping us understand the value of an API having:
– OpenAPI Contract – The overall value and importance of each API to have a complete OpenAPI contract defining what it delivers.
– JSON Schema – Augmenting OpenAPI, but also providing standalone JSON Schema artifacts for understanding the schema behind services.
– Postman Collections – Having a ready to go, single click representation of what an API does, that can be loaded in a commonly used client.
– Postman Environments – Ensuring there are machine-readable blueprints for the environments we depend on throughout the API life cycle.
Any API that posses these building blocks automatically increase in value. What ranking do you place on APIs in our catalog that has these supporting elements? After these machine-readable cornerstones, what is the value of having some other less machine, and more human elements of understanding the value an API delivers?
– Documentation – Making sure there is up to date, interactive documentation.
– sign-up – An easy to find, friction-less sign-up and login for services.
– Plans & Pricing – Clear, and coherent access tiers, pricing, and rate-limiting.
– SDKs – Access to robust and secure SDKs for integrating with API resources.
– Support – Make sure there is always someone out there to support an API.
– Status Dashboard – Knowing whether or not an API is up, and what the history is.
– Terms of Service – Being able to access plain language terms of service for an API.
It is important that we identify the building blocks of API operations that matter. Once we’ve identified the elements that matter most, we then need to assign a value to the presence of these building blocks. Then use machine-readable definitions like APIs.json, OpenAPI, and JSON Schema to help us document, validate, and apply the rating and ranking each API deserves–in an automated, real-time, fashion, helping us know which APIs deliver, and which ones do not.
We are working on some approaches to defining and applying an API rating and ranking system using the APIs.json discovery format. Helping us understand the value each individual API, but also be able to browse, search, and discover across hundreds or thousands of internal, partner, and public APIs. There are just too many APIs out there today to be able to keep up with which ones are the good or bad applies, we are going to need more help to understand where the most valuable resources are that we should be integrating into our applications.
