REST is a software architecture to build web-based APIs that other applications can access. Developed by computer scientist Roy Fielding, REST refers to Representational State Transfer. A REST API is an advanced web-based interface that facilitates seamless communication and data exchange among disparate software systems using well-defined rules and protocols.
REST APIs capitalize on the core principles of REST architecture to enable smooth interoperability between software systems. They use HTTP methods for CRUD operations on resources, provide a uniform interface for clients, and are stateless, making them easy to scale and maintain.
REST APIs are flexible as they permit users (clients) to communicate with servers, even if different servers host them. Defining a server and client is the first step to understanding the client-server mandate. Servers are machines that provide services to other devices, while clients are remote systems that use services from a server. The REST protocol allows two systems to work independently.
When the REST design rule is combined with an API, we call it a RESTful API. RESTful APIs use the HTTP protocol and its methods to define resources and operations that can be performed on those resources. This design principle makes REST APIs simple, lightweight, and scalable.
The proliferation of application programming interfaces (APIs) within organizations, known as API sprawl, presents challenges if not properly managed. The rise of microservices architectures and cloud adoption has contributed to the exponential growth of APIs. A 2020 study by 451 Research found that large enterprises now average over 15,000 APIs each, with projections that this number could reach 1 billion globally by 2030.
Key concepts of REST APIs
1. Resources
These are the fundamental elements of a REST API, encompassing any object, datum, or entity within the application, such as users, products, or orders. Each resource is assigned a distinct URL, referred to as the resource's Uniform Resource Identifier (URI).
HTTP Methods: REST APIs employ standardized HTTP methods to interact with resources. The most frequently used methods include:
GET: Retrieve a resource or an array of resources.
POST: Generate a new resource.
PUT: Modify an existing resource.
DELETE: Eliminate a resource.
PATCH: Implement partial modifications to a resource.
2. Stateless
REST APIs maintain a stateless nature, and the client and server communication is stateless. This implies that each request from a client to the server must encompass all requisite information for processing. The server is not responsible for retaining data about the client's state between requests. RESTful APIs do not cache anything about the HTTP request made on the client side. A server does not store any authentication details of any prior session by the same client. Because a REST API is stateless, a client must provide all the necessary information every session to enable a server to complete a task.
3. Cacheable
REST APIs utilize caching to enhance performance. Clients can cache responses for subsequent requests, reducing server load and expediting overall response times. A RESTful API's servers determine whether the information is cacheable or non-cacheable.
4. Client-Server Architecture
REST APIs adhere to a client-server architecture, wherein the client manages the user interface and user experience, while the server oversees request processing, resource administration, and business logic enforcement. The REST protocol allows for independent implementation for the client and the server. This independence means that both parties can make changes without knowing or interacting with one another.
5. Layered System
The REST architecture may comprise multiple layers, each entrusted with specific responsibilities. This separation of concerns fosters superior maintainability, scalability, and adaptability.
6. Content Negotiation
REST APIs facilitate content negotiation, enabling clients to determine their preferred data format from the server (e.g., JSON, XML). This feature empowers the API to accommodate diverse clients with varying data format requirements.
A REST API Example
REST APIs have become the preferred choice for developers when designing interoperable web applications. REST APIs are widely used in web and mobile applications due to their simplicity, scalability, and flexibility. They offer a standardized way of accessing and manipulating resources using HTTP. However, designing and implementing a REST API requires careful consideration of resource design, URI structure, and error handling.
Resources can be any data entity represented as a collection of properties and attributes, such as an image, a user, a credit card, or other objects. Each resource is assigned a unique URI (Uniform Resource Identifier) identifier in a REST API. The operations that can be performed on a resource are defined by the HTTP methods (GET, POST, PUT, DELETE, etc.) that can be used on the resource's URI.
For example, if we have a resource representing a list of users, we can perform different operations on that resource by sending requests to the URI representing that resource. We can send an HTTP GET request to the URI to retrieve a list of users. To add a new user to the list, we can send an HTTP POST request to the same URI with the necessary user data in the request body.
RESTful API example for Credit Card Resource:
- To retrieve a list of credit cards from a server, we can send an HTTP GET request to the URI representing that resource:
`GET http://api.example.com/credit-cards`
- To retrieve information about a specific credit card, we can send an HTTP GET request to the URI representing that credit card's resource:
`GET http://api.example.com/credit-cards/1234567890123456`
- To add a new credit card to the list, we can send an HTTP POST request to the same URI with the necessary credit card data in the request body:
`POST http://api.example.com/credit-cards { "card_number": "1234567890123456", "expiration_date": "12/23", "cvv": "123", "name_on_card": "John Doe" }`
- To update the information of an existing credit card, we can send an HTTP PUT request to the URI representing that credit card's resource with the updated data in the request body:
`PUT http://api.example.com/credit-cards/1234567890123456 { "card_number": "1234567890123456", "expiration_date": "12/24", "cvv": "456", "name_on_card": "Jane Doe" }`
- To delete a credit card, we can send an HTTP DELETE request to the URI representing that credit card's resource:
`DELETE http://api.example.com/credit-cards/1234567890123456`
REST API Best Practices
As a developer working on the REST API design, you should focus on the safety and the working of API. Now that you've understood the standards of REST API, here are some of the best practices you should follow to build an effective REST API.
1. Use Nouns over Verbs in URI
It is better to prioritize nouns over verbs as a REST API is generally built for resources like services. A resource is a significant object to be referenced in itself. Use nouns to describe an entity in the REST endpoint paths. As the HTTP request methods already involve verbs, if you are to use verbs in REST endpoints, it will not draw any new information. Tags are to be used to change the state of a resource. The following are the REST verbs:
GET: To retrieve a resource
OPTIONS: To retrieve all available REST operations
POST: To create a new resource
PUT: To update or edit an existing resource
PATCH: To modify a given resource
DELETE: To delete a resource
Here are a few examples to understand the way endpoints should look like:
GET /cakes/123
DELETE /cakes/123
POST /cakes
PUT /cakes/123
PATCH /cake/123
2. Use Plural Naming Convention
When it comes to collections, it is best to use Plural nouns. A collection refers to a group of resources. This plural Naming convention will become a global code, and people can easily understand which group of APIs forms a collection. For example,
GET /cakes/123
POST /cakes
3. Make Efficient Use of Resource Nesting
Resource nesting refers to the process of clubbing two functions that are linked to each other. Nesting to one level to group the logically coherent resources is considered good. For example, for an online shop, 'order' and 'customer' are two resources in the same category. The customer places the order, and the customer owns the order.
But it would be best to use nesting sparingly, as it creates unwanted dependency problems. Limiting the nesting to one level is always considered a REST API best practice.
4. Systematic Documentation
Systematic documentation of all solutions is another important API best practice. Everything should be documented, from utilizing frameworks and applications to storage usage. The document serves as a reference while troubleshooting issues. The API documentation should be precise and, at the same time, simple for non-technical to comprehend it. With systematic documentation, users can understand all critical aspects, such as authentication, error handling, and security.
5. Data Filtering Options
Managing the database becomes a big task as it continues to grow. Retrieving only the required data from a large database is a big challenge. But, by using a filter, you can pull out the data that fits the required criteria. Bandwidth will be saved at the client's end when data is filtered while retrieving. REST API provides the following four types of filtering options:
Filtering- it will filter data that fits your conditions for required data. Parameters such as creation date, country, etc. can be searched.
Sorting- this is used to sort results in ascending or descending order.
Paging- while the 'limit' option can be used to narrow down the results to a specific number, 'offset' displays the overall results.
• Field Selection- you can request to view a particular area related to an object using field selection. An object will have many fields such as "name", "birthdate", "phone", "email" etc. So, when you're querying an object with different fields, you can specify which field you're looking for.
6. Utilize SSL/TLS security layers
Always encrypt the REST API communication using SSL/TLS, as it is crucial to ensure database security. The use of a Secure Socket Layer (SSL) and Transport Layer Security (TLS) can avoid security breaches. SSL/TLS offers public and a public key to ensure a secured connection. As TLS is an advanced version of SSL, it provides better protection.
7. Focus on Error Handling
One of the key skills of an API developer is to handle errors with care. When the API is effective, the HTTP error code shows the nature of the individual error. There are 71 unique errors in the REST API with HTTP status codes and error messages. The error handling code has three parts:
Error – identifier of the error
Message – a readable message
Detail – explanation of the message in detail
The status codes are categorized into five; they are:
Informational - ranges from 100-199 and communicates the request's state
Success – ranges from 200-299 and communicates the success of the request
Redirection- ranges from 300-399 and sends a response for additional actions required to complete a request
Client Error- ranges from 400-499 and sends error response relating to the client's end
Server Error- ranges from 500-599 and sends an error response relating to the server's end
The following are some of the common codes that developers should start with:
- 200 - OK
- 404 - Not Found
- 500 - Internal Server Error
You can build upon these if there is a need for a detailed set of statuses, such as
- 201 – Created
- 204 – No Content
- 304 – Modified
- 400 – Bad Request
- 401 – Unauthorized
- 403 – Forbidden
- 501- Not Implemented
8. Choose JSON
JavaScript Object Notation is one of the easiest languages and thus, is easy to read and work with. The key features of JSON are that it makes converting data from to other easier and supports most of the frameworks. It can be used in any programming language.
In conclusion, REST is an architectural style used in creating web services, and RESTful APIs are web services that follow its principles. They use HTTP methods for CRUD operations on resources, provide a uniform interface for clients, and are stateless, making them easy to scale and maintain.
.svg){kind=small}
.svg){kind=small}
