Before I start about REST API, let me introduce what an API is.

API - Application Programming Interface. Still nothing ;)?

Interface definition

An interface is a type of connection that allows communication. We distinguish among others:

• user interface (UI),
• programming interface (API),
• physical interface (USB, ETHERNET, LPT, COM).

What is API?

An API is a way of communicating between different pieces of software and different software. Eg HubSpot, SalesForce and Google Maps.

What is Web API?

Web Application Programming Interfaces - a type of web application programming interface that uses the architecture and Web protocols (in particular the HTTP protocol) for communication between applications.

Designing a logical and easy-to-use API is very difficult. The lack of standardization does not make the task easier.

URI address or endpoint It is the endpoint of the API communication channel.

For example, the structure of an endpoint returning a list of companies might look like this:

GET /companies/all
GET /getallbcompanies
GET /companies?all=true

REST - this is a standard that defines the principles of API design. In the case of Web API, it is based on the HTTP protocol.

Popular CRUD actions (Create, Read, Update, Delete) correspond to POST, GET, PUT, DELETE methods.

REST API example:

GET /companies //returns a list of companies

POST/companies //saves a new company

PUT/companies/:id //updates the company with the given id

DELETE/companies/:id //removes the company with the given id

What is an asset?

It is an abstract concept. Any information that has a name and meets the criteria below is a resource.

It is a noun It is unique It can be presented in the form of data Has at least one URI address

E.g . the resource can be a "Andrew's friend car" or a definition of the word "wisdom".

We use resources when interacting with the API. Understanding what a resource is will allow you to better use and work with the API.

Resource naming

Resources must be designed to be disconnected from the action.

Using nouns instead of verbs.

Singular or plural?

This is a highly controversial and contradictory rule. On the other hand, using the plural for resources makes the API easier to read.

The resource can be a single document as well as a list of documents.

For example, the "users" list is a collection of individual "user" resources.

Sample collection address:

/api/users

Sample resource address:

/api/users/:id

Address structure

/api/users/:id/comments

In this case, the endpoint should return the comments of the user with the given identifier

/api //entry point
/users //resource collection
/:id //resource ID
/comments //sub-collection

Relationships between resources

Relationships can develop between the resources that affect the URL structure. As above, the resource/users/: id can have a relationship with the resource/comments

Filtering data

If you only want to retrieve selected resource information, the API should allow you to both sort and filter resources. Instead of creating another, additional endpoint, we can use a query string.

Address parameters (query string)

/api/v1/users?fields =name,phone

Data representation

We can present the resource with the help of data. The most popular data format used and the REST API is JSON. The flexibility of this format allows you to transfer arrays, objects and strings.

Good✅

GET /companies
POST /companies
DELETE /companies

Wrong❌

GET /getcompanies
POST /addcompany
DELETE /companies/delete

Good practices

• Use lowercase letters
• Use hyphens
• Don't add the final slash

6 REST rules:

1. Uniform Interface

The interface should provide standardized communication between the client and the server.

2. Client-Server

A clear, marked division between the application running on the client and server-side.

3. Stateless

Each query must have a complete set of information necessary for its correct completion.

4. Cacheable

The API should support data caching to improve performance.

5. Layered System

The system should be designed in such a way that the client, by sending a query, can get an answer without having to know what is happening on the server.

6. Code On Demand

Provides the ability to send a code that can be executed on the client's side. In response, the server returns a piece of code (eg JavaScript) that the client can use in any way.

HTTP methods

The HTTP method is part of the HTTP request. It is responsible for determining the action to be taken.

The most popular HTTP methods:

GET //reads the given resource. It only has to return data.
POST //sends data to the indicated resource.
PUT //updates the entire resource with the transferred data.
DELETE //Deletes the identified resource or collection of resources.