-2

Designing an API and looking for some advice.

Here's the actions:

  • publish : publish the document (POST)
  • update : update the document (PUT or PATCH)
  • unpublish : take the document down with the intention of putting it up later (?)
  • delete : remove the document completely (DELETE)

Any ideas?

Thanks! Matt

Matt
  • 22,224
  • 25
  • 80
  • 116

1 Answers1

2

  • Update and delete are pretty obvious, as you have them.

  • Do you consider "publish" the same as "create"? "Publish" can mean taking a document you've created and making it publicly visible. One way to think of it is, you can only create a document once, but then you can publish and unpublish it many times.

You might think about the lifecycle of the document, and what you can do with it after "unpublish". It kind of depends on what you want the sequence: "create (publish?) ... unpublish ... publish ... unpublish ... delete" to do. If publish/unpublish don't do anything different than create/delete, then you can just drop them and avoid the complexity altogether.

  • The purist REST answer is to provide a property in the representation: { ... "published": true ... } and let the client PUT an update to change that state. If that state changes, it triggers whatever processing is needed to publish or unpublish the document.

  • However, I was on a team that was uncomfortable with that because there can be big implications, publicly and technically, to publishing a document. So they chose instead to treat the operation as a POST "data processing" request (as the HTTP spec provides) and provide a POST URL to "publish" and "unpublish" the document.

  • There are some other options. Like take POST as the append verb, and provide a "published list" URI that allows you to add a document to the published list, doing any processing that's required:

    POST ht_p://.../documents { the document }

    POST ht_p://.../published-documents { id= }

    DELETE ht_p://.../published-documents/{id}

    DELETE ht_p://.../documents/{id}

edit: broke the prentend URIs because stackoverflow complained. ;)

sea-rob
  • 2,275
  • 1
  • 22
  • 22
  • thanks your thoughts! I'd like to avoid distinguishing between published and unpublished documents. What are your thoughts on using a querystring to distinguish? something like `DELETE /?action=unpublish`. Unpublish will probably not be a common pattern. – Matt Jan 10 '13 at 06:28
  • oh and `create = publish` in this case. – Matt Jan 10 '13 at 06:28
  • I probably wouldn't call it "action", just because you're not supposed to do that in REST (the HTTP verb is supposed to signal your action). But you could treat it as a modifier to the request, and call it "unpublish_only=true" or "permanent=false" or "erase=true" or somesuch. Ya I know that kind of sounds like a word game... but well... – sea-rob Jan 10 '13 at 08:00