REST API Design

• REST (REpresentational State Transfer) is basically an architectural style of development having some principles.
  • It should be stateless
  • It should access all the resources from the server using only URI
  • It does not have inbuilt encryption
  • It does not have session
  • It uses one and only one protocol that is HTTP
  • For performing CRUD operations, it should use HTTP verbs such as get, post, put and delete
  • It should return the result only in the form of JSON or XML, atom, OData etc. (lightweight data )

• REST based services follow some of the above principles and not all.
• RESTFUL services means it follows all the above principles.
  • It is similar to the concept of:
    • Object oriented languages supports all of OOPs concepts.
      • examples: Java, C++
    • Object-based languages supports some of OOPs concepts.
      • examples: JavaScript, VB

APIs are interfaces which allows services to expose their endpoint for other service to inter-operate. There is no backend calls to service’s resource (such as accessing DB directly).

Design Considerations

• Determine data exchange format (JSON or XML)
• Use noun (eg: /products) for endpoint and verb (see HTTP methods) for doing operations.
• Use HTTP methods
  • GET
  • POST
  • PUT is idempotent (need to provide complete input-entity in the request and multiple requests will have the same effects)
  • PATCH is non-idempotent (need to provide particular part (patching) of input-entity either to add, update or delete in the request and multiple requests will have the different effects)
  • DELETE
• Use appropriate HTTP status codes
  • 100 – Informational response
  • 200 – Success
  • 300 – Redirection
  • 400 – Client error
  • 500 – Server error
• Provide versioning with backward compatibility
• Use query and filter
  • Eg: Use GET query-param to query (like /products?name=’ABC’) and filter (/products?category=clothing&sex=male) the endpoint.
• Use pagination (limit and offset query-params)
• Provide appropriate error message with reason for failure.

Idempotency

• Idempotent means repeatable-> you repeat, produces same result.
  • GET, PUT, DELETE (every call of same request, returns same response).
  • GET, PUT, DELETE ops will provide same result irrespective of number of requests until there is a change.
• Non-Idempotent means non-repeatable-> you repeat, produces different result.
  • POST (every call of same request, returns different response)
  • Every POST request, actually create a new entry in the backend.
• PATCH is neither Idempotent nor Non-Idempotent
  • Based on operation, it become Idempotent nor Non-Idempotent
  • Idempotent scenario: PATCH request with appId (to identify a resource) and partnerProviderID (to change the value), will result in change of partnerProviderID. When you do this ops multiple times, produces same result (i.e., change in partnerProviderID).
  • Non-Idempotent scenario: PATCH request with appId (to identify a resource and also to change its value), will result in change of appId first time, but consecutive request fails (because fail to identify the app). When you do this ops multiple times, produces different result (first time the request changes the appID and second time, the request fails).