Stop pretending to be a REST API, change all the URL endpoints

[adamnovak]

We should name the HTTP endpoints for methods after the method names themselves, instead of nesting them in a REST-like hierarchy. Our API consists of POSTing lots of request objects, which isn't very RESTful at all, and the mapping between method names and URL endpoints isn't machine-readable as it stands.

[macieksmuga]

I second this: pagination can easily be expressed as a couple of parameters to a GET method (pagesize, pagetoken), and most of the other search parameters for most of the methods should be pretty simple to serialize as key-value pairs as well (although I expect that exceptions will need to be made for genuinely complex search parameters).

For context, this became an issue when designing a method for serving out (reference) subgraphs based on specified constraints (seed position, radius), that didn't fit the standard "search on existing objects" semantics.

[jeromekelleher]

Interesting; have you a concrete proposal here?

We'd still have to keep the POST methods around for a long time for compatibility reasons, but they could operate in parallel for as long as necessary.

[calbach]

IIRC the reasoning for POST was to workaround potential HTTP constraints, i.e. URL length. These concerns were probably unfounded though. I would support changing these endpoints to GET and also having parent ID nesting in the URL.

Though I can't tell whether the original issue is proposing to abandon REST semantics entirely.

[macieksmuga]

@calbach good point, and having discussed this further with @adamnovak I think you're right: His proposal was exactly as you state, namely abandon the appearance of REST semantics.

So while I still think that a few of the methods that don't require complex parameters could/should be implemented as GET methods (in parallel with their POST siblings), this was a distraction from Adam's main argument.

[adamnovak]

The solution I was thinking of was sort of the opposite: leaving the mix of POST and GET methods that we have (i.e. using POST for anything that we want to take a nontrivial type as input, so we don't have to try to define an Avro-object-to-query-string serialization) and changing the URL endpoints to not look like REST (we could just use the method names). So instead of /sequences/{id} as a GET we might have /getSequences?id=id (also a GET) and instead of /variants/search we would have /searchVariants (as a POST).

[delagoya]

-1

I like the semantics of POST for create or update and GET for read operations.

[jeromekelleher]

We don't really have that right now though @delagoya --- we have POST for some types of read operations and GET for others.

[Relequestual]

As an implementer and co-developer of the Matchmaker Exchange API (a ga4gh supported project for those who haven't heard about it)... we really wanted to keep the API RESTful, but because of the complexity of queires, it was basically not possible.

When you want to query with a patient (and all there genotypic and phenotypic data), then you have to post that data.

That being said, there's no reason to not try to keep the remaining REST principles, and be RESTlike rather than not.