Project 1

In project 1 you have to build an web application that needs to support the creating, updating and deletion of resources (e.g. playlists, events, etc.). However the way the API was structured between groups is completely different, and worse even within the same group (application) there are differences.

Take for example the create, update, delete for a event (within the same group), we find the following urls:

There is no consistency in the naming of the Uniform Resource Locator (URL), and it get’s even worse of you compare it between project groups:

Image you are a developer taking over such a project, there is no way to know for a resource, what the URLs are for Create, Read, Update, Delete (CRUD) operations. This is one of the pain points REST API fixes, by introducing Uniform interface, more about this in the next sections.

In project 1, you have seen both GET and POST request methods. Hopefully you used the GET method only for retrieving data and used the POST method for all other data manipulation. But what if you want to create and update a resource, let’s say an event. What you probably did was create two different URLs to handle create (e.g. create-event.php or event/create.php) and one for updating (e.g update-event.php or event/update.php). This works fine, but what if you for example also want to support partial update of an event? You can add another URL (e.g. partial-update-event.php or event/partial-update.php), but you can see that you are starting to get a lot very specific URLs and you need to make sure that you need the same naming convention for all resources. A REST API helps alleviate this problem by not only supporting GET and POST request parameters, but also PUT, PATCH and DELETE.

HTTP Request

The basic form of a HTTP request is very simple, it consists of three parts:

<request method> <URI> <HTTP version>

So a simple HTTP request could be as follows:

GET /images/logo.png HTTP/1.1 or POST /event/create.php HTTP/2.0

GET /home.html HTTP/1.1
Host: developer.mozilla.org
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.9; rv:50.0) Gecko/20100101 Firefox/50.0
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate, br
Referer: https://developer.mozilla.org/testpage.html

POST /api/users HTTP/1.1
Host: example.com
Content-Type: application/json
Accept: application/json
Content-Length: 67

{
  "name": "John Doe",
  "email": "johndoe@example.com",
  "age": 30
}

HTTP response

After making an HTTP request, the server responds with an HTTP response. The HTTP response is build up in almost the same manner as an HTTP request.

An HTTP response looks as follows:

<HTTP version> <status code> <status message>

So a simple response could be as follows:

HTTP/1.1 200 OK or HTTP/2.0 404 Not Found

HTTP/1.1 200 OK
Content-Type: text/html
Set-Cookie: sessionId=abc123; HttpOnly; Secure; Path=/
Location: https://example.com/dashboard
Content-Length: 0

HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 75

{
  "id": 123,
  "name": "New Resource",
  "status": "created"
}

Client-Server Architecture

Example: A mobile app (client) requests data from a REST API (server), and the API responds with the requested data without knowing how the client will use it.

Statelessness

Example: A request to get user data:

GET /users/123
Authorization: Bearer token123

The server does not remember the user between requests. The client includes authentication in every request.

Cacheability

Example: A cacheable response:

Cache-Control: max-age=3600

This tells clients they can reuse the response for 1 hour without making another request.

Layered System

Example: A request may pass through a load balancer before reaching the API server, distributing traffic across multiple backend servers.

Code on Demand (Optional)

Example: An API sends a JavaScript function to a web client to validate input before submitting a request.

Uniform Interface

The Uniform Interface is a key principle of REST. It ensures that interactions with a RESTful API follow a consistent structure. This is important to apply in project 2, so we go a bit deeper into this principle in the next section.

Identification of Resources

Good Examples:

/users          -> List of users
/users/123      -> Specific user
/orders/567     -> Specific order
/users/123/orders -> Orders for a specific user

Bad Examples:

/getUsers       -> Verb-based, violates REST principles
/retrieve-order?id=567 -> Query parameters should not define resource structure

Have a look at resource-naming.

Manipulation of Resources through Representations

Example: Updating a user’s profile:

PUT /users/123
Content-Type: application/json

{
  "name": "John Doe",
  "email": "john@example.com"
}

The API updates the user’s data and returns a response.

Self-Descriptive Messages

Example: Request to fetch user details:

GET /users/123 HTTP/1.1
Host: api.example.com
Authorization: Bearer token123
Accept: application/json

Hypermedia as the Engine of Application State (HATEOAS)

Example: A GET /users/123 response with hypermedia links:

{
  "id": 123,
  "name": "John Doe",
  "email": "john@example.com",
  "links": {
    "self": "/users/123",
    "orders": "/users/123/orders"
  }
}

The client can follow the "orders" link to fetch the user’s orders.

HTTP methods in REST

As you may have noticed in the Uniform interface, we do not have different URIs for creating and updating for example, instead we use HTTP requests methods to indicate what we want to do with a resource.

As already discussed in project 1, the GET method is not allowed to change any state, while the POST method is allowed to change state. REST uses the HTTP request methods in the same way, have a look at the following table:

Safe Methods: A method is considered safe if it does not modify the resource on the server (i.e., it only retrieves data). Idempotent Methods: A method is idempotent if making multiple identical requests results in the same effect as making a single request.