Types of API — HTTP API

• As you have to
• REST
• Remote Procedure Call (RPC)

We can find many rules and recommendations described in the HTTP specification, but they are not enough to build a full-fledged API. There are many questions that HTTP cannot answer:

• How do I build a URL?
• How do I work with mistakes?
• In what format and in what structure should the data be returned?
• How do I paginate?
• How do I version it?

That is why you need additional conventions to build a good API. Over the lifetime of the Internet, programmers created many API standards. You can distinguish several trends built on roughly the same rules. We will look at them below.

As you have to

It is where all the APIs work according to the «You get what you get» principle. We can find them in internal or old public services created dozens of years ago. There are no rules here. Endpoints exist by themselves. They actively use request parameters and ignore features of HTTP itself, such as response codes. We put this list there only to show that the real world is not as beautiful as we want.

REST

One of the creators of HTTP is the creator of REST, so he embedded the REST architectural style in HTTP itself. Without going into details, we can say that the API is built on these principles and makes full use of the capabilities of HTTP.

Such an API relies heavily on headers, response codes, and properly created endpoints. For example, DummyJSON works on REST principles. We can say that the general idea of REST is to use the features inherent in HTTP for API design:

However, REST does not answer the questions we asked at the beginning of the lesson. REST is an architectural style, not a specific standard. For example, in the endpoints above, we saw HTTP addresses and methods, but we know nothing about what the data will be like in the requests and responses. So, any REST API will have some unique peculiarities, such as how API handles errors and structures the returned data.

There have been attempts to create a standard that adds all the missing parts to REST. The most successful of these is jsonapi. This standard describes specific data structures for different types of queries and responses. For example, this might be what extracting a particular photo will look like:

{
  "type": "photos",
  "id": "1",
  "attributes": {
    "title": "Rails is Omakase"
  },
  "relationships": {
    "author": {
      "links": {
        "self": "/photos/1/relationships/author",
        "related": "/photos/1/author"
      },
      "data": { "type": "people", "id": "9" }
    }
  }
}

Remote Procedure Call (RPC)

RPC APIs appeared on the Internet before almost all other types of APIs. The general idea of RPC is that HTTP is treated only as a delivery method but not as a part of the API. Typically, RPC APIs work with a single endpoint, such as /rpc to which we send a GET or POST. RPC APIs use a small number of headers and response codes. Error handling and the execution of different actions are embedded in the body of the request and response in RPC.

The original idea behind RPC was that it was as if we call normal functions, and they magically make requests to an external system, hiding the existence of HTTP and the network as a whole from us.

For example, a JSON-RPC query looks like JSON, which specifies with which parameters we should call the function:

{
  "jsonrpc": "2.0",
  "method": "subtract",
  "params": { "minuend": 42, "subtrahend": 23 },
  "id": 3
}

The response will come as a result of the “function” being called:

{
  "jsonrpc": "2.0", "result": 19, "id": 3
}

There are many varieties of RPC, and they differ from each other. The most popular ones are NFS, SOAP, XML-RPC, JSON-RPC, gRPC, and GraphQL.