Introduction
In this course we will take a look on how to write API specs in Frends. You will learn about path version numbers, what formats are supported and how to use the Swagger editor in Frends.
APIs are great way to utilize your Frends and create an API based integration between different systems.
HTTP methods
Frends API is developed to be done Restful way. This will give some guidelines how to build you APIs and what principles you can take into consideration when developing you APIs. REST APIs have these HTTP methods which describe the functionalities of the resource.
GET
Get requests are used to retrieve data and resources from the server and it should never contain a request body. Request body is allowed but it should not have any semantic value.
POST
Post requests are for creating new resources. You can use Post to update existing data but in order for it work you need to deliver the whole structure of the updated resource which usually means that you need to first retrieve the resource with Get request before making the necessary modifications and posting the resource with the Post request.
PUT
Put requests are for replacing a resource and that's why it's usually mixed up with the Patch verbs. Put request does an exact replacement of the resource with given data.
PATCH
Patch requests are for actual updating and modifying of resources and it can handle for example partial modifications to the resource.
DELETE
Delete requests are for removing of existing resources.
Idempotence
POST is the only HTTP method which is not idempotent. This means that Post request can be executed certain amount of times and with every request the server will have the same amount of new resources. All other methods should always be implemented in that way that they will remain idempotent and the resource state will not change after the first request. Especially Delete method can be dangerous if idempotence is not taken into consideration. Imaging a situation where you have an endpoint /items/last with a Delete method attached. This could lead to a situation where a looping mechanism of these requests could remove all items from the server's items catalog.
The next article is Introduction to API Specification naming and versioning.