REST APIs Explained - 4 Components
A REST API is the most common standard used between Clients (a person or application) who want to access information from the web from Servers (application or database) who have access to that information.
An Application Programming Interface (API) is a way for two computers to talk to each other over the web. For example, a delivery app can use the Google Maps API to support location tracking instead of building one from scratch. Or a recipe website can use an AI model to suggest alternative recipes based on the same ingredients using the ChatGPT REST API.
An API that follows the REST standard is called RESTful. Here are good practices when designing and using a RESTful API using the example of a survey app.
The format of a RESTful API has three main components: 1) URL endpoint; 2) HTTP verb; and 3) Body.
Is a URL link that represents the resources we want to access. Resources can be text, images, documents or any data entry. For example,
example.com/surveys allows us to view or create survey templates and
example.com/surveys/123/responses allows us to do the same for all responses of survey 123.
Tells the server what we want to do with the URL endpoint resource. For example, a
POST request means we want to create a new survey template and a
GET request means we want to view an existing survey template.
Body message: Is an optional custom payload which contains a message with the properties and values we want to use to create or update a given resource.
For example, we want to create a new response for the survey 123 which we captured which includes a positive NPS score of 9, a short feedback message and the unique id of the respondent who gave the feedback.
// Body payload:
feedback: "love the service",
The server receives the HTTP request and returns a response that includes a HTTP status code and a response usually in JSON format. Here is an example request and response to a REST API server asking to read all the responses for survey 123:
// HTTP status code: 200
survey_title: "nps onboarding survey",
feedback: "love the service",
There are 5 basic verb commands when making a HTTP request:
- GET: make a read only request to view either a single or list of multiple resources
- POST: create a new resource based on the payload given in the body of the request
- DELETE: destroy the given resource based on the id provided
- PUT: update the entire fields of the resource based on the given body of the request or create a new one if not already exist
- PATCH: update only the fields of the resource if it exists
Most applications and resources will support all these commands. This is commonly referred to as a CRUD application:
|PUT & PATCH
A URL endpoint in a RESTful API represents any given object, data or service the API can access. For example,
example.com/surveys represents the data for all survey templates and
example.com/surveys/123/responses the data for all responses of a given survey.
URL endpoints should be grouped as pluralised nouns around the business data and objects and not verbs. For example,
example.com/surveys and not
URL endpoints should include the unique identifier as a path after the pluralised noun when viewing, updating or deleting a single item. For example,
Organise URL collections in a logical hierarchy based on relationships. For example, users are most likely to access responses to a given survey template. This would be represented as
Here is a summary of good practice URL endpoints and how they interact with HTTP verbs:
|URL endpoint resource
|Retrieve all surveys
|Create a new survey
|Bulk update surveys (not advised)
|Remove all surveys (not advised)
|Retrieve the details for survey 123
|Update the details of survey 123 if it exists
|Remove survey 123
|Retrieve all responses for survey 123
|Create a new response for survey 123
|Bulk update responses for survey 123 (not advised)
|Remove all responses for survey 123 (not advised)
|Retrieve the details for response 42
|Update the details of response 42 if it exists
|Remove response 42
Upon receiving a HTTP request in the basic RESTful format the server will return a HTTP status code along with any optional JSON payloads. Here are the most common HTTP status codes and their meaning:
|Request was successful.
|301 Moved Permanently
|For SEO purposes when a page has been moved and all link equity should be passed through.
|Server requires authentication.
|Client authenticated but does not have permissions to view resource.
|404 Not Found
|Page not found because no search results or may be out of stock.
|500 Internal Server Error
|Server side error. Usually due to bugs and exceptions thrown on the server side code.
|503 Server Unavailable
|Server side error. Usually due to a platform hosting, overload and maintenance issue.
Want more tips?
Get future posts with actionable tips in under 5 minutes and a bonus cheat sheet on '10 Biases Everyone Should Know'.
Your email stays private. No ads ever. Unsubscribe anytime.