POST to a collection

[jonathanrobie]

The document currently requires a parent parameter for post:

parent
identifier for the collection under which a new collection or document is to be created.

The usual REST idiom is that a POST to a collection URI creates a new item as a child of the target resource.

I don't particularly like this version either:

There are no required query parameters for a POST request to the Collections endpoint. The one optional parameter is parent. This should be the unique identifier of an existing collection. If a parent is supplied, then the new item will be created as a child member of that collection. Otherwise the new item will be created at the top level of the target repository.

I prefer not to rely on query parameters to know where a resource is going to be created. The semantics of POST on a collection URI are generally pretty standard, we should stick to them.

[monotasker]

Okay. I take your point about creating as a child for an identified collection. I'm happy to change that.

I'm not sure what the alternative is (in your response to the quote) for creating a root-level collection. If we're allowing CRUD for collections, I think we need the api to be able to create a new root-level collection. If we follow the logic you suggest, wouldn't that be natural if no collection id is supplied? The new collection is created as a child of the bare endpoint, rather than as a child of any existing collection.

[jonathanrobie]

There are at least two possibilities.

• State that there must be at least one root-level collection, which may be empty, and may not actually be instantiated until something is put into it, or
• Provide a way to create a root-level collection.

The first approach is simpler.