URLs for amendment service methods

[jar398]

There is currently one method, and according to the doc its URL looks like this: https://api.opentreeoflife.org/v3/amendment

It would be nicer if the name followed the pattern of the other APIs, where the URL is /v3/apiname/methodname. This makes the overall API more uniform, and also allows for the possibility of grouping together additional methods having to do with additions and other amendments, which seems likely.

The method for requesting the addition of new taxa might be called something like add_taxa, ergo /v3/amendment/add_taxa. If we ever generalize to other kinds of amendments we might want to have a new method.

Sorry I didn't catch this on PR review.

[jimallman]

There is currently one method, and according to the doc its URL looks like this: https://api.opentreeoflife.org/v3/amendment

I'm confused. Isn't this entirely typical of the "RESTful" APIs for studies, collections, etc.? Granted these are distinct from the other APIs that include method names, but there are many precedents for this pattern.

[jar398]

For a description of REST please see:

https://www.ics.uci.edu/~fielding/pubs/webarch_icse2000.pdf and Roy's dissertation.

In short, all URLs 'identify' some resource, GET when supported returns the state of the resource, PUT when supported replaces the state of the resource, and POST when supported does a partial update of the resource 'identified' by the URL.

If that's not what you're doing, you're not doing REST.

REST doesn't deal with RPC well, and it is designed for only a single kind of partial update (POST) for each resource. To do multiple kinds of partial updates you would need to specify the kind in the payload, or I suppose in a query string (although REST is vague on the use of the query string, so this might be cheating). For partial access, such as querying a database, the REST style is to use query strings.

Most web API designers nowadays ignore REST and use an RPC style instead. Instead of having a single resource ('the service') with a single URL, there is a single unnamed resource with one URL for every operation you can perform. That's what we've done (e.g. /v3/tree_of_life/mrca), with the anomalous exception of the /study/xxx and /collection/xxx URLs.

It hadn't occurred to me that you were thinking of /v3/amendment as 'identifying' a resource with POST as a partial update of that resource. The resource would have to the the entire amendments shard set. The RESTy way to create a resource is with PUT, not POST, and (in either case) with a 201 status and Location: header, so it may be a stretch to say that using POST to create a sub-resource (one that will have its own URL) is RESTy.

So the problem I have - after your reminder that it was intended to be RESTy rather than RCPy - is that the /v3/amendment URL is neither RESTy nor RPC-like.

If other ways of updating the amendment shards came along, such as a method that only updated the next-id pointer, how would they be expressed? By multiplexing the POST payload for /v3/amendment so that it could mean any kind of update?

How is study creation performed, by the way? I don't see that in our API documentation. (It would be nice if the API documentation described all the operations that are used by the GUI.) If /study works the same as /amendment I can see how you are following a precedent, but as I say it's not a very RESTy one - you would want to do PUT /study/new_study or something like that.

Personally I find the REST rhetoric sort of squishy and imperious; the real story behind REST has to do with caching. (There was also a theory of accessibility and portable bookmarking that never really caught on.)