RESTful API design, naming drafting endpoints

Question

When naming an endpoint for creating a "draft" version of a resource which is best practice?

POST >> /posts

{
    title: 'My Post',
    body: 'The content of my post',
    status: 'DRAFT',
}

Or is it better to:

POST >> /posts/drafts

{
    title: 'My Post',
    body: 'The content of my post',
}

Answer 1

From what I saw on the payload, the DRAFT is just status of the resource. you can use PUT to update it.

would you explain more on why you want to DRAFT in the URI path?

Answer 2

As with most of the things I'd say it depends. The general assumption when working with REST is that you've got collections of resources. That's why the most common naming convention is to use plurals when naming endpoints.

When I see and endpoint called /posts I'd assume that by doing a GET to it I would receive a collection of posts. Similarly by calling /posts/{id} I should receive a post with a particular id. Resource collections are also embedded in each other - when I see an endpoint /posts/{id}/drafts I'd assume that I would get drafts for a post with a given id.

Now the question is this - do you want to treat your data as two separate collections (which you would have to synchronize somehow) or do you want to stick with this being embedded collections? If the first then you could have two endpoints /posts and /drafts . If the second then you should go with the root endpoint /posts and then /posts/{id}/drafts .

However if a post doesn't have a collection of drafts, you could just simply go with a single /posts endpoint and don't specify any additional things, as this will mess up the design of your API. Just as in your first proposition.