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
POST/companies
PUT/companies/:id
DELETE/companies/: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
/users
/:id
/comments
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
POST
PUT
DELETE
