What’s been done to improve APIs?

As APIs have developed into the now-ubiquitous web API, several efforts have been made to make their design a little easier and their implementation more useful.

A little SOAP, a lot of REST

As web APIs have spread, a protocol specification was developed to help standardize information exchange: Simple Object Access Protocol, more casually known as SOAP. APIs designed with SOAP use XML for their message format and receive requests through HTTP or SMTP. SOAP makes it easier for apps running in different environments or written in different languages to share information.

Another specification is Representational State Transfer (REST). Web APIs that adhere to the REST architectural constraints are called RESTful APIs. REST differs from SOAP in a fundamental way: SOAP is a protocol, whereas REST is an architectural style. This means that there’s no official standard for RESTful web APIs. As defined in Roy Fielding’s dissertation “Architectural Styles and the Design of Network-based Software Architectures,” APIs are RESTful as long as they comply with the 6 guiding constraints of a RESTful system:

Client-server architecture: REST architecture is composed of clients, servers, and resources, and it handles requests through HTTP.
Statelessness: No client content is stored on the server between requests. Information about the session state is, instead, held with the client.
Cacheability: Caching can eliminate the need for some client-server interactions.
Layered system: Client-server interactions can be mediated by additional layers. These layers could offer additional features like load balancing, shared caches, or security.
Code on demand (optional): Servers can extend the functionality of a client by transferring executable code.
Uniform interface: This constraint is core to the design of RESTful APIs and includes 4 facets:
- Resource identification in requests: Resources are identified in requests and are separate from the representations returned to the client.
- Resource manipulation through representations: Clients receive files that represent resources. These representations must have enough information to allow modification or deletion.
- Self-descriptive messages: Each message returned to a client contains enough information to describe how the client should process the information.
- Hypermedia as the engine of application state: After accessing a resource, the REST client should be able to discover through hyperlinks all other actions that are currently available.

These constraints may seem like a lot but they’re much simpler than a prescribed protocol. For this reason RESTful APIs are becoming more prevalent than SOAP.

In recent years, the OpenAPI specification has emerged as a common standard for defining REST APIs. OpenAPI establishes a language-agnostic way for developers to build REST API interfaces so that users can understand them with minimal guesswork.

Another API standard to emerge is GraphQL, a query language and server-side runtime that’s an alternative to REST. GraphQL prioritizes giving clients exactly the data they request and no more. As an alternative to REST, GraphQL lets developers construct requests that pull data from multiple data sources in a single API call.