Who should read it: It is for you if you are looking for a quick overview of this topic for a project, to conduct/appear in an interview, or in general. As we learn more, we will update this article.
REST definition: REST is an architecture style based on web standards and the HTTP protocol. This was initially described by Roy Fielding in 2000. In REST, everything is a resource.
Resource: Any information that can be named is a resource.
Six Guiding principles of REST: To make a web service a true RESTful API, below are six guiding principles:
- Uniform Interface: A RESTful API MUST have an interface that is consistent to access all resources. A resource should have only one logical URI. Any single resource should not be too large.
- Client Server: A client and a server must be independent of each other.
- Stateless: All client-server interactions must be stateless. No session. No history.
Cacheable: When applicable, make the resources of REST cacheable. It improves the performance. Caching helps to reduce bandwidth, latency, and load on servers. It also helps in hiding network failures. There are two HTTP response headers to control caching behavior: Expires and Cache-Control. There are two validator options: E-Tag or Last-Modified. One of these two validators should be used.
- Layered system: REST allows to use a layered system architecture. For example, an API may be deployed on system 1, get database data from system 2, and authenticate the user from system 3.
- Code on demand (optional): This is an optional constraint. For example, my API may return the code to hide/show UI logic of a UI element.
HTTP methods: REST architecture uses these methods below:
- HTTP GET: Use GET requests to retrieve the information.
- HTTP POST: Use POST to create new resources.
- HTTP PUT: Use PUT to update an existing resource. If a resource does not exist, API may decide to create a new resource. Consider it as an update-else-create operation.
- POST versus PUT: POST requests are made on resource collections whereas PUT requests are made on a single resource.
- HTTP PATCH: Use PATCH to partially update a resource.
- PUT versus PATCH: Use PUT to update a resource completely (like replacing a resource). Use PATCH to update a record partially.
- HTTP DELETE: Use DELETE to delete a resource.
HATEOAS driven APIs: HATEOAS (Hypermedia As The Engine Of Application State) is a constraint of REST API. It keeps the REST API unique from most other network application architectures. As per HATEOAS constraint, a client needs to know only a single URL. All other resources should be dynamically discoverable via the URL.
Other REST terms:
- Safe methods: GET and HEAD are considered safe methods because these are used to retrieve information, not to update or delete.
- Idempotent methods: Idempotent term means that the repeated execution should not impact anything negatively. In other words, making one request or multiple requests should have same impact. If we follow REST API design, GET, PUT, DELETE, HEAD, OPTIONS, and TRACE HTTP methods are automatically idempotent. Only POST methods are not idempotent.
REST’s eight security essentials:
- Least Privilege: follow the minimum privilege model.
- Fail-Safe Defaults: Users should not have a default access. Accesses should be explicitly given.
- Economy of Mechanism: The design should be as simple as possible.
- Complete Mediation: A system should validate all access rights as a fresh validation. Access rights should not be cached.
- Open Design: Design should not have any secrets or confidential algorithms.
- Separation of Privilege: For the privileges, use of multiple conditions is a better idea, rather than providing a single condition access.
- Least Common Mechanism: Mechanism used to access resources should not be shared.
- Psychological Acceptability: Security should not make the experience worse.
- Keep it simple.
- Always use HTTPS.
- Use password hash.
- Never expose information on URLs.
- Consider OAuth: OAuth 2.0 authorization framework enables a third-party application to limited access to an HTTP service. Read more here.
- Consider adding timestamp in Request.
- Input Parameter Validation.
Content Negotiation: Asking for a suitable presentation by a client is called the content negotiation.
Versioning: It helps to manage the iterations of the APIs. Versioning allows clients to use existing API version while new version can be made available. Below are ways to manage versioning:
- Via URI path. For example, https://onepointahead.com/api/1/categories
- This is a good, cache-able strategy but it may need the branching the entire API.
- Via query parameters. For example, https://onepointahead.com/api/categories?version=1
- It’s simple and generally a default option. But, query parameters are difficult to use.
- Via customer headers. For example, curl -H “Accepts-version: 1.0″
http://www.onepointahead.com/api/categories- It doesn’t clutter the URI path. But, it requires custom headers.
- Via content negotiation. For example, curl -H “Accept: application/json; version=1” http://www.onepointahead.com/api/categories
- It is a simpler option that avoid versioning. But, it needs the HTTP headers with media types.
Compression: REST APIs can returnresource representations in several formats like XML, JSON, HTML, or plain text. All these formats can be compressed to save bandwidth on the network.
REST API’s N+1 problem and solution: It is a problem when loading a request needs N more requests, to load associated items. To solve this problem, include more information in individual resource inside collection resource.
‘q’ parameter: In HTTP accept header, ‘q’ parameter helps in setting the MIME type preference and the degree of it.For example:
- Accept: audio/*; q=0.2, audio/basic
- should be interpreted as “I prefer audio/basic, but send me any audio type if it is the best available after an 80% mark-down in quality.”
For more details about ‘q’ parameter, read here.
REST Maturity Model: After the detailed analysis, Leonard Richardson used three factors to decide the maturity model of a web service: URI, HTTP, and HATEOAS (Hypermedia)being URI at the bottom and Hypermedia at the top.
- Level zero: Level zero does not use any of three: URI, HTTP, or HATEOAS (Hypermedia). These web services are a single HTTP based typically POST. For example, a SOAP web service may use HTTP POST, to transfer SOAP based payloads. An XML-RPC based service can send data using Plain Old XML (POX).
- Level one: Level one maturity model makes use of URI and does not make use of HTTP and HATEOAS. These APIs may implement multiple URIs and with the implementation of a single verb, maybe just POST.
- Level two: Level two maturity model makes use of URI and HTTP but does not use HATEOAS. These services may support CRUD operations.
- Level three: this level uses all three: URI, HTTP, and HATEOAS.
API Management: It is about the processes and technologies that maintain the APIs in the cloud. There are many tools options. Some of these are below:
- AWS API Gateway
- Azure API Management
- Mulesoft Anypoint Platform
- IBM API Connect
- Postman
- Apigee API Management
- RapidAPI
- Tyk
- Software AG
- Boomi
API Rate limiting: It is the number of times an API can be called in a given time period.
OpenAPI Specification (OAS): OAS defines the standards for RESTful APIs.
Documenting public APIs: Documentation of public APIs is as important as developing these APIs. It is needed to document public APIs well so that users of these APIs can understand these in a systematic way. For details of how to document public APIs, refer here.
REST versus SOAP web services: coming soon
References:
- https://docs.oracle.com/javaee/6/tutorial/doc/gijqy.html
- https://restfulapi.net/
- https://stackoverflow.com/questions/31089221/what-is-the-difference-between-put-post-and-patch
- https://restfulapi.net/rest-put-vs-post/
- https://howtodoinjava.com/resteasy/writing-restful-webservices-with-hateoas-using-jax-rs-and-jaxb-in-java/
- https://www.cs.clemson.edu/course/cpsc420/material/Design%20Principles/Design%20Principles.pdf
- https://datatracker.ietf.org/doc/html/rfc6749
- https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html
- https://developer.mozilla.org/en-US/docs/Glossary/Quality_values
- https://swagger.io/specification/
- https://swagger.io/resources/ebooks/api-documentation-the-secret-to-a-great-api-developer-experience/
onepointahead.com 
One thought on “RESTful APIs”