0

I am designing an API that some operations may take a while, for example, creating a backup (not the actual case).

I am planning to have an endpoint to query the current job

http GET /api/v1/jobs/{uuid}

{
  "code": 1,
  "status": "created",
  "running": true,
  "completed": false
}

To create a new task, the client should do a POST which will return an empty response

http POST /api/v1/backups

I am planning to return a header Location pointing to the current job uuid

Is it okay to a RESTful API? More specifically, should a 201 response to a POST request contain a body?

Improve this question
8
  • 1
    "Is it okay to a RESTful API" - doesn't really matter in any meaningful way. But, why not just return the location in the body, e.g., as JSON, for consistency? If I'm a consumer of your API, why make me write special-case handling for this?
    – Filip Milovanović
    Jun 9, 2022 at 13:47
  • 2
    The status code 201 spec states that you can return a body, in some format of your choice, typically with a list of URIs (+ maybe some metadata) identifying the resource(s) created, so that the user agent (read: browser) can choose the one that it likes. The Location header then indicates "the most specific URI", or the primary resource. See: 1, 2 1/2
    – Filip Milovanović
    Jun 9, 2022 at 14:38
  • 2
    In the original (actual) REST, which is a generalized description of the architecture of the Internet (or Internet-scale systems), this is part of a wider protocol, and was designed as part of a larger effort meant to address the needs of such a system. RESTful APIs are not such systems; they are really a different thing, inspired by REST. The 201 spec is simply adopted, but unless you're a browser, or unless you and the consumers of your API are specifically designed to work under this convention, nothing is really gained here. It's mostly cargo-culting. 2/2
    – Filip Milovanović
    Jun 9, 2022 at 14:38
  • 1
    @FilipMilovanović, could you make an answer out of those comments?
    – Bart van Ingen Schenau
    Jun 9, 2022 at 14:45
  • 1
    Since the resource has not been yet created (is an asynch batc process), my bet would be HTTP 202 Accepted. You can send the status of the running job or it's location within the response body. Which is not much different than sending the job's uri through the http response headers
    – Laiv
    Jun 11, 2022 at 11:08

0

Reset to default

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Browse other questions tagged or ask your own question.