Types of web APIs

Learn about the different types of web APIs and their characteristics. We compare and contrast REST, SOAP, RPC and GraphQL and provide simple examples of each.

Introduction - What is REST API
Comparison of different types of APIs
API Design Best Practices
HTTP Requests and Responses
API Authentication
Is GraphQL a replacement for REST?

Most common API styles

There are several different types of web APIs in use today, each with its own strengths and weaknesses. They are all built on top of HTTP foundation but differ in design and use cases they are optimized for. The common web API types are:

  • REST (Representational State Transfer) is the most common type of web API. It is a set of architectural principles that dictate how web APIs should be designed and implemented. REST APIs are typically built using HTTP and return data in a format like JSON or XML.

  • SOAP (Simple Object Access Protocol) is another type of web API, but it is not as widely used as REST. SOAP is a protocol that uses XML to encode messages and requires the use of other protocols like HTTP or SMTP for transport.

  • RPC (Remote Procedure Call) is a type of web API that allows a client to make requests to a server and receive a response. Unlike REST and SOAP, which are designed to be flexible and easy to use, RPC is a more structured and rigid approach.

  • GraphQL is a relatively new type of web API that is gaining popularity. It is a query language that allows clients to specify exactly the data they need from the server. This makes it more efficient than other API types, as it reduces the amount of data that needs to be transferred.

REST

REST (Representational State Transfer) is an architectural style that defines a set of principles for designing web APIs. It is the most common type of web API and is widely used in web development.

REST is based on six architectural constraints, which dictate how web APIs should be designed and implemented. These constraints are:

  1. Client-server architecture: REST APIs are built using a client-server architecture, where the client makes requests to the server and the server returns a response. This allows for a clear separation of concerns and makes it easier to scale and maintain the API.

  2. Statelessness: REST APIs are stateless, which means that each request is treated as an independent action and does not depend on the state of previous requests. This makes the API more scalable and easier to manage.

  3. Cacheability: REST APIs should be designed to be cacheable, which means that responses can be stored and reused to improve performance. This allows the API to handle more requests and reduces the amount of data that needs to be transferred.

  4. Layered system: REST APIs are typically built using a layered system, where each layer has a specific role and can be added or removed without affecting the rest of the system. This allows for modularity and flexibility in the design of the API.

  5. Code on demand: REST APIs can optionally include code that can be executed by the client, such as JavaScript or Flash. This allows the API to be more flexible and adaptable to changing requirements.

  6. Uniform interface: REST APIs use a uniform interface, which means that all resources are accessed using the same set of methods and conventions. This makes the API more predictable and easier to use.

One of the major benefits of using REST-style web APIs is their flexibility. REST APIs are designed to be simple and easy to use, allowing developers to quickly build and integrate them into their applications. They are also built using HTTP, which is a widely supported and well-understood protocol.

Another benefit of REST APIs is their ability to support a wide range of data formats, including JSON and XML. This makes them compatible with a wide range of applications and technologies.

Example of a REST call to a fictional weather service:

GET /weather?zipCode=90210 HTTP/1.1
Host: www.example.com

And the response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "temperature": 72,
  "conditions": "sunny"
}

Despite these benefits, there are also some shortcomings of using REST-style web APIs. One of the main drawbacks is that they can be difficult to design and implement properly. It is important to follow the architectural principles of REST to ensure that the API is efficient and scalable.

Another shortcoming of REST APIs is that they can be difficult to secure. Since they use HTTP, it is possible for malicious actors to intercept and manipulate data being sent and received. Proper authentication and security measures need to be in place to prevent this from happening.

While the guide explains REST in depth, in this article we'll compare it with other popular types of APIs on the internet.

SOAP

SOAP (Simple Object Access Protocol) is a protocol that is used to communicate between web services. It uses XML to encode messages and requires the use of other protocols like HTTP or SMTP for transport.

SOAP is typically used in enterprise environments where web services need to be accessed by different applications and platforms. It is self-describing, which means that it includes metadata that describes the data being exchanged. This metadata is typically defined using WSDL (Web Services Description Language), which is an XML-based language that defines the operations and parameters of a web service.

Here is an example of a SOAP request to the /weather endpoint of example.com service:

POST /weather HTTP/1.1
Host: www.example.com
Content-Type: application/soap+xml; charset=utf-8

<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
               xmlns:w="http://www.example.com/weather">
  <soap:Header>
    <w:RequestAuth>
      <w:Username>user1</w:Username>
      <w:Password>password</w:Password>
    </w:RequestAuth>
  </soap:Header>
  <soap:Body>
    <w:GetWeather>
      <w:ZipCode>90210</w:ZipCode>
    </w:GetWeather>
  </soap:Body>
</soap:Envelope>

One of the advantages of SOAP is that it is a well-established and standardized protocol, which means that it is widely supported and has a large developer community. It is also flexible and extensible, which allows it to be used in a variety of different scenarios.

However, SOAP is not as widely used as other web API types like REST. It can be more complex and difficult to use, and is not as efficient as other approaches. It also requires the use of other protocols for transport, which can add complexity and overhead.

RPC

RPC (Remote Procedure Call) is a style of web API that allows a client to make requests to a server and receive a response. It is based on the idea of calling a remote procedure, or function, on the server and receiving a response.

XML-RPC is a popular implementation of the RPC style of API. It uses XML to encode messages and HTTP for transport. XML-RPC is simple to use and allows for easy integration with other systems and languages. A variant called JSON-RPC behaves in a similar way but uses JSON for the message format.

An typical JSON-RPC request looks like this (note the protocol version, method, and parameters in the payload):

POST /rpc HTTP/1.1
Host: www.example.com
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "method": "getWeather",
  "params": {
    "zipCode": 90210
  },
  "id": 1
}

gRPC is another popular implementation of the RPC style of API. It uses a binary encoding format and supports multiple languages and platforms. gRPC is faster and more efficient than XML-RPC and is commonly used in high-performance systems.

The main advantage of the RPC style of API is its simplicity and predictability. It is a more structured and rigid approach, which makes it easy to understand and use. However, this also means that it is less flexible and adaptable than other API styles.

GraphQL

GraphQL is a query language for APIs that was developed by Facebook. It provides an alternative to REST, allowing clients to query data in a more flexible and powerful way. Unlike REST, where the structure of the API is defined by the server and clients have to adapt to it, with GraphQL the client can specify the exact data it needs and the server will return only that data. This can make it easier for clients to work with the API, since they don't have to worry about the underlying structure of the data.

One of the main benefits of GraphQL is that it allows for more efficient data fetching, since the client can specify exactly what data it needs in a single request. This can reduce the number of round trips to the server and improve performance. In addition, GraphQL provides a type system that allows clients to verify that they are getting the data they expect, which can help prevent errors.

GraphQL schema definition for a fictional weather service:

type Query {
  weather(zipCode: Int!): Weather
}

type Weather {
  temperature: Int
  conditions: String
}

A request to this service would looks like this:

POST /graphql HTTP/1.1
Host: www.example.com
Content-Type: application/json

{
  "query": "{ weather(zipCode: 90210) { temperature, conditions } }"
}

Some of the drawbacks of GraphQL include a steeper learning curve, since it requires clients to learn a new query language, and the fact that it can be more difficult to cache data with GraphQL than with REST. Additionally, some critics argue that the flexibility of GraphQL can make it harder to design and maintain a consistent API.

Overall, GraphQL provides some advantages over REST, particularly in terms of flexibility and efficiency, but it may not be the right choice for every situation. It's important to evaluate the needs of your specific application and choose the architecture that best meets those needs.