The Comprehensive Guide to REST API Architecture and Conventions

Consider that we are interacting with multiple entities. We should build the API path as follows,

domain + /API + /Version + /Entity + /ID Parameter [Optional] + /SubEntity + /ID Parameter + ? + fromDate=01/02/2022 + & + endDate=02/02/2022

For instance, if we want to get all the items of an order, where the order ID is 17, out API should look like this,

https://mydomain/api/v1/order/17/items

Request

Let’s debug the previous URL step by step,

Few conventions,

1. The api keyword should be somewhere as follows

   1. api.mydomain.com [Preferred]

   2. mydomainapi.com

   3. mydomain.com/api

2. API should support versioning,

   1. Inside request header [Preferred]

   2. Inside URL. In this case,

      1. Version starts after the api/

      2. Version should have a prefix v

      3. Version number should be a natural number, like 1, 2, 3, etc. No decimal should be used

   3. Should not put versioning in the query parameters

3. The entity should be one word as a name, but not a verb, since the HTTP method is taking care of that

4. ID Parameter: The ID parameter should come after the entity

5. Subentity: The subentity should come after the entity

6. Query Parameters: Should come after ? and concatenated by the &

Query Parameters vs ID Parameters

1. While nothing was found in query parameters, it’s fine. However, missing ID parameters should throw an error.

2. For an entity, there could be multiple query parameters. But there should be only one ID parameter for the entity.

3. To extend, query parameters may return one to multiple entities, but if the ID parameter finds nothing, it will throw an error.

Response Code

Five Groups

• 1xx: Avoid this one, for informational purposes

• 2xx: Success

• 3xx: Avoid this one, Redirection in OS low-level

• 4xx: Client Error

• 5xx: Server Error

2XX

• 200 - Ok: Default Status Code

  • Get request, get data

  • Post request created data

• 201 - Created: On Post request, entity created

• 202 - Accepted: Request accepted and under processing on the server

• 204 - No Content: Operation completed and no entity as response

4XX

• 400 - Bad Request: Client sent a request with invalid parameters or JSON

• 401 - Unauthorized: Server does not recognize the client

• 403 - Forbidden: Server recognizes the client, but the client does not have enough permission to access the resource

• 404 - Page Not Found:

  • The resource entity was not found.

  • Entity with the ID parameter not found

  • Not Applicable when query parameters are used

5XX

• 500 - Internal Server Error: Something is wrong with the server, and the client has nothing to do with it.

JWT in REST API

JWT Token should be passed using Authorization Header with a prefix bearer

Performance

To keep up the scalability and availability,

1. Using an asynchronous mechanism for long-term operation

2. Using caching for near-frequently accessed data with expiration

3. Use a rate limit to reduce the maximum concurrent requests

4. Rate limit for a specific user

Metrics to Monitor

1. Request/sec

2. Failure ratio

3. Latency between request and response

4. Memory, CPU Utilization

5. Users, sessions, geolocation distribution

HATEOAS

Stands for, Hypermedia as the Engine of Application State. The user should not have prior knowledge of resources. Other relevant resource links should be included in the response.

Spider Web

If the URL of one service is changed, all other services calling that service will go down. To resolve this, we can use Yellow Page Directories, where the service and mapping will be stored. Also, it is possible to use an Gateway as a middleman, it will handle the URL mapping of a specific service.