RESTful API?

[ifokkema]

Hi all; I see some references here and there that mention that the GA4GH Search API is RESTful, but according to the definition of REST APIs, I'm afraid it isn't.

• In case you don't mean to have a REST(ful) API, such statements can be removed (e.g. from here and here.
• In case your intention is to have a REST(ful) API, then some changes can be made.
  • The GA4GH Table Discovery API can become RESTful in my view by implementing HATEOAS (related to #61) and specifying valid HTTP response codes.
  • The GA4GH Search API, well, that's more difficult. POSTing a search query is just not possible according to REST standards.

I understand the immense advantage of the currently light specifications of the GA4GH Table Discovery API, so keeping it light and not specifying more requirements would be a completely valid choice, but I think then not calling it RESTful would be better to not confuse users.

[cmungall]

Unfortunately I think the use of "RESTful" to describe any web API is commonplace, regardless of whether it follow's Fielding's definition or not. I do think it would be useful to clarify the use of the term, whether the API is intended as "RPC-style" (i.e OpenAPI) vis "true" REST/HATEOAS.

I do note that the API has some HATEOAS-like elements:

https://github.com/ga4gh-discovery/ga4gh-search/blob/develop/SEARCHSPEC.md#pagination-and-long-running-queries

I am by no means a HATEOAS adherent - some cases you want a more tightly coupled RPC style API, sometimes hypermedia makes sense. But it does seem that if there is a use case for HATEOAS it is the open-ended discovery oriented nature of the GA4GH search API.

[jfuerth]

I agree, the current spec does not meet all of the constraints of REST. As @cmungall says, it's a classic case of "JSON over HTTP" getting called REST when it isn't.

In very early drafts, table info and table data were links (relative or absolute) rather than IDs that the client needs to know what to do with. We were asked to change this to the OpenAPI style of specifying fixed URL patterns early on. As far as I know, providing an OpenAPI spec is one of the requirements we need to meet as a GA4GH API, and an OpenAPI spec for a true REST application would have to be empty. :)

Looking at the mentions of "REST" that @ifokkema refers to, I'd support removing them.

Pure REST (including HATEOAS) works superbly for human-driven user agents like web browsers, and even for generic headless clients like web crawlers. However I agree with @cmungall that it's not the best approach for all problems. I've encountered exactly one fully HATEOAS API in the wild (for VMWare VCloud Air) and it was really painful to write a headless client for it that carried out specific operations!

[ifokkema]

Thanks for your replies!

Unfortunately I think the use of "RESTful" to describe any web API is commonplace, regardless of whether it follow's Fielding's definition or not.

Totally agree, I myself have been calling my APIs RESTful for years when I ran into Fielding's rants on the subject, simply not knowing the full depth of the definition before.

I do note that the API has some HATEOAS-like elements:

https://github.com/ga4gh-discovery/ga4gh-search/blob/develop/SEARCHSPEC.md#pagination-and-long-running-queries

I noticed, indeed! Very useful! It is using different terms compared to the standard links element with rel and href attributes, but to be honest I'm not even sure if those exact terms are a requirement or simply a suggested standard.

In very early drafts, table info and table data were links (relative or absolute) rather than IDs that the client needs to know what to do with. We were asked to change this to the OpenAPI style of specifying fixed URL patterns early on. As far as I know, providing an OpenAPI spec is one of the requirements we need to meet as a GA4GH API, and an OpenAPI spec for a true REST application would have to be empty. :)

Haha OK, that's a good point :laughing:

Pure REST (including HATEOAS) works superbly for human-driven user agents like web browsers, and even for generic headless clients like web crawlers. However I agree with @cmungall that it's not the best approach for all problems. I've encountered exactly one fully HATEOAS API in the wild (for VMWare VCloud Air) and it was really painful to write a headless client for it that carried out specific operations!

I can imagine! It could be that I've spent too much time reading Fielding's rants on REST-like APIs calling themselves RESTful. I do still want to adapt all mentions of "REST API" from my own documentation though, as I don't plan to adapt them to make them fully RESTful, either, but do want to respect the original definition of the term.