I've implemented CRUD functionality pretty restfully in my WebAPI project. I'm now trying to implement Archiving of objects (not quite deleting) - if only there were an ARCHIVE
HTTP method.
I see two options:
1) Have isArchived
as a property of every archive-able entity, which must be included in PUT and POST requests even if archiving isn't relevant to the request. Archiving an entity would be a matter of calling PUT /api/object/id
with isArchived set to true. Seems bulky on the wire but restful.
2) Have an RPC-ish url like PUT /api/object/id/archive
that doesn't require a body. Seems the most efficient but not restful.
What's everyone doing in the "archive my stuff via an api call" space?
This is an excellent question, but I suspect it may eventually be marked as opinionated because I don't see a correct answer... as the OP also stated.
I would recommend treating the archive as a separate object store (or, even, different object types), if that makes sense for your system. Object design should not depend upon how the DB persists your data.
Thus, this is the most RESTful design I can come up with right now (assuming archiving and updating are always separate actions -- which they should be):
Typical (everybody knows this):
GET /api/object get all current objects
POST /api/object new current object
PUT /api/object/id update current object
DELETE /api/object/id delete current object
GET /api/object/id get current object
The weirdness:
POST /api/object/id/archive move object to archive (makes some REST sense)
POST /api/object/id move object from archive (muddy)
The archive:
GET /api/object/archive get all archive objects
PUT /api/object/id/archive update archive object (if possible)
DELETE /api/object/id/archive delete archive object (tempting for unarchive)
GET /api/object/id/archive get archive object
Or, maybe one of these mods for archive URLs:
GET /api/object/archive/id get archive object
GET /api/objectarchive/id get archive object
The above feels pretty muddy (not very self-documenting) for moving objects in and out of the archive. It also leads to some REST API design pain where update/delete/get of an archived object probably don't need archive-specific functions. Thus, I ultimately settled on this:
GET /api/object get all objects
GET /api/object?archived=false get all current objects
GET /api/object?archived=true get all archive objects
POST /api/object new current object, returns all current objects*
PUT /api/object/id update object (current or archived; cannot change archive state)
DELETE /api/object/id delete object (current or archived), returns objects of same archive state as deleted*
GET /api/object/id get object (current or archived)*
PUT /api/object/id/archive body:{archived:true} move object to archive, returns all current objects*
PUT /api/object/id/archive body:{archived:false} move object from archive, returns all archive objects*
* Return could be expanded/overridden with a query string if design calls for it.
Admittedly, this is mostly a reversal from my earlier statement of treating the archive as a separate object store. Yet, that thought process is what ultimately led to this compromise in design. This feels good to me on most fronts.
I, personally, don't agree with using the query string for anything but... uh... queries. So, I don't. Payload for data changes -- no matter how small -- should go in the body (when it doesn't fit with a REST verb and URL, that is).
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With