4 Levels of API Adoption

#api #microservices #paas #saas

The following is my list of non-technical patterns and common characteristics to describe degrees of adoption an engineering organisation is likely to find themselves in as part of their journey.

Level 1: The Backend Team

APIs built and owned strictly by backend engineers
API design is informed mostly by the backend implementation
Consumers create their own API client implementations using technical documentation or ask the backend engineers for support
Written change requests used to ask for new APIs or features

Level 2: The Full Stack

Engineers working on frontend features also build backend features and APIs
API design is informed mostly by the frontend implementation
Machine readable interfaces such as GraphQL, Swagger or Postman Collections may be used to help to consume and document the APIs
Changes to API design are made by directly changing backend code

Level 3: API First

APIs are built and owned by platform or backend engineers working together with teams delivering end to end features
APIs are commonly designed to implement an overarching DDD (Domain Driven Design) microservices architecture
Machine readable interfaces are published in a common API catalogue alongside documentation and are used as a design and prototyping (mocking) tool
API designs are collaboratively reviewed and iterated on using concrete Pull Requests to modify machine readable API definitions such as GraphQL schemas or OpenAPI documents

Level 4: Platform

APIs are built by engineers in multidisciplinary teams delivering end to end features built on layers of APIs
APIs are treated as managed platform products with lifecycles and used to enable both internal and external developers
Versioned API client packages with uniform conventions and documentation are released to make up full SDK libraries
Machine readable API definitions act as a single source of truth for platform and data capabilities

Conclusion

These descriptions are by no means an exhaustive list to rank companies' API competencies but rather a tool to assess the general level of maturity using common heuristics gathered from nearly 10 years of experience in the field.

Most companies I've had a good internal view into have been somewhere between levels 1-2 with some elements of levels 3-4 already in their roadmap.

Examples of Level 4 companies are seemingly rare but in addition to the obvious big cloud players AWS, Google and Azure there's also a large group of more recent exceptional success stories with companies including Stripe, Adyen, Auth0, Datadog and Twilio showing that the use of APIs to build a developer friendly platform can translate into a billion-dollar startup valuation.

At time of writing, some smaller Level 3-4 companies I'm also very excited to follow include Netlify, TypeForm, Vercel, Fauna, TakeShape, Contentful and Storyblok.

What level is your company at? Are you planning to build a level
four API platform?