-3

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?
1
  • 1
    Would anyone like to elaborate on why they deem my question down-vote-worthy? I'd like to improve the question, if possible. Cheers. Commented Oct 15, 2022 at 18:18

1 Answer 1

0

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.

1
  • Thanks for your answer. To answer "how do you create an HTTP response [...]?": Perhaps with 303 See Other and a Location: /item/published header? And after reading RFC 5789, I don't actually see anything that discourages my intended use of PATCH (but maybe I've overlooked something). In fact, it actually appears to suggest my use of PATCH is perfectly acceptable: "The PATCH method affects the resource identified by the Request-URI, and it also MAY have side effects on other resources; i.e., new resource may be created, or existing ones modified, by the application of a PATCH." Commented Oct 16, 2022 at 1:20

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.