2024 State of SaaS APIs: API Specifications and Documentation

April 18, 2024

In modern software development, APIs are the connective tissue of the Internet. This is why API design is critical in bridging diverse systems and increasing interoperability between products.

In this article, we'll explore the role of API specifications and documentation within API design and draw on insights from the 2024 State of SaaS APIs report.

What is API design?

API design is the process of planning and structuring an Application Programming Interface, which defines how a software application allows other software applications to access its functionality and data. When done properly, API design results in an interface that is easy to use, efficient, secure, and scalable.

Good API design not only benefits software developers but end-users as well. API specifications and documentation are tenets of effective API design, which involve:

• Specifying methods and endpoints: Designating the specific actions the API can perform (methods), and the location within the API where it accepts requests and returns responses (endpoints).
• Writing documentation: Creating clear and detailed explanations of how to use the API, including examples of requests and responses, error codes, and operational details, which is crucial for developers to integrate and use the API effectively.

API Specifications

An API specification is the "blueprint" for an API; it describes each element of the API and the purpose it serves. Its specifications outline the methods, endpoints, data formats, and protocols an API will use, which ensures developers have a clear roadmap for building or interacting with an API. It is a crucial foundation for clear and effective communication between different software components.

The most common API specification formats are:

1. OpenAPI and Swagger

The OpenAPI Specification (OAS) is a widely adopted standard for describing RESTful APIs.

It describes an API's endpoints, parameters, responses, and other details and can be written in JSON or YAML format. Version 3 of the OpenAPI Specification is currently in widespread use, and the forthcoming release of Version 4 promises further enhancements and features to accommodate evolving API practices and needs.

Swagger is often mentioned along with OpenAPI. It is a collection of open source tools for building APIs based on the OpenAPI specification for designing, implementing, and documenting RESTful APIs.

There is some confusion between OpenAPI and Swagger because many developers use both terms interchangeably. Swagger was the original name of the standard and applies to versions up to and including version 2. From version 3 onward, the standard was renamed to OpenAPI by the OpenAPI Initiative. Swagger now refers to the toolset for building APIs using OpenAPI.

2. Postman Collections

Designed for use with Postman, a developer tool for building and testing APIs, a Postman Collection is an API specification that allows developers to define APIs, share and execute API requests, create and model API workflows, and document and test APIs.

3. RAML (RESTful API Modeling Language)

RAML is a YAML-based API specification that focuses on top-down API modeling to describe APIs clearly and concisely. Its structure makes it useful for long-term API planning; however, it is an older specification and rarely used.

4. API Blueprint

API Blueprint is a Markdown-based high-level documentation authoring language for describing web APIs that is meant to be easily readable by both humans and machines.

What specification formats do most SaaS APIs use?

The 2024 State of SaaS APIs, a white paper that examined 145+ APIs across 12 industries, reports that OpenAPI and Swagger are the most supported API specification formats.

A well-defined API specification sets the stage for API documentation, testing, and SDKs. Sadly, many developers see the necessary step of making API specifications as an unnecessary formality. At the opening keynote of the recent API Conference in London, when asked if they used an API specification, only half the audience raised their hands. This general lack of rigor explains why many APIs are poorly designed, with inconsistencies and redundancies, and are hard to work with.

API Documentation

API documentation is an indispensable resource for developers, providing essential guidance on how to use and integrate an API effectively. It describes what the API does, the services it offers, and how it can be used, including detailed examples of requests and responses, authentication methods, and error handling. Good documentation improves the developer experience and significantly reduces the learning curve and development time, enabling users to solve problems independently.

There are two ways to create API documentation:

1. Manually

Initially, API documentation was often manually created. This involves writing detailed guides, example requests and responses, and instructions for integrating with the API. Although this approach allows for a high degree of customization, it can be time-consuming to maintain and update, and the process is tedious.

2. Using automated tools

Tools like Swagger, Apiary, and Postman can automatically generate documentation from the API's codebase or an API description file. The documentation generated by these tools is interactive, allowing developers to make API calls directly from the documentation to see real responses. Some large language models are proficient at generating documentation from codebases, and it should be expected that AI will soon be integrated into automated API documentation tools.

While there is little data on the topic, it has been our experience that about half of the API documentation we have encountered is either outdated or inaccurately describes the current API, which only adds to the complexity of working with third-party APIs.

Conclusion

While API design industry standards exist, SaaS API design often lacks the necessary foresight and planning, resulting in inconsistency and inefficiency across different APIs. Poor API design not only hampers API scalability and usability but also poses significant challenges for developers who rely on them for robust applications that require third-party data to build automation and insights into their products.

As we've explored, API specifications and documentation are critical in mitigating these issues by providing clear guidelines and comprehensive information supporting the development and integration processes. Investing time in thoughtful API design, rigorous specification, and detailed documentation can dramatically improve the quality and functionality of APIs.

An increasing trend in the industry is to utilize unified API platforms that standardize interactions across various applications. These platforms simplify the integration process and reduce the overhead associated with maintaining multiple APIs. They often provide additional layers of abstraction and tools that facilitate easier access, improved security, and better management of API ecosystems. This relieves developers from the intricacies of API inconsistencies, allowing them to focus more on core product functionality. Unified.to has built an award-winning real-time unified API platform with 160+ pre-built integrations spanning 12 API categories, including accounting, e-commerce, payment, and CRM, offering a promising future for API integration.

To learn more about API design or the stats referenced in this article, download the 2024 State of SaaS APIs.