We are using HTTP protocol to trigger an asynchronous action on the web server, which later in the background loads data from another server and writes them into our server's database.
┌──────┐ ┌──────┐ ┌───────────┐
│client│ │server│ │data-source│
└──┬───┘ └──┬───┘ └─────┬─────┘
│ │ │
│ ?METHOD? /sync-data │ │
│────────────────────→│ │
│ │ │
│ 202 ACCEPTED │ │
│←────────────────────│ │
│ │ │
│ │ Fetch data │
│ │───────────→│
│ │ │
│ │ [data] │
│ │←───────────│
│ │ │
│ │───────╮ │
│ │ Store │ │
│ │ data │ │
│ │←──────╯ │
│ │ │
┌──┴───┐ ┌──┴───┐ ┌─────┴─────┐
│client│ │server│ │data-source│
└──────┘ └──────┘ └───────────┘
(Credit for ASCII sequence diagram online tool: https://arthursonzogni.com/Diagon/#Sequence)
The question is, which HTTP method is the best for the call?
I am not asking for an opinion, but for well-informed answer which of the HTTP method is more corresponding to the industry standards in this particular case.
I collected arguments for and against each of the method.
In "Normal purpose" I am influenced how we use CRUD-HTTP mapping with REST.
| Method | Normal purpose | Why to use it in my case | Why not |
|---|---|---|---|
| GET | Read data | • Request does not immediately change server status • No body • Most simple for testing |
• Eventually server status changed |
| POST | Create a new object | • It is a common method used for changes | • The character of the triggered asynchronous action is not Create • After the method returns, the server status is not yet changed |
| PUT | Replace an existing object | • Sounds fine, but... | • The data which will replace the server data are not part of this request • After the method returns, the server status is not yet changed |
| DELETE | Delete an existing object | N/A | N/A |
| PATCH | Partially update an existing object | N/A | • We are not changed "some fields of a record" • The data which will replace the server data are not part of this request • After the method returns, the server status is not yet changed |
I am not asking anyone's opinion, what I want is to know which of the HTTP method corresponds the best with the above mentioned use case, according to standards. I might have some opinion on it, but I want my opinion to be supported by what the industry standard is. My arguments and counter-arguments collected in the table might look like "opinion-based", but that's how people are searching for an answer - sorting out what they know so far.
Please consider this before quickly connecting the phrasing "which is the best" with "opinion-based".
The question is, which HTTP method is the best for the call?
POST
Your notion that the POST method's "normal purpose is for creating a new object" is misguided.
In actuality, the current HTTP specification (RFC 9110, June 2022) describes POST thusly (emphasis mine):
The
POSTmethod requests that the target resource process the representation enclosed in the request according to the resource's own specific semantics.
For asynchronous processing of requests, HTTP server should respond with HTTP 202 Accepted:
The 202 (Accepted) status code indicates that the request has been accepted for processing, but the processing has not been completed.
[...]
The 202 response is intentionally noncommittal. Its purpose is to allow a server to accept a request for some other process (perhaps a batch-oriented process that is only run once per day) without requiring that the user agent's connection to the server persist until the process is completed. The representation sent with this response ought to describe the request's current status and point to (or embed) a status monitor that can provide the user with an estimate of when the request will be fulfilled.