So I'm creating a RESTful API that manages a list of order in a DB. There is an option to create an order, then users can update/edit the order and eventually call a POST /orders/{id}/send endpoint to send the order.
Now, we found out that often times we do not need to edit the order and can just create & send directly. Since it's a bit messy to deal with multiple sequential request in the frontend I though it to be a good idea to make a Create & Update request.. would that go against the RESTful pattern?
And if it doesn't what would be the best way to do it (semantically).. Would it fit to just use the create-method have an optional sendDirectly query or header parameter? Or would it make more sense to have an entirely different endpoint for that?
What do you think?
Since it's a bit messy to deal with multiple sequential request in the frontend I though it to be a good idea to make a Create & Update request.. would that go against the RESTful pattern?
No, it would not. Think about how it would work on the web: somebody navigates to a form, fills in information, submits the form... and then the back end does whatever it does with the result.
Would it fit to just use the create-method have an optional sendDirectly query or header parameter?
The resource identifier identifies a resource; the query is part of that. So you shouldn't be overloading the query with payload semantics.
The normal way to deal with this would be to have an optional field in the schema of the payload of the request. On the web, you might inform the client of this field via a hidden input control in a form.
would it make more sense to have an entirely different endpoint for that?
Maybe, but probably not. What you normally want to do is identify the primary resource that will be changed by the request, and use the identifier of that resource as the target-uri for the request, so that the standard cache invalidation rules do what you want.
Yes, that means you might have multiple forms that submit different information to the same resource using the same method. You design the payloads so that the server can tell them apart, and you perform your discrimination there.
(Note: it seems that OpenAPI 3 doesn't support documenting an API like this; "this is a feature of Swagger's opinion on API". Sometimes you have to choose where to compromise.)