How we develop APInf Platform REST APIs openly

APInf provides you with a unified, simple interface for publishing your APIs to the developer community and performing complex API management tasks. It allows you to gain a better understanding of your API traffic. Providing just GUI is not enough for us — nor to some of our customers. Our principle is that what ever can be done with GUI, you can do it with an API as well.

Open development

In this post I’ll use one of the platform APIs as an example. With APInf Catalog REST API we have moved to open design practice described below. We are moving other platform APIs to follow the same open method.

The example API is called APInf Catalog REST API which enables API gatalog management via a simple API. With this API you can list, add, update and remove (CRUD) APIs in the catalog.

Next version API design open for commenting

We have Catalog REST API production version andthe APInf Management REST API production version now available. Next design version of the Catalog REST API is also visible in the API portal. Anyone can see the plan for next version and add own requirements to the feedback tab.

Since our platform is developing fast we anticipate next version of the Catalog API to be launched multiple times during this year. It is expected that modifications will be minor and non-breaking (but not guaranteed). During 2018 the speed most likely gets slower and we will launch version 2.

Iterative open process

In a nutshell, the process is pretty simple:

  1. Launch API
  2. Copy OpenAPI spec to future version (Design version) of the API at hand to enable collection of new features (via the feedback tab). Make some noise through thesocial media and by contacting existing customers.
  3. Analyze the feedback — listen to users. Apply design suggestions to API (Design version). Give credit to those who bothered to comment your API design.
  4. Finalize the design beta
  5. Collect more detailed feedback from trusted 3rd party developers. We normally get around 5 high volume API consumers to do the final review.
  6. Apply changes to design.
  7. Implement new version, test it thoroughly (automated and human tests).
  8. Start again from step 1.

Apply the same process to all platform APIs

We plan to apply this open process to all our platform APIs: Management API and APInf Analytics REST API (API performance and other analytics). The Analytics API is currently in the design phase and we’ll push the version 1 design to platform in a few weeks.