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.
- 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
- 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
- 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
- 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
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.
What level is your company at? Are you planning to build a level
four API platform?