Part 10: What is a REST API? | CRUD APIs| REST vs HTTP | System Design Tutorials | Part 10 | 2020
Topics covered in this video include:
- What is REST?
- REST != HTTP
- Building REST with Example
- Security, Error Handling, etc.
Future videos will cover SOAP and RTP.
A more detailed breakdown of the video is:
- What is REST? (1:05)
- Guidelines of REST (2:59)
- Example of REST API (6:43)
- State Transfer vs Stateless (14:50)
- Path vs Query Parameters (16:17)
- HTTP Response (Status codes) (18:55)
- Security, Authorisation, and Error Handling (21:17)
What is REST?
It's an acronym of Representational State Transfer. It has 5-6 guidelines that must be implemented in client-server architecture. When the client requests information, the server sends it back in an agreed upon representational format. When the state changes at the server, after the client requests data - the updated state is shared from the server to the client. For example, the server has notes on books and new notes are added.
Guidelines of REST
The six guidelines that define a RESTful interface include:
- Client-Server - data is exchanged between client and server in agreed-upon format.
- Cachable - server sends information if data is cachable and if so, the client can re-use it.
- Layered - when the client makes a request, it only knows about one layer of abstraction. It does not, for example, know how the server retrieves the data from a database.
- Stateless - the server can get multiple requests from servers or multiple requests from single server. The server does not differentiate between the clients. Neither the server, nor the clients preserve state during the interactions.
- Uniform Interface - more details provided later in the video. Same formats and protocols should be used throughout.
- Code on Demand - server sends code that client execute at run-time such as JavaScript (or applets).
Example of REST API
If a person has books for online purchase, they need to use a catalogue to store book information. The system will need a database to track the books. Hence the REST API will include interfaces for getting list of books, removing a book, adding a book, updating details of a book. The update can include information such as how many copies of the book are in stock.
Hence the actions that need to be done on the data are CRUD operations:
- Create
- Read
- Update
- Delete
In order to use these, we need resources (books listed in databases), URI (Uniform Resource Identifier), and a method to communicate. For the read (list of books) the URI could be <server domain>/mystore/books. We'll use the HTTP protocol to access the book resources. The method used for the request to view the list of books is GET. The response will be a JSON containing a list of books.
The state, the copy of the data, is transferred in an agreed upon format - encoded as JSON - from the server to the client.
In order to create new books entries, the POST method is used to write to the database. It will have the same URI, in addition it will contain the data (PAYLOAD). This will include: name, author, price, publication date, etc. The server will add a new book to the store and send a response.
When the books information is updated, for example due to available number of books decreasing - the PUT method is used. To remove entries from the book database, the DELETE method is used. Two other methods that are not covered in the lecture are PATCH and OPTIONS.
The full list of methods are:
- GET
- POST
- PUT
- DELETE
- PATCH
- OPTIONS
State Transfer vs Stateless
The state transfer refers to the transfer of data between the client and server. For example. the state is the list of books, or books to be added, updated, or deleted. The server should be stateless, in other words, it should not care about which client(s) it is communicating and not keep any state information as part of the communication. There are some exceptions, such as during authentication.
The server does not distinguish between serving multiple clients with the same requests, or a single client with multiple requests.
Path vs Query Parameters
- Path parameters
- Query parameters
When requesting the list of books, the following is used: URI/<server domain>/mystore/books. In order to access a single book, we can use the ID as follows: URI/<server domain>/mystore/books/id. This is referred to as path parameter.
In order to only see the first 20 results, we can use query parameters as follows: URI/<domain>/mystore/books?limit=20&offset=0. This will show the first 20 books. by increasing the offset to 21 - we can retrieve the next 20 books. Adding other query parameters such as ?tag=fiction, we can further refine the search.
HTTP Response (Status codes)
- 1xx - Informational
- 2xx - Success
- 3xx - Redirection (URI now at different location)
- 4xx - Client is sending invalid request, in a format not agreed upon
- 5xx - Something is wrong on the server side
Security, Authorisation, and Error Handling
API security is a big topic that you should look into further in depth. This includes rate limiting how often a request can be made or how to prioritise it in a queue.
REST is not the same as HTTP. It is a set of guidelines of how client and server should interact.
Here are some useful links: