REST APIs for HTTP
REST is in short for REpresentation State Transfer, which is an architectural style for building systems based on hypermedia. REST principles does not has to use HTTP as underlying protocol but we will be focusing on designing REST APIs for HTTP protocol.
- Web application designed around REST principles are often called RESTful, they reveal information in the form of resources.
- An application needs to follow a set of limitations to be RESTful.
- When a RESTful API is called, the server will transfer its current representation of state of the resouce requested.
- The representation of state often exchanged via JSON format but it can be any format such as XML, YAML, Key-Value pairs, or a custom format.
- In RESTful APIs, each resource has its unique identifier (URI — Unique Resouce Identifier)
- When a client calls a RESTful API, it has to provide a URI of the resource the client wants to interact with, and also the operation that wanted to be performed on the server as an HTTP verb. Example: a client may want to access a specific order from an API, the URL of the resource client is interested https://adventure-works.com/orders/1 and client can send a GET request to URI above to receive a representation of the state described by URI above in JSON format; {“orderId”:1,”orderValue”:99.90,”productId”:1,”quantity”:1}
REST Constraints
1 — Client — Server: This constraint means there should be a client that is initiating the requests, and there should be a server that is handling the request and returning a response.
2 — Uniform interface: has multiple parts.
- Each resource must have an unique identifier, URIs are the resources unique identifier for HTTP implementations.
- If user has permission to do, the returned response should include necessary information to modify or delete the resource interested.
- Each request and response should include enough information for server and client to understand request and response.
- HATEOAS (Hypermedia as the Engine of Application State): This part of uniform interface constraint simply means, showing user what can be done using HTTP links included in the response. In more formal words, a resource should contain links to its related resources. Although this is debatable, Martin Fowler says, REST reaches it’s full glory with HATEOAS.
3 — Stateless: Stateless constraint is simply the server does not store any information about any request and each request contains the information for server to perform and return a response.
4 —Cacheable: Every response should include whether resource is cachable and for how long.
5 — Layered system: Between client and server, there may be a number of layers such as proxy, authentication, caching, load- balancer etc. These layers should not affect request or response.
6 — Code on Demand — Optional: If you prefer, an executable code can be transferred instead of static representation (JSON, XML, etc.)