HTTP Status 202 indicates that the request has been accepted for processing, but the processing has not been completed. This status code is useful when the actual operation is asynchronous in nature.
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.
1. Response Entity
The entity returned with this response SHOULD describe the request’s current status and point to (or embed) a status monitor that can provide the user with (or without) an estimate of when the request will be fulfilled.
2. HTTP Status 202 – Example
If you submitted a long-running asynchronous job to a REST API then API can return the result like this:
HTTP STATUS 202 (Accepted)
{
"task": {
"href": "/api/company/job-management/jobs/2130040",
"id": "2130040"
}
}Now user agent can send HTTP GET requests to URI /api/company/job-management/jobs/2130040 periodically for the completion status of the job.
The response of the above API will inform the current status of the actual scheduled operation.
2.1. Job Not Started
{
"job" : {
"@uri" : "/api/company/job-management/jobs/2130040" ,
"id" : "2130040",
"name" : "Update Resource",
"job-state" : "SCHEDULED",
"job-status" : "UNDETERMINED",
"percent-complete" : "0",
"scheduled-start-time" : "01-01-2013 10:50:45 PM GMT",
"start-time" : "",
"end-time" : "",
"owner" : "Admin",
"summary" : "random text"
}
}2.2. Job Started
{
"job" : {
"@uri" : "/api/company/job-management/jobs/2130040" ,
"id" : "2130040",
"name" : "Update Resource",
"job-state" : "STARTED",
"job-status" : "INPROGRESS",
"percent-complete" : "30",
"scheduled-start-time" : "01-01-2013 10:50:45 PM GMT",
"start-time" : "01-01-2013 10:50:55 PM GMT",
"end-time" : "",
"owner" : "Admin",
"summary" : "random text"
}
}2.3. Job Completed
{
"job" : {
"@uri" : "/api/company/job-management/jobs/2130040" ,
"id" : "2130040",
"name" : "Update Resource",
"job-state" : "COMPLETED",
"job-status" : "SUCCESS",
"percent-complete" : "100",
"scheduled-start-time" : "01-01-2013 10:50:45 PM GMT",
"start-time" : "01-01-2013 10:50:55 PM GMT",
"end-time" : ""01-01-2013 10:52:18 PM GMT",
"owner" : "Admin",
"summary" : "random text"
}
}The above example is for reference only.
Reference: HTTP Status 202 (Accepted)
What HTTP status code should ‘/api/company/job-management/jobs/2130040’ return?
Should it return a `200` (yes, here’s your status), or a `202` (I’ve accepted your request for the status of the job)
A `200` makes perfect sense to me as the ‘request for the status of the job’ *is* ready (and the *status of the job* is contained within the payload)
Generally, when an API returns 202 status, it also returns a Location URI where the job status should be tracked. The API which returns the current status of a long running Job should return status code 200.
unlike what the RFC-7231 Section 6.3.3 says
The representation sent with this response ought to describe …
not “SHOULD”, which is to be interpreted as described in RFC-2119. I assume the authors carefully choose their words. And therefor leaving all us API-designers in confusion.