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,
The api keyword should be somewhere as follows
api.mydomain.com [Preferred]
mydomainapi.com
mydomain.com/api
API should support versioning,
Inside request header [Preferred]
Inside URL. In this case,
Version starts after the api/
Version should have a prefix v
Version number should be a natural number, like 1, 2, 3, etc. No decimal should be used
Should not put versioning in the query parameters
The entity should be one word as a name, but not a verb, since the HTTP method is taking care of that
ID Parameter: The ID parameter should come after the entity
Subentity: The subentity should come after the entity
Query Parameters: Should come after ? and concatenated by the &
Query Parameters vs ID Parameters
While nothing was found in query parameters, it’s fine. However, missing ID parameters should throw an error.
For an entity, there could be multiple query parameters. But there should be only one ID parameter for the entity.
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
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
To keep up the scalability and availability,
Using an asynchronous mechanism for long-term operation
Using caching for near-frequently accessed data with expiration
Use a rate limit to reduce the maximum concurrent requests
Rate limit for a specific user
Metrics to Monitor
Request/sec
Failure ratio
Latency between request and response
Memory, CPU Utilization
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.
