How to correctly name complex actions in REST API?

Question

PHP

Good afternoon!
In all manuals, REST descriptions give simple examples, such as here you have users, they will be the /users resource, here you have one user, it will be /users/[id] and add / delete / change actions with it.
Suppose we are writing a "nuclear suitcase" application with a REST interface. Functionality: 1. Actions with rocket [ id
]: launch in the country, sale to the country, service, scrap
fit in.
There is an option to expand the list of standard HTTP methods, but somehow it is not ideologically correct. Plus, there may be difficulties with support for different clients and ready-made libraries.
Doing /missiles/[id]?action=launch makes the whole REST approach meaningless, because most of the functionality will be in actions.
Doing /missiles/[id]/launch - dragging the verb to the resource address - is also wrong.
2. Launch [id] rocket at country [country_id].
With some humor, you can do PATCH or LINK /missile/[id]/country/[id], but this is a one-time action, not a permanent connection.
Again, there are several similar actions (sell to a country or run across a country), i.e. it will not be obvious which of them is which, and the number of standard methods is limited.
It is possible to make the action "be gouged" for the /countries/[id] resource, but this is delusional in meaning.
3. Launch any suitable rocket at [country_id].
Suppose that there are a lot of missiles and doing a search first, and then launching is expensive and long, you need one request for instant execution.
The point is that we don't know the [id] of a particular missile, it is incorrect to perform the "launch" action on the entire collection of missiles.
4. Actions that do not have a resource
There is, for example, the action "hold a parade". There are no related resources, only the verb.
Drag it to the URL /start_parade ?

Answer 1

Based on the results of the excavations and the conclusions made, he published an article: habrahabr.ru/post/251193

Answer 2

In the REST ideology, you need to think in terms of decomposition of the subject area of ​​the task into resource objects (with the corresponding URLs), and verbs(actions) are strictly fixed (fixed, including in the HTTP protocol). This achieves scalability (in every sense) of the developed web service. If a wide variety of actions, rather than objects, is seen in the application area, then they can be perceived in the style of workflow documents or payment system transactions. For example, a rocket launch across a country can be represented as the creation of a document (transaction) "rocket launch across a country". You can design it both as a resource nested in a rocket, and as a root resource with the attributes "rocket" and "country" - this depends on the physical and logical organization of the service. Such a resource-document can be provided with an identifier and given the opportunity to be processed on any server included in the web service infrastructure, to read automatically generated attributes of the type "

Answer 3

All imho
1) POST /missiles/[id]/launch seems quite normal to me
2) POST /missile/[id]/country/[id] seems quite normal to me
3) POST /country/[id]/destroy ;)
4 ) POST /parade/start

Answer 4

I read a lot where, and I myself stick to using parameters in non-standard queries.
Again, you need to determine the main resource with which you are working, in your example, most likely it is a rocket.
This resource can have a state or an action (depending on the architecture, which is better).
An example with a rocket in which we change the state: (In this case, the table with rockets should have a target field)
PUT rocket/23/?launch {'target': 'usa'} The
example with actions implies more opportunities for using rockets. In this example, there should be a separate rocket_action table with fields: action, state, target...
Request to sell the rocket:
POST rocket/23/?sale {'target': 'pakistan', 'price': 235000};
(accordingly, the controller that is responsible for processing this action should remove the missile from the missile table or change its state)
As for the actions under points 3 and 4:
3 - Such actions should be better divided into sub-actions: 1. request which missile is free (or closer all to this country) 2. launch this rocket into the country.
4 - I think that here it is necessary to revise the architecture of the application, if there is no entity with which we can perform an action. For your example, allocating a separate rocket for the parade would be better POST rocket/23/?start_parad {'place': 'Moscow'}
In general, REST is a rather abstract architecture. Here, first of all, you need to think about what the user wants to receive by sending this request, and only then how logical it is in technical terms of the built architecture.

Answer 5

I think you've got the HTTP methods mixed up in your head and the method names in the address.
otherwise I can't explain the phrase
What is so unusual about the REST method name "missiles" - I don't understand