Course Introduction

What is REST?

REST is a set of architectural constraints for web APIs. That is to say, it tells us some properties that the API should have in order to be called a "REST API".

Here are the constraints:

  • It should use the concepts of "server" and "client", which virtually all web APIs do.

Three boxes with the word 'Client' in each, with arrows pointing to another box with the word 'Server' in it

  • It should use the concept of "resource", which we'll talk about in a moment.
  • No client information should be stored in the server between requests. Therefore, whenever the client sends a request, the client should include all necessary information for the server. This is known as being stateless because no state is stored in the server.
  • Data sent by the server to the client (called the responses) should be cacheable. This doesn't mean you must use caching, but you should be able to.
  • The interface should be uniform and use hypermedia. This is where many web APIs go wrong in calling themselves "REST", and we'll explore how to add this to our API towards the end of the course.
  • If the backend uses multiple different servers, this fact should be invisible to the client. For example, a client might send a request to create a user account and a different request to create a post, and these might go to different servers, but the client doesn't know.

As you can see, there are quite a few constraints! We will be implementing these in our project, so by the end of the course you'll know how a REST API operates.

What is a REST resource?

Think about a social media platform, and what "things" it deals in. For example, it may have "posts", "comments", "likes", "users", and many other things. Each of these could be a resource.

When a client sends a request, it should identify what resource it's talking about. This seems obvious, as otherwise how would the server know what information to retrieve, delete, or modify?

Similarly, when the server responds to requests, it should do so in the form of "resource representations". A common way to do this is by using JSON.

For example, if a social media post in your database has these properties:

  • unique identifier
  • title
  • body
  • user who created it

Then the API might represent this using JSON like so:

{
    "id": 123,
    "title": "post title here",
    "body": "body of the title here",
    "user_id": 3
}

The server should also tell the client how to fetch information about related resources. For example, it might include the endpoint to which the client should make a GET request to get more information about the user:

{
    "id": 123,
    "title": "post title here",
    "body": "body of the title here",
    "user_id": 3,
    "user_link": "/user/3"
}

REST as an architectural style was first described in a research paper by Roy Fielding. Over time people have interpreter this in different ways, and so there are many different "flavours" of REST. The main thing is to implement the features you need in your backend and to achieve the goals you want to achieve. Making sure that you adhere to REST to the letter shouldn't normally be a goal in itself, although it can guide you toward making better decisions.