Building a REST API: Basics

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!