Types of API — HTTP API

Despite the large number of rules and recommendations described in the HTTP specification, they're still not enough to build a full-fledged API. There are many questions that HTTP doesn't answer:

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

That's why it's not enough to build a good API, you need additional conventions. Over the lifetime of the Internet, many API standards have been created. Among them, you can distinguish several large trends, which are built on roughly the same rules. We'll look at them below.

As you have to

This is where all the APIs that work according to the principle of "you get what you get". They're usually found in internal services or old public services created dozens of years ago. There are no rules here, each endpoint exists by itself, they actively use request parameters and ignore features of HTTP itself, such as response codes. This list is only there to show that the real world is not as beautiful as we'd like it to be.

REST

The REST architectural style, which was embedded in HTTP itself (one of the creators of HTTP is the creator of REST). Without going into details, we can say that the API built on this principle, and makes full use of the capabilities of HTTP. Such an API relies heavily on headers, response codes, and properly created endpoints. For example, https://dummyjson.com/ is built on REST principles. I.e., we can say that the general idea of REST is to use the features inherent in HTTP for API design. Example:

However, REST does not answer the questions that were 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 peculiarities that are unique to it, such as how errors are handled and what structure the returned data has.

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 (transport), but, by itself, is not part of the API. Typically, RPC APIs work with a single endpoint, such as /rpc, to which a GET or POST is sent. RPC APIs use a small number of headers and response codes. Error handling and the execution of different actions are all embedded in the very body of the request and response in RPC.

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

For example, a JSON-RPC query looks like JSON, which specifies which “function” with which parameters should be called:

{
  "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 greatly from each other. Among the most famous are NFS, SOAP, XML-RPC, JSON-RPC, gRPC, GraphQL.

---

Are there any more questions? Ask them in the Discussion section.

The Hexlet support team or other students will answer you.

About Hexlet learning process

• Article “How to Learn and Cope with Negative Thoughts“
• Article “Learning Traps“
• Article “Complex and simple programming tasks“