Rest API Design Reference
REST stands for Representational State Transfer. It is an architectural style for developing software.
Uniform interface
Client–server
Stateless
Cacheable
Layered system
Code on demand
Uniform interface
Uniform interface suggests that the resource in a system to have only one logical URI and
Then provide additional information to retrieve the related data. For instance we can provide
Links for related resources like child objects, parent objects etc.
User of one API end point should be able to identify and work similarly with other Resources.
Also, the resource representations across system should follow certain guidelines
such as naming conventions, link formats or data format, filter formats pagination formats etc.
All resources should be accessible in similar way and should use similar status codes.
Client–server
Server should not depend on previous client state to serve next request.
Each request should be independent
of any state set in the server by previous requests.
If we replace the server with a different server serving same API’s then the Client should be work.
This is only possible if the API’s are consistent and follows same standard for all endpoints.
This way we can use load balancer to switch the server serving the API.
Stateless
For the API’s to work properly it should not be assumed that server is not storing
any kind of data which might be essential for subsequent API calls.
The API should be stateless and Client should be responsible for managing the state of the application.
Client should be sending all the necessary information.
Cacheable
In REST, caching shall be applied on resources when applicable and then these resources MUST
declare themselves cacheable.Caching can be implemented on server or client side.
Well-managed caching partially or completely eliminates some client–server interactions unless the resouce
was changed between the last time it was requested.
Layered system
REST allow you to use a layered system architecture where you deploy the APIs on a Server A,
have intermediate systems between. Client facing urls and the actual Service.
For instance we can have a API gateway which control access to the API.
Or we can also think of load balancing architecture where the serving accepting request
actually redirect the request to a particular node.
Code on demand (optional)
Well, this constraint is optional. Most of the time you will be sending the static representations
of resources in form of XML or JSON.
But when you need to, you are free to return executable code to support a part of your application
e.g. clients may call your API to get a UI widget rendering code. It is permitted.
All above constraints helps you build a true RESTful API and you should follow them.
Still, at times you may find yourself violating one or two constraints.
Do not worry, you are still making a RESTful API – but not “truly RESTful”.
Following are the Best Practices for Designing and Developing REST
REST Resource Naming Best Practices
Use nouns to represent resources not verbs.
To describe names use concrete names (Nouns) rather then verbs.
RESTful URI should refer to a resource that is a thing (noun)
instead of referring to an action (verb) because nouns have properties as verbs do not
similarly resources have attributes.
Example
Use
GET /questions
GET /questions/1
Rather then
GET /retrieveQuestions
GET /getQuestionWithID/1
URI Case
Use lowercase letters in URIs. According to RFC3986, URLs are “case sensitive” (except for the scheme and the host).
When convenient, lowercase letters should be consistently preferred in URI paths.
Do not use trailing forward slash (/) in URIs
Use hyphens (-) to improve the readability of URIs (Spinal-Case)
Do not use underscores ( _ )
Use forward slash (/) to indicate a hierarchical relationships
HTTP methods
Key objectives of the REST approach is using HTTP as an application protocol. Hence, we should systematically
use HTTP verbs to describe what actions are performed on the resources and facilitate the developer’s
work handling recurrent CRUD operations.
The following methods are used in REST development.
GET
The GET method is used to retrieve information from the given server using a given URI.
Requests using GET should only retrieve data and should have no other effect on the data.
HEAD
Same as GET, but transfers the status line and header section only.
POST
A POST request is used to send data to the server, for example, customer information,
file upload, etc. using HTML forms.
PUT
Replaces all current representations of the target resource with the uploaded content.
PATCH
Update a part of a document/content.
DELETE
Removes all current representations of the target resource given by a URI.
OPTIONS
Describes the communication options for the target resource.
Singular vs Plurals
commonly-accepted practice is to always use plurals in node names to keep your
API URIs consistent across all HTTP methods
Idempotent and Safe Methods
Some HTTP methods are considered Safe(does not change data) and Idempotent(can be called multiple time without side effect) and some are not. Following table summarizes the methods those are considered Idempotent and Safe.
An idempotent method means that the result of a successful performed request is independent
of the number of times it is executed.
For example
A = 2 + 3 ; is idempotent , because it does not matter how many times this statement is executed,
value of A would be always 2 +3 = 5
Where as
A = A + 3 is not idempotent since, on each execution the value of A will change (increase).
Safe Methods:
Safe methods are HTTP methods that do not modify the resource e.g. a GET, HEAD, OPTIONS are safe because they doesn't modify the resource.
Where as other HTTP methods e.g. POST, PUT, PATCH, or DELETE are non-safe
HTTP Status Code
The RESTful Web Service should respond to a client’s request with a suitable HTTP status response code.
2xx – OK – everything is fine.
4xx – client error – if the client did something wrong (e.g. the client sends an invalid request or he is not authorized)
5xx – server error – something went wrong in the server, like the Database is down or some exception was raised
by application server
2xx: Success
200 OK
201 Created
3xx: Redirect
301 Moved Permanently
304 Not Modified
4xx: Client Error
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
410 Gone
5xx: Server Error
500 Internal Server Error
List of HTTP status code can be found here
https://en.wikipedia.org/wiki/List_of_HTTP_status_codes
HATEOAS
HATEOAS stands for Hypermedia As The Engine Of Application State
Architectural Constraints
REST defines 6 architectural constraints which make any web service – a true RESTful API.Uniform interface
Client–server
Stateless
Cacheable
Layered system
Code on demand
Uniform interface
Uniform interface suggests that the resource in a system to have only one logical URI and
Then provide additional information to retrieve the related data. For instance we can provide
Links for related resources like child objects, parent objects etc.
User of one API end point should be able to identify and work similarly with other Resources.
Also, the resource representations across system should follow certain guidelines
such as naming conventions, link formats or data format, filter formats pagination formats etc.
All resources should be accessible in similar way and should use similar status codes.
Client–server
Server should not depend on previous client state to serve next request.
Each request should be independent
of any state set in the server by previous requests.
If we replace the server with a different server serving same API’s then the Client should be work.
This is only possible if the API’s are consistent and follows same standard for all endpoints.
This way we can use load balancer to switch the server serving the API.
Stateless
For the API’s to work properly it should not be assumed that server is not storing
any kind of data which might be essential for subsequent API calls.
The API should be stateless and Client should be responsible for managing the state of the application.
Client should be sending all the necessary information.
Cacheable
In REST, caching shall be applied on resources when applicable and then these resources MUST
declare themselves cacheable.Caching can be implemented on server or client side.
Well-managed caching partially or completely eliminates some client–server interactions unless the resouce
was changed between the last time it was requested.
Layered system
REST allow you to use a layered system architecture where you deploy the APIs on a Server A,
have intermediate systems between. Client facing urls and the actual Service.
For instance we can have a API gateway which control access to the API.
Or we can also think of load balancing architecture where the serving accepting request
actually redirect the request to a particular node.
Code on demand (optional)
Well, this constraint is optional. Most of the time you will be sending the static representations
of resources in form of XML or JSON.
But when you need to, you are free to return executable code to support a part of your application
e.g. clients may call your API to get a UI widget rendering code. It is permitted.
All above constraints helps you build a true RESTful API and you should follow them.
Still, at times you may find yourself violating one or two constraints.
Do not worry, you are still making a RESTful API – but not “truly RESTful”.
Following are the Best Practices for Designing and Developing REST
REST Resource Naming Best Practices
Use nouns to represent resources not verbs.
To describe names use concrete names (Nouns) rather then verbs.
RESTful URI should refer to a resource that is a thing (noun)
instead of referring to an action (verb) because nouns have properties as verbs do not
similarly resources have attributes.
Example
Use
GET /questions
GET /questions/1
Rather then
GET /retrieveQuestions
GET /getQuestionWithID/1
URI Case
Use lowercase letters in URIs. According to RFC3986, URLs are “case sensitive” (except for the scheme and the host).
When convenient, lowercase letters should be consistently preferred in URI paths.
Do not use trailing forward slash (/) in URIs
Use hyphens (-) to improve the readability of URIs (Spinal-Case)
Do not use underscores ( _ )
Use forward slash (/) to indicate a hierarchical relationships
HTTP methods
Key objectives of the REST approach is using HTTP as an application protocol. Hence, we should systematically
use HTTP verbs to describe what actions are performed on the resources and facilitate the developer’s
work handling recurrent CRUD operations.
The following methods are used in REST development.
GET
The GET method is used to retrieve information from the given server using a given URI.
Requests using GET should only retrieve data and should have no other effect on the data.
HEAD
Same as GET, but transfers the status line and header section only.
POST
A POST request is used to send data to the server, for example, customer information,
file upload, etc. using HTML forms.
PUT
Replaces all current representations of the target resource with the uploaded content.
PATCH
Update a part of a document/content.
DELETE
Removes all current representations of the target resource given by a URI.
OPTIONS
Describes the communication options for the target resource.
Singular vs Plurals
commonly-accepted practice is to always use plurals in node names to keep your
API URIs consistent across all HTTP methods
Idempotent and Safe Methods
Some HTTP methods are considered Safe(does not change data) and Idempotent(can be called multiple time without side effect) and some are not. Following table summarizes the methods those are considered Idempotent and Safe.
Idempotent?
|
Safe
| |
GET
|
YES
|
YES
|
HEAD
|
YES
|
YES
|
OPTIONS
|
YES
|
YES
|
PUT
|
YES
|
NO
|
PATCH
|
NO
|
NO
|
DELETE
|
YES
|
NO
|
An idempotent method means that the result of a successful performed request is independent
of the number of times it is executed.
For example
A = 2 + 3 ; is idempotent , because it does not matter how many times this statement is executed,
value of A would be always 2 +3 = 5
Where as
A = A + 3 is not idempotent since, on each execution the value of A will change (increase).
Safe Methods:
Safe methods are HTTP methods that do not modify the resource e.g. a GET, HEAD, OPTIONS are safe because they doesn't modify the resource.
Where as other HTTP methods e.g. POST, PUT, PATCH, or DELETE are non-safe
HTTP Status Code
The RESTful Web Service should respond to a client’s request with a suitable HTTP status response code.
2xx – OK – everything is fine.
4xx – client error – if the client did something wrong (e.g. the client sends an invalid request or he is not authorized)
5xx – server error – something went wrong in the server, like the Database is down or some exception was raised
by application server
2xx: Success
200 OK
201 Created
3xx: Redirect
301 Moved Permanently
304 Not Modified
4xx: Client Error
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
410 Gone
5xx: Server Error
500 Internal Server Error
List of HTTP status code can be found here
https://en.wikipedia.org/wiki/List_of_HTTP_status_codes
HATEOAS
HATEOAS stands for Hypermedia As The Engine Of Application State
Comments
Post a Comment