Understanding RESTful APIs: A Guide to Implementation and System Design

REST is the most common communication standard between computers over internet.

What is it? Why is this so popular?

Api stands for application programming interface. It's a way for two computers to talk to each other. The common api standard used by most mobile and web applications to talk to the servers is called REST

REST stands for REpresentational State Transfer

Rest is not specification. It is a loose set of rules which has been the common standard for building web API since the early 2000s. An API that follows the REST standard is called RESTful API.

Basics of REST:

A RESTful api organizes resources into a set of unique URIs (Uniform resource identifiers). The uri differentiate different types of resources on a server.

https://unisala.com/api/v3/products
https://unisala.com/api/v3/users

• /api/v3/products represents the products resource.
• /api/v3/users represents the users resource.

Noun-Based Design:

The resources should be grouped by NOUN & not verb.

RESTful APIs should organize resources by nouns, not verbs. This aligns with the idea that APIs represent entities or objects (resources) rather than actions. Each resource corresponds to a real-world entity.

Some of the correct and incorrect apis designs

Example:

• Correct: /products, /users, /orders
• Incorrect: /getProducts, /createUsers, / deleteOrders

Why Use Nouns?:

1. Resources are entities that clients can act upon using standard HTTP methods (verbs) like GET, POST, PUT, DELETE.
2. HTTP methods define the action, so including verbs in the URI is redundant.

A client interacts with a resource by making a request to the endpoint for the resource over HTTP. The request has a very specific format:

In the body of these request, there could be an optional HTTP request body that contains custom payload of data, usually encoded in JSON.

HTTP Method    Action                 Example URI
-------------------------------------------------
GET            Retrieve a resource    /products
POST           Create a new resource  /products
PUT            Update a resource      /products/123
PATCH          Modify a resource      /products/123
DELETE         Remove a resource      /products/123

The server receive the request then processes it, then format the result into a response.

The first line of the response contains the HTTP status code to tell the client what happened to the request.

A well implemented restful api returns a proper HTTP status codes.

1. 200-299 level code means request was successful.
2. 200 OK: Request succeeded
3. 201 Created: Resource was successfully created
4. 204 no content: Request succeeded, no content.
5. 400 level code means something wrong with our request:
6. 400 Bad Request: Incorrect syntax in the request
7. 401 unauthorized: Authentication needed or failed
8. 404 Not Found: Resources does not exist
9. 409 Conflict: Request conflicts with server state.
10. 500 level means something wrong at the server level.
11. 500 Internal server error: Generic server error
12. 503 Service Unavailable: Server is overloaded.

Idempotent vs. Non-Idempotent Requests

Idempotent means making the same request multiple times doesn’t change the result or state.

Example: Updating a user profile (PUT) repeatedly with the same data doesn’t change anything beyond the first update.

A well behaved client could choose to retry a failed request with a 500 level status code. In RESTful APIs, the behavior of retrying failed requests (e.g., those with a 500 level status code) depends on whether the HTTP method is idempotent or non-idempotent.

HTTP_Method  Idempotent?  Explanation
----------------------------------------------------------
GET        Yes      Fetching  does not change its state.
PUT        Yes      Updates a resource; DELETE     Yes      Deleting a resource multiple times results 
POST       No       repeated requests can create duplicates.

The response body is optional and could contain the data payload that are usually formatted in JSON.

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 123

{
    "id": 1,
    "name": "Sample Product",
    "price": 19.99
}

Critical Attributes of REST

1. A rest implementation should be stateless
2. two parties don't need to store any data about each other.
3. Every request and response is independent from all others.
4. This leads to web application that are easy to scale and well behaved.
5. If an api returns an huge amount of data use pagination.
6. limit & offset , if not provided server should store default
7. Versioning or API:
8. Versioning allows an implementation to provide backward compatibility.
9. If we introduce breaking changes from V1 -> V2, consumers can get enough time to move to the next version.
10. 1 way to version an api is to prefix it:

/v1/products
/v2/products

RESTful APIs are widely used because they are simple, standardized, and effective, making them a good fit for many use cases. However, they may not always be the best choice depending on the needs of different companies.

Limitations of RESTful APIs:

1. Lack of flexibility in Responses:
2. The server defines the structure and content of responses.
3. Which often leads to clients receiving extra, unnecessary information.
4. This increase the payload size & makes data fetching less efficient.
5. With REST, every feature needs its own endpoint (e.g., /users, /users/123/posts, /comments), which makes managing and maintaining multiple APIs complex.

In contrast, GraphQL uses a single entry point, like /graphql, to handle all queries and mutations. This not only reduces the complexity of managing multiple endpoints but also provides flexibility for clients to request exactly the data they need, nothing more or less.

At Unisala, this was the main reason we transitioned from RESTful APIs to GraphQL. It allowed us to reduce the complexity of managing multiple endpoints while giving clients the flexibility to request exactly the data they need.

These notes were taken from the ByteByteGo. All credit goes to ByteByteGo.