Introduction to REST and RESTful APIs

In modern web development, you must often encounter terms such as REST and API. If you have heard of these terms or used APIs but don't fully understand how they work or how to build your own API, this tutorial series is right for you.

This tutorial series will first overview of REST principles and concepts. We will then create a complete API that runs on the Node.js Express server and connects to the MySQL database. After completing this series of tutorials, you should be able to build your own API with confidence or dig into documentation for existing APIs.

Prerequisites

To make the most of this tutorial, you should have some basic command line knowledge, basic JavaScript knowledge, and install Node.js globally.

What are REST and RESTful APIs?

Declarative State Transfer ( REST ) ??describes an architectural style of a Web service. REST contains a set of standards or constraints for sharing data between different systems. The system that implements REST is called RESTful. REST is an abstract concept, not a language, framework, or software type.

A loose analogy about REST is: keeping vinyl record collections and using streaming music services. For physical vinyl record collections, each record must be copied in full in order to share and distribute copies. However, for streaming services, the same music can be shared permanently by reference to certain data, such as song titles. In this case, streaming music is a RESTful service, while vinyl record collection is a non-RESTful service.

API is an application programming interface, which is an interface that allows software programs to communicate with each other. The RESTful API is just an API that follows REST principles and constraints. In the Web API, the server receives the request through the URL endpoint and returns a response , which is usually data in JSON format.

REST Principle

Six guiding constraints define the REST architecture as follows:

1. Unified interface : The interfaces of components must be the same. This means using the URI standard to identify resources—in other words, paths that can be entered into the browser's address bar.
2. Client-Server : There is a separation of concerns between the server (store and operate data) and the client (request and display response).
3. Stateless interaction : All information about each request is contained in each individual request and does not depend on the session state.
4. Cacheable : Clients and servers can cache resources.
5. Hierarchical system : The client can connect to the final server, or to the intermediate layer, such as a load balancer.
6. On-demand code (optional) : The client can download the code, thereby reducing external visibility.

Requests and responses

You may already be familiar with all websites' URLs starting with https (safe version). Hypertext Transfer Protocol ( HTTP ) is a method of communication between clients and servers on the Internet.

We most obviously see it in the browser's URL bar, but HTTP can not only be used to request websites from the server. When you access a URL on the web, you are actually performing GET and other types of requests.

HTTP makes a request by opening a TCP (Transport Control Protocol) connection to the server port (http, https), and the listening server returns the status and body.

The request must contain URL, method, header information, and body.

Request method

There are four main HTTP methods, also known as HTTP verbs, which are commonly used to interact with Web APIs. These methods define the actions to be performed on any given resource.

The HTTP request method roughly corresponds to the CRUD example, which represents creation, update, read, and delete . Although CRUD refers to the functions used in database operations, we can apply these design principles to HTTP verbs in the RESTful API.

 <code>curl -i https://www.google.com</code>

Google's server will return the following:

 <code>HTTP/2 200 date: Sun, 21 Aug 2022 19:06:22 GMT expires: -1 cache-control: private, max-age=0 content-type: text/html; charset=ISO-8859-1 ...</code>

We can see the 200 status code, as well as the version of HTTP (this will be HTTP/1.1, HTTP/2 or HTTP/3).

Since this particular request returns a website, it is text/html. In the RESTful API, you may see a curl request to Google (not including google.com) returning a 301 response indicating that the resource should be redirected.

REST API Endpoint

When an API is created on the server, the data it contains can be accessed through the endpoint. An endpoint is a URL that can accept and process requests for POST, DELETE requests.

The API URL will consist of the root, path, and optional query string.

• Root For example, the root of http://m.miracleart.cn/link/9efa87e164995a7743eca9ad63029fa4 may contain protocols, domain names and versions.
• Path for example /users/5: The only location for a specific resource.
• Query parameters (optional) such as limit=10, are used to filter the response to contain only ten results.

For example, to get a user with ID 5, we will use /user/5.

REST API Contract

Here are some conventions you should follow when building a RESTful API:

• Endpoints should not display file extensions : Although the API is most likely to return JSON, the URL should not end in .json.
• Use nouns instead of verbs : For example, to add a user, we should use the /users endpoint and use the POST request instead of the /users/add endpoint. The API should be developed to be able to handle multiple types of requests to the same URL.
• Paths are case sensitive and should use lowercase letters and hyphens instead of underscores : for example, /users-list is preferable to /users_list.

All of these conventions are guiding principles because there are no strict REST standards to follow. However, using these guidelines will make your API consistent, familiar, and easy to read and understand.

Alternatives to REST

REST is a great tool, but there are some alternatives that can help in some cases.

SOAP

SOAP (Simple Object Access Protocol) is an API created in 1998 and was very popular before REST. There are some major differences between them. First, SOAP has much stricter restrictions on response formats. Second, SOAP uses XML instead of JSON, which may be useful for legacy applications, but is usually larger and more complex than equivalent JSON. Finally, while SOAP works well with HTTP, it also supports protocols such as SMTP.

GraphQL

GraphQL is a newer API format created by Facebook that aims to reduce the number of HTTP requests needed to get the data by allowing clients to accurately tell the server what data it needs. Instead of using URL paths, GraphQL has a custom syntax to define what data the client needs so that the client gets everything it needs in one request.

For a great introduction to GraphQL, check out this GraphQL tutorial.

in conclusion

In this article, we learn what REST and RESTful APIs are, how HTTP request methods and response code work, the structure of API URLs, and the common RESTful API conventions. In the next tutorial, we will learn how to put all these theories into practice by setting up an Express server with Node.js and building our own API.

This article has been updated and includes Jacob Jackson's contributions. Jacob is a web developer, tech writer, freelancer and open source contributor.

The above is the detailed content of Code Your First API With Node.js and Express: Understanding REST APIs. For more information, please follow other related articles on the PHP Chinese website!