Multiple entity replacement in a RESTful interface

Question

I have a service with some entities that I would like to expose in a RESTful way. Due to some of the requirements I have some trouble finding a way I find good.

These are the 'normal' operations I intend to support:

GET /rest/entity[?filter=<query>] # Return (matching) entities. The filter is optional and just a convenience for us CLI curl-users :)

GET /rest/entity/<id> # Return specific entity

POST /rest/entity # Creates one or more new entities

PUT /rest/entity/<id> # Updates specific entity

PUT /rest/entity # Updates many entities (json-dict or multipart. Haven't decided yet)

DELETE /rest/entity/<id> # Deletes specific entity

DELETE /rest/entity # Deletes all entities (dangerous but very useful to us :)

Now, the additional requirements:

• We need to be able to replace the entire set of entities with a completely new set of entities (merging can occur internally as an optimization).

  I thought of using POST /rest/entity for that, but that would remove the ability to create single entities unless I move that functionality. I've seen /rest/entity/new-style paths in other places, but it always seemed a bit odd to reuse the id path segment for that as there might or might not be a collision in IDs (not in my case, but mixing namespaces like that gives me an itch :)

  Are there any common practices for this type of operation? I've also considered /rest/import/entity as a separate path for similar non-restful operations for other entity types we might have, but I don't like moving it outside of the entity home path.

• We need to be able to perform most operations in a "dry-run"-mode for validation purposes.

  Query strings are usually considered anathema, but I'm already a sinner for the filter one. For the validation mode, would adding a ?validate or ?dryrun flag be ok? Have anyone done anything similar? What are the drawbacks? This is meant as an aid for user-facing interfaces to implement validation easily.

We don't expect to have to use any caching mechanism as this is a tiny configuration service rarely touched, so optimization for caching is not strictly necessary

Answer 1

We need to be able to replace the entire set of entities with a completely new set of entitiescompletely new set of entities

That's what this does, no?

PUT /rest/entity

PUT has replace semantics. Maybe you could use the PATCH verb to support doing partial updates.

Personally, I would change the resource name to "EntityList" or "EntityCollection", but that's just because it is clearer for me.