Restful design of read only list, with the exception of one published and one draft item

Question

I have the following domain specs:

A historic read only list of items that were published and a currently published item (if any) and an optional draft item (if any).

I thought of the following design:

Publicly accessible:

GET /items

# Returns list of items excluding optional draft

GET /item/published

# returns currently published item

Restricted access to an editor:

PUT /item/published

# update published item

GET /item/draft

# returns current draft item

PUT /item/draft

# update draft item

PATCH /item/draft
{publish: true}

# publish draft item
# replaces /item/published with this draft and clears /item/draft

As you can see: I don't have a need to update historic items or return them individually, so they are not identified by an ID.

Is the above design in the spirit of REST, or are there serious flaws?

For instance:

• Is promoting /item/draft to /item/published (and thereby simultaneously deleting its contents) by PATCHing it acceptable?
• Is not using IDs to individually identify items acceptable?

Answer 1

Is promoting /item/draft to /item/published (and thereby simultaneously deleting its contents) by PATCHing it acceptable?

It's a bit twitchy. The key idea behind REST is that everybody agrees what messages mean. Therefore, a general purpose component (like a web browser) can be used to interface with your resource model without needing to know anything about the underlying implementation.

PUT/PATCH/DELETE are all method tokens with "remote authoring" semantics. They are the methods we would use to update the contents of an HTML page on a web server (think "save file" or "delete file").

The IANA method registry shows us that the currently registered reference for PATCH is RFC 5789. Roughly, it means "apply the changes described in this patch document to the target resource", with the additional constraint that "partial application" of the changes is not permitted.

The riddle then becomes: how do you create an HTTP response message that a general purpose client will understand (in this case, that a different resource is now important)?

Given that the request says "apply my changes to your copy of the resource", instead turning around and deleting that representation is... not something that you should expect to "just work".

You'd be better off using POST, where the method semantics are not so tightly constrained.