REST

• REST - Representational State Transfer
• Common communication standard used in mobile and web applications
• REST defines a set of rules to build web APIs. An API that follows the rules are said to be RESTful

---

Rules of REST §

1. Uniform interface
   • APIs should have a uniform and consistent interface
   • This includes,
     • Resources identification via URIs (Uniform Resource Identifiers)
     • Resource manipulation through representation - Resources can be manipulated using a limited set of operations (typically HTTP methods) based on represntation (like JSON, XML, etc)
     • Self-descriptive messages - Each message should contain enough info on how to process it
     • Hypermedia as the engine of application state (HATEOAS) - ensure that resources are interconnected through hypermedia links
2. Client-Server decoupling
   • The only information the client app should know is the resource URIs
   • The only communication from the server to the client is the passing of the requested data
3. Statelessness
   • Every request/response is independent of other requests/responses
   • Every request/response should have all the necessary information needed to process it (Headers)
4. Cache-ability
   • Whenever possible resources should be cached in the client slide to improve performance
   • The server response should contains info about wether caching a particular resource is allowed or not.
5. Layered system architecture
   • In REST APIs, the requests and responses can go through multiple layers btw the client and the server, the client and server can be made up of multiple layers themselves.
   • APIs need to be designed in such a way that neither the client nor the server would be able to tell if it’s communication with the end application or an intermediary
6. Code on demand (Optional)
   • REST API responses can sometimes be executable code
   • In such cases, the code should only run on-demand in the client side

---

URI §

• URI - Uniform Resource Identifier
• Ex:

  https://example.com/api/v3/products // for 'product' resource
  https://example.com/api/v3/users // for 'user' resource
  

---

HATEOAS §

• Simply, they are links to related resources within a resource’s responses

• To incorporate HATEOAS in your REST API, include relevant hypermedia links in resource representations and use standardized media types to convey link relations

• For example, links can be embedded in JSON payloads using the _links property, like this:

  {
    "orderId": 12345,
    "totalAmount": 99.99,
    "_links": {
      "self": {
        "href": "https://api.example.com/orders/12345"
      },
      "customer": {
        "href": "https://api.example.com/customers/54321"
      }
    }
  }

---

Format of a HTTP request as per REST §

// start line
 
<HTTP_VERB> /<URI> HTTP/<VERSION>
 
// Headers
 
Accept: application/json
Authentication: <token>
Connection: keep-alive
...
 
// Optional body
 
{
	"key1": "value1",
	"key2": "value2"
}

Note

HTTP verbs - POST, GET, PUT, DELETE, etc.

Note

URI must be a noun

• ✅ https://example.com/api/v3/products
• ❌ https://example.com/api/v3/getAllProducts

---

Format of a HTTP response as per REST §

// start line
 
HTTP/<VERSION> <STATUS_CODE>
 
// headers
 
Server: nginx
Connection: keep-alive
...
 
// optional body
 
{
	"key1": "value1",
	"key2": "value2"
}

Note

Summary of status codes,

2** - Successful
4** - Something wrong with the request
5** - Something wrong with the server

---

Related §

Best practices for REST API design

---

Refs §

1. https://appmaster.io/blog/the-six-rules-of-rest-apis
2. https://www.ibm.com/topics/rest-apis