RESTful design: distinguish between unpublish and delete [closed] - api

Question

Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 4 years ago.
Improve this question
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

Answer 1

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. ;)