Skip to content

Commit 0564f2f

Browse files
anishmanandharanishmanandhar
authored
Merge pull request #6 from leapfrogtechnology/rest-api
REST API Standards (Include Best practices for Methods, Headers, Versioning, Naming convention etc)
2 parents ba2e932 + d6bc58a commit 0564f2f

File tree

14 files changed

+13641
-5
lines changed

14 files changed

+13641
-5
lines changed

‎docs/rest-api/delete.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
---
2+
id: delete
3+
title: Delete Method
4+
sidebar_label: Delete
5+
---
6+
7+
As the name applies, **DELETE** APIs are used to delete resources (identified by the Request-URI).
8+
9+
A successful response of DELETE requests SHOULD be HTTP response code 200 (OK) if the response includes an entity describing the status, 202 (Accepted) if the action has been queued, or 204 (No Content) if the action has been performed but the response does not include an entity.
10+
11+
DELETE operations are idempotent. If you DELETE a resource, it’s removed from the collection of resources. Repeatedly calling DELETE API on that resource will not change the outcome – however, calling DELETE on a resource a second time will return a 404 (NOT FOUND) since it was already removed. Some may argue that it makes the DELETE method non-idempotent. It’s a matter of discussion and personal opinion.
12+
13+
If the request passes through a cache and the Request-URI identifies one or more currently cached entities, those entries SHOULD be treated as stale. Responses to this method are not cacheable.
14+
15+
> * **/employees/{employee-id}**
16+
> * **/departments/{department-id}**
17+
18+
| Response code | Result/Reason |
19+
|---------------------------|------------------------------|
20+
|200 OK | Sucessfully deleted the Enity.|
21+
|401 (Unauthorized) | Invalid Credentials/ Invalid Authentication |
22+
|403 (Forbidden) | Invalid Authorization/ Insufficient rights/ Incorrect Role |
23+
|405 (Method Not allowed) | If API supports methods other than PUT request |
24+
|500 (Internal server error)| Server encountered an unexpected condition that prevented it from fulfilling the request.|

‎docs/rest-api/get.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
---
2+
id: get
3+
title: Get Method
4+
sidebar_label: Get
5+
---
6+
7+
Use **GET requests** to retrieve resource representation/information only – and not to modify it in any way. As GET requests do not change the state of the resource, these are said to be safe methods. Additionally, GET APIs should be **idempotent**, which means that making multiple identical requests must produce the same result every time until another API (POST/PUT/PATCH/DELETE) has changed the state of the resource on the server.
8+
9+
> * **/employees**
10+
> * **/employees/{employee-id}/leaves**
11+
> * **/employees/{employee-id}/employee-reports**
12+
13+
Use query params to filter response or get subset or limited resource.
14+
15+
> * **/employees/{employee-id}/leaves?type={leave-type}&order-by={leave-date}**
16+
17+
| Response code | Result/Reason |
18+
|---------------------------|------------------------------|
19+
|200 OK | Sucessfully Fetched the Enity. <br/> Must include a response body. |
20+
|404 (Not found) | If Entity not found for given ID or is invalid ID|
21+
|405 (Method Not allowed) | If API supports methods other than GET request |
22+
|401 (Unauthorized) | Invalid Credentials/ Invalid Authentication |
23+
|403 (Forbidden) | Invalid Authorization/ Insufficient rights/ Incorrect Role |
24+
|410 (Gone) | Expired link/Server no longer serve this request.|
25+
|500 (Internal server error)| Server encountered an unexpected condition that prevented it from fulfilling the request. |

‎docs/rest-api/hateaos.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
id: hateaos
3+
title: HATEAOS
4+
sidebar_label: HATEAOS
5+
---
6+
7+
#### HATEAOS

‎docs/rest-api/headers.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
---
2+
id: headers
3+
title: Headers Best Practices
4+
sidebar_label: Headers
5+
---
6+
7+
#### The following convention should be followed for REST API Headers
8+
9+
* Headers names should be **noun** and should be **Captialised-Case** separated by **(-)**. e.g **Token-Key**, **Account-ID**, **Tenant-ID** etc
10+
11+
* For cases like Acronym, use acronyms itself. eg. *PID-value*, *PIN*
12+
13+
* Headers can be used for meta information that the API carries for e.g
14+
* Authentication
15+
* Authorization
16+
* Versioning the API
17+
* Content-Type
18+
* Caching etc
19+
* <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers" target="_blank">More Examples</a>
20+
21+
* Avoid using headers for business logic
22+
23+
* Use headers for parameters that should not appear in the URL
24+
* for e.g https://api.application.com/users/{id}/fetch?apiKey=abcd123456789 //**BAD Practice**

‎docs/rest-api/naming-convention.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
---
2+
id: naming-convention
3+
title: Naming Convention
4+
sidebar_label: Naming Convention
5+
---
6+
7+
In REST(**REpresentational State Transfer**), primary data **representation** is called **Resource**. Having a strong and consistent REST resource naming strategy – will definitely prove one of the best design decisions in the long term.
8+
9+
* Use **noun** and **hyphenated-lower-case** for CRUD operations to an entity/resource/document. The **GET/POST/PUT/DELETE/PATCH** requests represents the corresponding CRUD operation for the following resources like employees, reports, leaves.
10+
11+
> * **/employees**
12+
> * **/employees/{employee-id}/leaves**
13+
> * **/employees/{employee-id}/employee-reports**
14+
15+
* For cases of executable functions besides a basic CRUD operations, use **verb** and **hyphenated-lower-case**.
16+
17+
> * **/customer/{customer-id}/check-validity**
18+
> * **/customer/{customer-id}/cart/checkout**
19+
20+
* Use forward slash (/) to indicate hierarchical relationships
21+
22+
> **/customers/{customer-id}/accounts/{account-id}/balance**
23+
> **/category/{cateogry-id}/products/{product-id}/balance**
24+
25+
* Do not use trailing forward slash (/) in URIs
26+
27+
> * **/employees** //Good practice
28+
> * **/employees/{employee-id}/leaves/** //Bad practice
29+
30+
* Use hyphens (-) to improve the readability of URIs
31+
32+
> * **/employees/{employee-id}/employee-reports** //Readable
33+
> * **/customer/{customer-id}/check-validity** //Readable
34+
>
35+
> * **/employees/{employee-id}/employeeReports** //Less Readable
36+
> * **/customer/{customer-id}/checkValidity** //Less Readable
37+
38+
* Do not use file extentions and underscores
39+
40+
> * **/employees/{employee-id}/employee-reports.pdf** /*Bad Practice*/
41+
> * **/employees/{employee-id}/employee_reports** /*Bad Practice*/
42+
43+
* Never use CRUD function names in URIs
44+
45+
URIs should not be used to indicate that a CRUD function is performed. URIs should be used to uniquely identify resources and not any action upon them. HTTP request methods should be used to indicate which CRUD function is performed.
46+
47+
> * GET Request **/employees** // Get all employees
48+
> * POST Request **/employees** // Create new employees
49+
> * GET Request **/employees/{employee-id}** // Get one employee with given id
50+
> * PUT Request **/employees/{employee-id}** // Update one employee with given id
51+
> * DELETE Request **/employees/{employee-id}** // Delete one employee with given id

‎docs/rest-api/patch.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
id: patch
3+
title: Patch Method
4+
sidebar_label: Patch
5+
---
6+
7+
#### The following convention should be followed for Patch

‎docs/rest-api/post.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
id: post
3+
title: Post Method
4+
sidebar_label: Post
5+
---
6+
7+
Use **POST requests** to create new subordinate resources, e.g., a file is subordinate to a directory containing it or a row is subordinate to a database table. Talking strictly in terms of REST, POST methods are used to create a new resource into the collection of resources.Note that POST is **neither safe nor idempotent**, and invoking two identical POST requests will result in two different resources containing the same information (except resource ids).
8+
9+
> * **/employees**
10+
> * **/departments**
11+
12+
| Response code | Result/Reason |
13+
|---------------------------|------------------------------|
14+
|201 (Created) | Sucessfully Created the Enity. <br/> Must include a response body. |
15+
|202 (Accepted) | Actions that take a long while to process/ Batch/Queue Oriented Process |
16+
|204 (No Content) | When the REST API declines to send back any status message or representation in the response message’s body. Must not contains the response body|
17+
|401 (Unauthorized) | Invalid Credentials/ Invalid Authentication |
18+
|403 (Forbidden) | Invalid Authorization/ Insufficient rights/ Incorrect Role |
19+
|400 (Bad Request) | Bad request object | validation error |
20+
|405 (Method Not allowed) | If API supports methods other than POST request |
21+
|500 (Internal server error)| Server encountered an unexpected condition that prevented it from fulfilling the request.|

‎docs/rest-api/put.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
id: put
3+
title: Put Method
4+
sidebar_label: Put
5+
---
6+
7+
Use **PUT** APIs primarily to update existing resource (if the resource does not exist, then API may decide to create a new resource or not). If a new resource has been created by the PUT API, the origin server MUST inform the user agent via the HTTP response code 201 (Created) response and if an existing resource is modified, either the 200 (OK) or 204 (No Content) response codes SHOULD be sent to indicate successful completion of the request.
8+
9+
> * **/employees/{employee-id}**
10+
> * **/departments/{department-id}**
11+
12+
| Response code | Result/Reason |
13+
|---------------------------|------------------------------|
14+
|200 OK | Sucessfully updated the Enity. <br/> Must include a response body. |
15+
|204 (No Content) | When the REST API declines to send back any status message or representation in the response message’s body. Must not contains the response body|
16+
|401 (Unauthorized) | Invalid Credentials/ Invalid Authentication |
17+
|403 (Forbidden) | Invalid Authorization/ Insufficient rights/ Incorrect Role |
18+
|400 (Bad Request) | Bad request object | validation error |
19+
|404 (Not found) | If ID not found or invalid|
20+
|405 (Method Not allowed) | If API supports methods other than PUT request |
21+
|500 (Internal server error)| Server encountered an unexpected condition that prevented it from fulfilling the request.|

‎docs/rest-api/security.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
id: security
3+
title: Security Method
4+
sidebar_label: Security
5+
---
6+
7+
## Best Practices to Secure REST APIs
8+
9+
* Always Use HTTPS.If you use HTTP 2, to improve performance – you can even send multiple requests over a single connection, that way you avoid the complete TCP and SSL handshake overhead on later requests.
10+
11+
* Never expose information on URLs. <https://api.app.com/users/{id}/fetch?apiKey=abcd123456789> //Bad practice
12+
13+
* Conside using token based authentication like OAUTH2
14+
15+
* Consider Adding Timestamp in Request
16+
17+
* Log each request and response data
18+
19+
* Validate and sanitize incoming requests against data types, injections

‎docs/rest-api/versioning.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
id: versioning
3+
title: Versioning
4+
sidebar_label: Versioning
5+
---
6+
7+
## Four common REST API versioning strategies
8+
9+
### Versioning through URI Path (*recommended*)
10+
11+
> <http://api.app.com/v1/products>
12+
>
13+
> One way to version a REST API is to include the version number in the URI path.This solution often uses URI routing to point to a specific version of the API. Because cache keys (in this situation URIs) are changed by version, clients can easily cache resources. When a new version of the REST API is released, it is perceived as a new entry in the cache.
14+
15+
### Versioning through custom header
16+
17+
> curl -H API-Version: 1.0” <http://api.app.com/products>
18+
>
19+
> This approach doesn’t clutter the URI with versioning information.
20+
21+
### Versioning through query parameters
22+
23+
> <http://api.app.com/products?version=1>
24+
>
25+
>Another option for versioning a REST API is to include the version number as a query parameter.
26+
27+
### Versioning through content negotiation
28+
29+
> curl -H “Accept: application/vnd.xm.device+json; version=1” <http://api.app.com/products>
30+
>
31+
>The last strategy we are addressing is versioning through content negotiation.
32+
>
33+
>This approach allows us to version a single resource representation instead of versioning the entire API which gives us a more granular control over versioning. It also creates a smaller footprint in the code base as we don’t have to fork the entire application when creating a new version. Another advantage of this approach is that it doesn’t require implementing URI routing rules introduced by versioning through the URI path.
34+
>
35+
>One of the drawbacks of this approach is that it is less accessible than URI-versioned APIs: Requiring HTTP headers with media types makes it more difficult to test and explore the API using a browser.

0 commit comments

Comments
 (0)