What is the API maturity model?

Some API maturity frameworks emphasize specific dimensions such as security, discoverability, maintainability or platform engineering. API management vendors, including Kong, Tyk and Curity, offer API maturity models aligned with their own solutions, helping clients gauge their progress in adopting those platforms. Other models are broader in scope and can be applied to any protocol or architecture.

Application programming interfaces (APIs), which facilitate connections between separate services and applications, are a key pillar of the internet, helping developers use third-party technologies and data sources, instead of building them from scratch. They also enable the integration of resources, data, security and governance inside organizations, streamlining internal deployments and cross-team communications. Multiple APIs can be packaged alongside libraries, UI tools and other components to form a software development kit (SDK), a set of tools that helps developers build standardized applications quickly and reliably.

API maturity models identify and describe specific structural and technological innovations as well as strategic best practices that can help organizations develop more sophisticated and robust API systems, improving efficiency, security and interoperability. They serve as a roadmap that helps organizations decide which innovations to prioritize as they accelerate their API development.

The Richardson maturity model, one of the most widely cited frameworks, assesses an API’s adherence to RESTful principles across four maturity levels, with the highest tier representing a fully RESTful system.

In 2000, computer scientist Roy Fielding introduced REST, an architectural style that promotes features such as a uniform interface, client-server decoupling, statelessness, cacheability and layered systems. Together, these capabilities can improve scalability, efficiency and flexibility within organizations and can contribute to a more open, resilient and secure internet when implemented at a larger-scale. Modern iterations often use HTTP to transport information and the human-readable JSON format to organize this data, although other protocols and formats can also be used.

In 2008, software engineer Leonard Richardson built upon this framework with a model that identifies specific technical changes that organizations can implement to improve the adaptability and resilience of their REST API design. The Richardson maturity model (RMM) “encourages you to look at the three web technologies—URI, HTTP and hypermedia (also known as HTML)—as three individual technologies rather than a package deal,” Richardson told IBM Think. The framework shows the practical benefits of progressively implementing each, “given that we have these technologies, they’re very popular, they’re widely supported by every programming language.”

The Richardson maturity model prioritizes resource implementation, where each resource is given a distinct URI, in accordance with general REST principles, which recommend assigning each resource a unique identification. The RMM also encourages the use of response documents, which capture an API’s current state, rather than description documents, which present a static, pre-defined description of an API at a single point in time. The model generally applies to http-based web applications, although as a conceptual framework, it can also be used in other contexts, such as IoT networks and data pipelines.

The Richardson maturity model uses four levels to distinguish between different degrees of maturity, from a non-RESTful architecture to a fully RESTful one.

Level zero represents a non-RESTful design, featuring a single endpoint (such as “/api”) and a single command (usually POST). While level zero is simple to implement, it fails to use HTTP’s most powerful features, including verbs, URIs and status codes. Instead, HTTP is used merely as a transport mechanism, with all operational details added to the message body itself.

Because XML-based remote procedure call (RPC) patterns have historically employed this method, critics have nicknamed it “swamp of POX”(plain old XML). The idea is that, with a lack of structure and no clear delineations between services, functions and data can easily become cluttered and tightly coupled. At level zero, the API has no capacity to identify or expose discoverable resources, forcing API consumers to know in advance what’s available. Developers might struggle with scaling, versioning and troubleshooting because the single endpoint cannot share information about itself.

Level one introduces multiple URIs, each capable of representing a different resource. But it continues to use only a single HTTP verb, typically POST. Instead of interacting with a generic “/api” endpoint, clients can now call endpoints that correspond to specific resources—for example, “/products,” “/carts” or “/invoices” in an e-commerce setting. However, clients typically still need to convey operational intent or actions through the body of the request itself, rather than using a pre-defined set of HTTP verbs.

This approach establishes cleaner lines between resources and reduces ambiguities around which resources are available to clients. But developers can easily confuse which actions can be performed because there is no standardized format for calling URIs. Level one can also become cumbersome over time because, in practice, developers might create new endpoints for individual actions, such as “/productsUpdate” or “/productsDelete.” This approach can cause URIs to gradually pile up, making rollouts and versioning more challenging.

Finally, the model makes developers more reliant on external API documentation because, although resources get assigned distinct URIs, they can’t expose which actions can be interpreted or fulfilled.

Level two adds HTTP methods, a standardized set of verbs that developers can use to interact with data and services. In many configurations, clients can use four basic commands—create, read, update or delete—to perform different actions at each endpoint. Headers can be used to convey additional information— such as content type, conditional requirements or authorization credentials—during the API call.

This approach is more efficient and organized compared to level one and level zero because users have a sense of what the API is capable of and how clients can interact with it. But APIs aren’t able to convey this information in real time—users can only learn about each API through an external developer portal—reducing discoverability. This static approach can also lead to misalignments if API documentation doesn’t match current capabilities.

Today, most organizations’ API ecosystems operate at level two because the tier offers a balance between predictability, efficiency and accessibility. It also enables organizations to take advantage of HTTP’s distinct infrastructure capabilities, such as caching (storing frequently-used resources locally, so they can be quickly retrieved), leading to significant performance gains.

Level three introduces HATEOAS, or hypermedia as the engine of application state. When a client makes an API call, the API will respond with a dynamic list of options for various actions and related terms, like how modern browsers operate. These actions and terms are conveyed in-band, meaning developers do not have to consult external documentation to learn about them. Hypermedia-based architectures also foster interoperability because external clients can easily access services without learning how to use them in advance.

At the same time, hypermedia controls introduce greater complexity at run time: “The client has to be able to not just react in a pre-programmed way but be able to read the documents that are coming in from the server and use the content of those documents to make the decision about its next request,” Richardson said.

Building and maintaining hypermedia capabilities can be more costly and time-consuming due to hypermedia’s dynamic structure. The API responds to client requests with a set of links for further actions, which is more operationally taxing. Also, many client platforms don’t support hypermedia, so when an organization embraces HATEOAS, external users might have to find compatible tools before they can access these services.

Today, HATEOAS is used most often by libraries, non-profits, scientific institutions, market coalitions or insurgent companies (organizations that are trying to disrupt an industry), Richardson said, because it promotes openness and interoperability. Hypermedia can also be effective when used internally because it makes APIs and actions easily discoverable to users, even users who have no prior knowledge of the API ecosystem. Some companies might offer hypermedia APIs during their growth phase, and then restrict access after they begin to monetize their product.

The industry is increasingly shifting to alternatives such as GraphQL and gRPC for particular use cases. While 93% of developers say they use RESTful web services in some capacity, according to Postman’s State of the API report, a third now use GraphQL and 14% use gRPC. GraphQL can intelligently fetch requests from multiple microservices, even services hosted in different environments, and compile them into a single response, boosting efficiency and preventing over- or under-provisioning. gRPC, meanwhile, is ideal for streaming, telemetry and other use cases where high performance and low latency are primary concerns.

While GraphQL and gRPC can’t replicate the dynamic nature of hypermedia, both architectures address pain points related to efficiency and schema management with more precision, leading some organizations to prioritize these implementations over full hypermedia controls.

In the Richardson maturity model, moving from one API maturity level to the next can present both design and technical challenges. The process often involves refactoring server code to accommodate multiple URIs (level one) and multiple HTTP methods (level two). This is achieved by updating routing rules, database interactions, tests, documentation and controllers.

Organizations might start by cataloging their current endpoints, identifying which ones can be modified to follow RESTful constraints and mapping out required resources and verbs. Developers might build a new version on top of the organization’s current build so that client calls are not disrupted during the transition. A comprehensive set of error codes can also help users learn how to navigate new API endpoints and troubleshoot errors without consulting excessive documentation.

While the RMM focuses on specific technological implementations in RESTful systems, organizational models take a broader view, helping enterprises align around a shared set of principles that foster consistency, resource optimization and adaptability. While strategic maturity frameworks can differ by organization, one common approach incorporates four tiers:

In basic or ad hoc API ecosystems, organizations react to immediate concerns rather than working under a cohesive API development framework. Developers create and retire APIs as needed with limited centralized control, which can lead to misalignments as well as governance, security and observability issues. With little insight into current API performance, teams can’t effectively allocate resources or plan for the future.

Standardized API ecosystems introduce consistent documentation, naming conventions, error codes and design patterns. An API gateway might be used to enforce authentication, authorization and other centralized API security protocols. Developers can confidently add, remove and maintain APIs within the organization’s governance structure and can seamlessly reuse and adapt components. Clients can easily discover and learn about available services through a developer portal and integrated onboarding, increasing overall API adoption.

But because there are few mechanisms to capture API performance and security at this stage, teams might struggle to maintain oversight over the ecosystem. For example, an organization might be unaware of security breaches, versioning errors or authentication problems within a particular API cluster.

Managed frameworks use telemetry data, KPIs and other metrics to capture API performance in greater detail. For example, a monitoring system can alert developers when clients face excessive API downtime and help identify the underlying issue—whether server overload, network outages, code misalignments or another problem.

Managed ecosystems might also feature more advanced API governance infrastructure, which preserves team autonomy while giving stakeholders a clear understanding of which APIs they’re responsible for managing. Finally, managed ecosystems introduce formal lifecycle management processes, where APIs are monitored across design, development, maintenance, versioning and retirement. But at this tier, organizations might still lack a cohesive vision of how API management contributes to broader business objectives.

Optimized or strategic frameworks combine governance, standardization, lifecycle management, metrics and security best practices with long-term business planning. With oversight over the entire network, organizations can efficiently scale and allocate resources and dynamically respond to changing market conditions. Rather than thinking of APIs only as technical components, organizations can deploy APIs in service of broader business objectives. Strategic frameworks help organizations craft forward-thinking roadmaps and planning strategies, accelerating innovation and improving operational efficiency.

Organizations might craft API maturity models to address specific pain points or operational focuses. Common focus areas include:

These maturity models focus on API design principles such as adopting specific protocols, practices and standards that contribute to an improved user experience. The RMM is one example of a design-based framework, but other models might focus on GraphQL, gRPC and other architectural styles.

Governance models focus on the degree to which organizations can maintain control and oversight over their API ecosystems. At the highest tiers, organizations maintain high compliance, data quality and security while preserving stakeholder autonomy.

Governance-based frameworks also consider the quality of an API ecosystem’s enforcement mechanisms, including whether it incorporates automated checks and validation processes. Ownership models, meanwhile, assign APIs to specific teams so that every API is accounted for.

Security-focused maturity frameworks assess an API network’s adherence to security best practices. In the earliest stages, organizations might rely on API keys or basic HTTP authentication, which both lack granular control and are vulnerable to exposure. Advanced systems might introduce token-based authentication and authorization as well as zero-trust access. The most sophisticated frameworks adhere to identity and access management principles, such as using the OAuth and OpenID Connect (OIDC) authorization protocols.

API documents are technical guides that provide instructions about how developers can use and integrate a particular API. Documentation can include tutorials and code examples as well as release notes and acceptable call parameters.

Initially, organizations might have no standardized process for creating and maintaining API documentation, giving developers little insight into what each API is capable of. Higher tiers might introduce standardized formats for describing API specifications, such as the OpenAPI Specification (OAS) or API Blueprint. Mature API frameworks might also incorporate automation, helping ensure that documentation is automatically updated alongside each rollout.

Observability-focused maturity models help organizations track the sophistication of their data collection mechanisms across microservices. Basic systems might use telemetry and metrics to help organizations spot errors but are unable to help identity longer-term data trends.

More complex platforms can proactively track latency, request rates and other relevant metrics to help organizations respond to downtime, misalignments and other problems in advance. In the highest tier, organizations can identify high-level data patterns and generate actionable insights that guide future API development.