REST API, or how to create a convenient web service

The term REST was coined in 2000 by Roy Fielding, one of the creators of the HTTP protocol. Today the REST API is used everywhere to transfer data between the client and the server.

What is REST API?

So, what is a Restful API and what are its advantages? REST API is a composite of two acronyms:

API is an Application Programming Interface; this is an interface used to make one program work with another.

REST is Representational State Transfer, a way to build an API architecture using HTTP.

The REST API is responsible for the interactions between the server and the client application. In simple terms, the REST API is used whenever a website or application user needs to get resources from the server.

HTTP is the basis of REST services because this protocol is implemented in all kinds of programming languages, as well as all operating systems, and is universal. With HTTP, it is possible to provide a user with a specific resource using its URI.

A resource is something that needs to be shown to the client. For example, we created an application with lists and descriptions of cafes in the country. A resource can be a list of all the cities in the application.

Resource representations consist of data; metadata describing the data, and hypermedia links to the next desired state.

The URI is a universal resource identifier. For example, http://allcafes.com/cities, where the first part (http://allcafes.com) is the site or server address and the second (/cities) is the address of the resource on the remote server.

The main principles

There is no specific standard for the REST API, but there are several principles to keep in mind, particularly in creating interface code.

• Client-Server. This is the concept of the separate operation of the server and the client. In other words, it's possible to change the application without affecting the data structure on the server or to edit the database on the server without affecting the client application.
• Stateless. Requests can be executed independently, and each request contains the data needed to successfully provide resources to the user. The server should not store data about client operations.
• Cache. The server operation can be overloaded while processing many incoming and outgoing requests. So the REST API must be able to cache data (then the user can return to this data buffer for repeated requests).
• Uniform Interface. Having a uniform interface allows you to establish a more stable operation (for example, through the use of HTTP).
• Layered System. REST APIs have different levels within their architecture, which allows for placing different servers on different levels. With this approach, it is possible to control, for example, the response speed of more important servers. This kind of system enables you to significantly increase the level of security.
• Code on Demand. Providing code on demand allows you to pass it through the API for use in the application.

Advantages

The benefits of the REST API and the popularity of its use are based on the principles of its work.

Working with the REST API, you get scalability. This is possible thanks to the principle of separating the client and the server.

The flexibility of the REST API is ensured due to the use of HTTP and the ability to work with any programming language, in any operating system. The created API architecture enables handling of any type of request and data format.

Using the cache can improve performance because it will reduce the number of requests to be processed.

Reliability and security in REST APIs come from the layered system. It allows you to stop attacks at different levels, preventing them from penetrating the entire server architecture. For example, critical or most vulnerable elements of the API architecture can be stored behind the firewall.

Despite these advantages, SOAP, GraphQL, and RPC are trying to take REST's place. SOAP, invented before REST, and RPC, which has several versions, are more prevalent in narrow areas. But GraphQL is considered to represent good progress in this area for more complex projects.

How does RESTful API work?

The operation of the RESTful API is similar to that of any website on the Internet. A user (client) communicates with the server using the API when he needs some web resource.

Step by step, the work of RESTful API can be described as follows:

1. The user sends a request to the server. According to the API documentation, the client application modifies this request so that the server receives the information necessary for processing.
2. The server authenticates the client and confirms that the client is authorized to make this request. If authentication fails, a 403 error is returned.
3. The server receives the request in the right form and processes it.
4. Then the server returns the response to the client. The response contains information about the success of the command and the requested resource.

HTTP commands are used to work with resources through the REST API:

• GET is used to get some data: GET /cities will return a list of all cities for which cafe addresses are collected.
• DELETE is used to delete data: DELETE /istanbul will delete cafes in Istanbul from the list that have been closed.
• POST is used to add new data or replace old data: POST /ankara will add a new cafe address in Ankara.
• PUT is used to edit data: PUT /cities can be used to make edits to the list of cities represented in the application.

After the completion or failure of any command, the user receives a response beginning with a certain number. For example, a code starting with 2 means the successful performance of the command, 500 - server error, and codes with the number 4 in the beginning indicate the cause of the error (401 Unauthorized - unsuccessful authorization, 404 Not found - requested a non-existent resource, etc.).

Best practices for building REST API

The OpenAPI specification, or REST API development best practices, allows any developer to understand API architecture parameters and capabilities. Specialists share their experiences on the Internet.

• Use kebab-case for URL

Bad: /cafeKahve or /cafe_Kahve

Good: /cafe-Kahve

• Use plural for collections

Bad: DELETE /city or DELETE /City

Good: DELETE /cities

• The URL must begin with the collection and end with the URI

Bad: GET /cafe/:cafeId/group/:groupId/price

Good: GET /cafes/:cafeId/ or GET /group/:groupId

• Use verbs in operations, not in resource URLs

Bad: POST /updatecafe/{cafeId} or GET /getcafes

Good: PUT /cafes/{cafeId}

• Use special tools to develop REST APIs

For example, API Blueprint and Swagger.

• Ensure security

Use HTTPS for all resources and services.

• Use status codes while processing errors

We recommend using standard HTTP status codes. HTTP codes make it easier to know what caused the error.

• Use filtering and sorting

The API database can become quite large and without proper sorting, processing and finding the right resource will take a long time.

More REST API practices can be found here.