monotasker / specifications Goto Github PK

Assuming that the implementation wants to maintain control over who can create and modify server data, the new token parameter also allows for token-based authentication (as with OAuth 2.0) if desired. It is up to the implementation to decide how such tokens should be generated and processed.

Authentication is orthogonal to updates. Different environments may want to do this in different ways.

Currently, DTS does not have optional extensions. If we introduce them, how does a client discover which extensions are supported on a given server?

An alternative would be to say that a client can always return a permission error - you aren't allowed to update this resource, but has to support the method.

This should be stated once somewhere under URL conventions, and perhaps not as part of this particular proposal. Of course you need to URL encode characters if they are problematic.

Interpretation of existing DTS query parameters should be no different for updates than for anything else. Is this section needed?

The POST request body is underspecified. What are the contents?

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.

It has been suggested that I stick for the moment to proposing the new methods on existing endpoints, rather than proposing new endpoints. I can see the wisdom in that, so I'll probably separate out the possible new endpoints into a separate file.