Understanding REST API concept

REST API (Representational State Transfer) is a feature added to an application that allows other developers to interact with the application. WordPress also provides various endpoints to work with its data via HTTP.

Key concepts and terms

Before learning what is REST API, lets understand how a full-stack application works.

Client-Server architecture of an application

• A full-stack application can also be a simple (or complex) database driven application where you don’t have to call backend services using HTTP. In such applications, you connect to database using relevant drivers then work with the data.
• Full-stack applications based on REST API have two parts:
  • Frontend: what users sees and interacts with (form submission).
  • Backend: where data and other application logic is handled (routing, data processing,…)
  • These two communicate via HTTP (GET request, POST request, …)
• Back-end can be developed using any framework and tool (Django, node, Laravel,..)
• Similarly front-end can be developed using any tool (ReactJS, Vue.js,…)
• Application is structured in such a way that, whenever client sends HTTP request to backend, some APIs (Application Programming Interfaces) are available in the backend to handle the HTTP request. The method used in HTTP request determines the kind of the operation to perform on the resource.

Resources and Endpoints

• Resource is an application data.
• Resources for an application will depend upon it’s functionality.
• For example, if you are developing a backend for an online store, then you can define following resources for the application.

1. products
2. customers
3. users
4. orders

• Endpoints are routes (URLs) for performing CRUD operations on the resources (app data).
• Structure of endpoints are different for different applications but within an application, the structure of endpoint is consistent for every resources.

// Endpoints examples
// if an application decides to provide endpoints for its data in the structure: https://app_name.com/api/v2/, then endpoints for;
1. Customers: https://app_name.com/api/v2/customers
2. Products: https://app_name.com/api/v2/products
3. Users: https://app_name.com/api/v2/users
4. Users: https://app_name.com/api/v2/orders

Note: here the url structure before /customers can differ from applications to applications. e.g., https://api.app_name.com/customers
(Its just a developer preference)

HTTP methods

• HTTP method determines the kind of the operation to perform on the application resource.
• Examples:

// Perform GET request at endpoint: https://app_name.com/api/v2/customers
GET https://app_name.com/api/v2/customers
// to get single customer info include its id in url (as query string)
GET https://app_name.com/api/v2/customers/id=123

// DELETE a resource
DELETE https://app_name.com/api/v2/customers/id=123
Note: you will need to provide an id of the customer to DELETE (include in url as query string)

// create a resource using POST method
POST https://app_name.com/api/v2/customers
Note: A POST request will require authentication token to be included in the header (for authentication and authorization) and a body which includes the information about the customer.

// Update a resource.
PUT https://app_name.com/api/v2/customers/id=123
Note: Similar to POST method, PUT will also require authentication token and a body message.

Response

• It is the data you get back after performing a specific HTTP request to an endpoint.
• When developing a backend services, its very important to include necessary information in the response. For example;
  • 404 for resource not found,
  • 303 for page redirects,
  • 200 for successful operation
  • 401 for unauthorized or authentication failure
  • 403 for forbidden operation
  • 500 for server errors
• Response types:
  • html
  • json (mostly used)
  • xml
  • xhtml
  • text
• Response type is specified by the application.

Definition of REST API in summary

In simple terms, REST API is a convention to build HTTP services for your application. And once the application supports RESTful service, client applications can send HTTP requests at supported endpoints to perform CRUD operations on the application resources.