Building a REST API: Basics
Tags: webdev, tutorial, beginners, api
Published: 2022-11-11 09:17:15

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.


![Visual representation of a REST request](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/r6vr5rn207oj6bcz1hyg.png)

## 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!