In this post we will talk about the basics concepts of a REST API. For this we will see in detail how a request is build and works.
What is a REST API
- REST is short for REpresentational State Transfer
- It's not a standard, it's an architecture style that use standards like HTTP, URI, JSON, MIME-Type, ...
- is used for exchange between server and client especially of JSON and binary data (images and videos)
- it's Stateless - The web service doesn't store a sessionID or anything like that, each call stands for itself.
- URIs are used to identify web resources - Each resource is represented by a URI
- Access to URIs with the HTTP methods: GET, POST, PUT, PATCH, DELETE
HTTP Methods
As mentioned above, URIs are called together with an HTTP-Method. For the REST API, these HTTP-Methods are mapped to CRUD operations. For example, the GET method is used to read customer information and the POST method is used to add an order. The table below lists the most commonly used HTTP methods and for what purposes they should be used.
| HTTP-Methods | CRUD | SQL |
|---|---|---|
| GET | Read | SELECT |
| POST | Create | INSERT |
| PUT/PATCH | Update | UPDATE |
| DELETE | Delete | DELETE |
Resource
In REST architecture, each content is treated as a resource. These resources are mostly JSONs, images, or videos. The REST API provides access to the resources and the client can read, update, create a new entry or delete the resources.
Naming
It should be possible to form a sentence from a REST call, from which the naming convention is derived. The verb of the sentence is the HTTP method and the noun is the URI. The nouns are always used in the pural form.
- Here are some examples:
- GET method with https://localhost:.../customers -> Read (GET) all customers.
- POST method with https://localhost:.../customers/2348 -> Create (POST) new customers resource.
- GET method with https://localhost:.../customers/2348 -> Read (GET) customers with id 2348.
As you can see that there are two types of resources Collection Resource and Instance Resource. Collection Resources are read by a common URI and for Instances Resources a ID is appended to the URI.
MIME-Type
MIME is the acronym for Multipurpose Internet Mail Extensions which is used to specify the format of the data.
- With the MIME type
- the client tells the server in which format it expects the response. -> accept = application/json
- the server tells the client which format the response has. -> content-type = application/json
HTTP-Status
An HTTP status code is provided by a server in response to each HTTP request. The first digit of a status code represents the status class: 2xx for a successful operation, 4xx for an incorrect request from the client, and 5xx for errors that are in the responsibility of the server.
| Status Code | Description |
|---|---|
| 200 | OK; used as response code for GET |
| 201 | Created; used as response code for POST |
| 204 | No content; used as response code for PUT, PATCH, DELETE |
| 400 | Bad Request; invalid data in the request |
| 401 | Unauthorizied |
| 403 | Forbidden |
| 404 | Not found |
| 500 | Internal Server Error |
| 502 | Bad Gateway |
| 503 | Service Unavailable |
Making a Call
To make our first REST request, we bring together the things we've already learned. For this we take the , the URI ../customer together with the id 3569 and the MIME types application/json as we expect the data in JSON format, as shown below in the example the GET method.
Summary
Finally, a summary of the most important points in compact form
| URI | HTTP-Method | Representation | Description | Response |
|---|---|---|---|---|
| /customers | GET() | JSON | get all customers resources | 200 - List of Customers |
| /customers/{id} | GET(UUID id) | JSON | get customer resource with given id | 200 - Customer |
| /customers | POST(Data data) | JSON | create new customer resource | 201 - URI (to new customer resource) |
| /customers/{id} | PATCH(Delta delta) | JSON | update customer resource with given id | 204 |
| /customers/{id} | DELETE(UUID id) | -- | delete customer resource with given id | 204 |
Wrap Up
That's it for this post. We have seen how a REST request is built and how it works in detail. This information will be used in the next step to create a REST API.
There will be more post to follow in this series "Building a REST API".
See you then!
Top comments (0)