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?

Attribution

Illustrations: @hrishikesh1990