I've come up with the mapping that follows while working on the REST API of a system where users are able to create and manage resources of different types.
// READ OPERATIONS
GET /objects => read collection meta
GET /objects/[id] => read single element
GET /objects/?[query] => read a number of elements
GET /objects/?all => read all elements
// CREATE / UPDATE OPERATIONS
PUT /objects => possibly create the collection and update its meta
PUT /objects/[id] => possibly create and update a single element
PUT /objects/?all => update the entire content of the collection
POST /objects => create new objects or update existing objects
PATCH /objects => partially update the collection meta
PATCH /objects/[id] => partially update a single element
PATCH /objects/?all => partially update all the elements
PATCH /objects/?[query] => partially update a number of elements
// DELETE OPERATIONS
DELETE /objects => delete the collection
DELETE /objects/[id] => delete a single element
DELETE /objects/?all => empty the collection
DELETE /objects/?[query] => delete a number of elements
Here's some more information on the system:
I've also examined the following alternatives:
/collection
to access the collection's set of elements and /collection?meta
to access the collection's own data;/collections/path/to/collection
.I do not like alternative n. 1) because it feels, to me, semantically poor. By comparison, when I refer to a box I am actually referring to the box in itself and not to its content.
I do not like alternative n. 2) because a resource ends up having its own data exposed by another resource, duplicating urls and making the problem of "which url should I use" not that trivial as I'd like it to be.
Therefore, my questions:
Please excuse my english, I'm not a native speaker of the language.
I thought the API design looked OK, but then I re-read this comment of yours at the start:
where users are able to create and manage resources of different types.
If the resources of your system are of different types, why are you exposing them with a neutral, type-less API that works only with generic object
s?
The first part of RESTful API design is the identification of the nouns in your system, and those nouns should be considered strongly as candidates for exposure as URIs. I would strongly encourage you to try and get more specific than object
and model the business functionality of your system with clearer URIs.
And your English is fine!