Naming complex actions in the REST API
In all the manuals in the REST descriptions give simple examples, such as here you are the users, they will be the / users resource, here you are one user, it will be / users / [id] and add \ delete \ edit actions with it.
And what if actions are complex or complex and do not fit into GET \ POST \ DELETE?
')
Trying to figure it out, asked a question on a toaster and continued further excavations.
I found an exhaustive article , but I will not master a full translation, so I’ll summarize the findings in a short note.
Suppose we are writing a nuclear suitcase application with a REST interface. The functionality will be as follows:
1. Actions with a rocket [id]: launching around the country, selling into the country, servicing, write off for scrap
It is logical to use the / missiles / [id] resource, but for these actions it is simple to use PUT or PATCH incorrectly and uninformatively.
Wrong options:
1. You can expand the list of standard HTTP-methods. But there may be difficulties with the support of different clients, ready-made libraries and filtering server settings.
2. / missiles / [id]? Action = launch deprives the whole REST approach, since Most of the functionality will be in action.
3. / missiles / [id] / launch - drag the verb to the address of the resource incorrectly.
4. LINK / missiles / [id] / countries / [country_id] / - it is not clear what exactly is happening - sale or nuclear strike.
Correct option
Correctly refer to the properties of the resource. Those. not the action "/ users / [id] / disable", but the resource "/ users / [id] / disable d ", to which the standard methods GET \ POST \ ... are logically applicable
Rocket launch: POST / missiles / [id] / countries-landed / [country_id]
Missile sale: POST / countries / [country_id] / missiles-bought / [id] or POST / missiles / [id] / owner / [country_id]
Service: POST / missiles / [id] / on-service
UPD:
Rocket launch: POST / missiles / [id] / launcher {target: [country_id]}
Missile sale: PATCH / missiles / [id] {owner: [country_id]}
Service: PUT / missiles / [id] / on-service or if there is a separate service for the maintenance of missiles POST / missiles_service / {missile: [id]}
Write off to scrap: DELETE / missiles / [id] or if there can be other options for “deleting” PUT / missiles / [id] / utilized
2. Launch any suitable missile in the country [country_id]
Suppose that the rockets are very dofig and do a search first, and then launch it is expensive and long, we need one request for instant execution.
Wrong options:
1. Run the "launch" on the entire collection of rockets ([id] of a specific rocket, we do not know).
2. The action "get a rocket" from the selected country
Correct option
If the action is complex and cannot be expressed through atomic actions on the resource object, a process resource is created. Similarly, a resource process is created in case you need to perform a composite action with complex business logic (consisting of several dependent actions), for example, a banking transaction.
Those. the creation of the “Rocket launch” resource will be correct.
Then POST will launch a rocket, GET to find out the status of the process, DELETE cancel it. This preserves the consistency, i.e. the rocket is already flying, and the country's status "still exists."
Bonus:
It turned out that many large companies do not have any idea what REST is, and this name is used in the description. So you can not trust everything that is writtenon the fence, even in large.
A couple of examples of Achtungs:
The only decent REST API I could detect is GitHub . Amen.
And what if actions are complex or complex and do not fit into GET \ POST \ DELETE?
')
Trying to figure it out, asked a question on a toaster and continued further excavations.
I found an exhaustive article , but I will not master a full translation, so I’ll summarize the findings in a short note.
Briefly about the problem:
The main difference between REST and RPC is in the approach that the URL is the resource whose actions are performed using standard HTTP methods: GET \ POST \ DELETE \ PATCH \ ... In short, the resource is a noun, not a verb.
Those. if you see something like / api / users / do_some_cool_staff or GET / users / 1? action = delete, you know - this is not REST!
Suppose we are writing a nuclear suitcase application with a REST interface. The functionality will be as follows:
1. Actions with a rocket [id]: launching around the country, selling into the country, servicing, write off for scrap
It is logical to use the / missiles / [id] resource, but for these actions it is simple to use PUT or PATCH incorrectly and uninformatively.
Wrong options:
1. You can expand the list of standard HTTP-methods. But there may be difficulties with the support of different clients, ready-made libraries and filtering server settings.
2. / missiles / [id]? Action = launch deprives the whole REST approach, since Most of the functionality will be in action.
3. / missiles / [id] / launch - drag the verb to the address of the resource incorrectly.
4. LINK / missiles / [id] / countries / [country_id] / - it is not clear what exactly is happening - sale or nuclear strike.
Correct option
Correctly refer to the properties of the resource. Those. not the action "/ users / [id] / disable", but the resource "/ users / [id] / disable d ", to which the standard methods GET \ POST \ ... are logically applicable
UPD:
Rocket launch: POST / missiles / [id] / launcher {target: [country_id]}
Missile sale: PATCH / missiles / [id] {owner: [country_id]}
Service: PUT / missiles / [id] / on-service or if there is a separate service for the maintenance of missiles POST / missiles_service / {missile: [id]}
Write off to scrap: DELETE / missiles / [id] or if there can be other options for “deleting” PUT / missiles / [id] / utilized
2. Launch any suitable missile in the country [country_id]
Suppose that the rockets are very dofig and do a search first, and then launch it is expensive and long, we need one request for instant execution.
Wrong options:
1. Run the "launch" on the entire collection of rockets ([id] of a specific rocket, we do not know).
2. The action "get a rocket" from the selected country
Correct option
If the action is complex and cannot be expressed through atomic actions on the resource object, a process resource is created. Similarly, a resource process is created in case you need to perform a composite action with complex business logic (consisting of several dependent actions), for example, a banking transaction.
Thought more fully
The dissertation says about the resource: “... Business capabilities / processes can neatly fit the definition of resources. In other words, for complex business processes, we can consider the process itself. For example, it can be modeled as a resource. CRUD is just a minimal business process. It can be tracked in their own right.
Those. the creation of the “Rocket launch” resource will be correct.
Then POST will launch a rocket, GET to find out the status of the process, DELETE cancel it. This preserves the consistency, i.e. the rocket is already flying, and the country's status "still exists."
Bonus:
It turned out that many large companies do not have any idea what REST is, and this name is used in the description. So you can not trust everything that is written
A couple of examples of Achtungs:
- Twitter
POST friendships / create
POST friendships / destroy
POST friendships / update
GET friendships / show
GET friends / list - Mail.ru
All API method calls are GET or POST HTTP requests to the URL www.appsmail.ru/platform/api with some set of parameters. [...] At the moment, the API does not distinguish between GET and POST requests.
The only decent REST API I could detect is GitHub . Amen.
Source: https://habr.com/ru/post/251193/
All Articles