This video explains the three kinds of REST resources, the endpoint names of each kind, and the methods that can be applied to each endpoint.
- [Instructor] In the previous video, we learned the basics of HTTP. In this video, we're going to take a look at how RESTful APIs use HTTP to access and manipulate collections and elements, and to call more procedures. What is a collection in REST? As its name implies, a collection is a group of elements with the same representation. A list of events and a list of messages are both considered collections. What does a collection's interface look like? The interface consists of two parts: the collection's endpoint or URL path and the method.
An endpoint has the name of the collection, such as /events for events, and /messages for messages. The four HTTP methods can be used on the same endpoint to perform different tasks. GET lists the collection's elements. POST inserts a new element to a collection. PUT replaces the entire collection, and DELETE deletes the collection. We will now look at an example of using these four methods to access a collection. As an example, let us assume that the server has a collection of notes. One note has the word chicken, and another note has the word beef.
If we want to get the notes on the server, we send a GET request to /notes. Keep in mind that the GET request does not need a body. The server responds with 200 OK message. This means that the request was successful. In the response body, the server sent a JSON representation of the notes. It is useful for a server to include the content type header to tell the client the format of the data. In this case, it is application/json. We are bored with eating chicken and beef. We want something new, so we decide to insert some ham into the notes collection.
We do that by sending a POST request to the /notes endpoint. In the request body, we put the JSON representation of our note. Notice that we do not send the ID. Object IDs are usually assigned by the database, which is accessed by the server. Therefore, we should expect the server to send back an ID. As we had expected, the server sends back our note with an ID. In this message, however, the server sent a 201 Created status code, instead of a 200 OK. Different API developers have different opinions regarding the use of status codes.
But as a rule of thumb, anything that starts with a two is positive. One day, we wake up to a nightmare. Animals overthrew humans because of our cruelty. So we decide to go vegetarian to prevent that from happening. We do that by sending a PUT request to /notes, sending on a potato and a salad. Notice that this time, we included the IDs of the elements. People have mixed opinions about doing that, since the HTTP 1.1 specification defines PUT to be item potent. That is, calling it several times should have the same effect as calling it once.
The most widely accepted opinion is that the ID should be included, and the server should send an error response if it does not accept that. It is entirely up to the developer to decide whether to support PUT in collections or not. In this trivial example, the server replaces the entire collection and sends a 200 OK with nothing in the response body. After eating potatoes and salads for days, we lost our appetite and decide to not eat anymore. So we send a DELETE request to /notes. The server deletes all the elements in the collection and responds with a 200 OK.
An element in REST represents a single entity, such as a note. And element's endpoint is like that of the collection, except that it has a slash followed by the element's ID. Just like a collection's interface, an element's interface supports the GET, PUT, and DELETE methods. However, there is no such thing as posting to an element. You insert elements by posting to a collection. Remote procedures are endpoints on the server that trigger some server-side logic. There is no standard way for implementing remote procedures in REST. However, there are a couple rules of thumb that we can follow when designing our APIs.
The endpoints of remote procedures should always end with a verb that describes the procedure. For example, /search and /reply are good names. You should use GET for calling safe procedures, and POST, PUT, and DELETE for calling unsafe procedures. A procedure is safe when it does not have any side effects. In other words, calling it once or 10 times does not change the response or the server state. Many people consider remote procedure call as not trustful. We cover it because it is widely used in practice.
In this video, we learned how resources are used in RESTful APIs. In the next video, we will look at properties or constraints that make APIs RESTful.
This Node.js course gives you an overview of a RESTful API and the logical steps of creating one. It explores three different APIs, focusing on their similarities and differences and how to effectively implement one. Instructor Saleh Hamadeh starts off by defining APIs, showing how they can be built on top of HTTP and listing the properties that make an API RESTful. Learn how to develop Twitter Notes, a sample web application that lets users leave notes for their Twitter friends. Use Twitter's API to implement a login flow and then design a web API. Additionally, get a closer look at several other real-world APIs, and learn some best practices to keep APIs secure, maintainable, and efficient.
- Identifying REST resources
- Setting up the development environment
- Consuming a RESTful API
- Creating an OAuth login request
- Getting an access token
- Saving data in MongoDB
- Building a RESTful API
- Testing user-perceived performance
- Looking at APIs in the real world
- Best practices for building RESTful APIs