#95 Make /results end-point work as a collection
Closed: Invalid 6 years ago Opened 6 years ago by csomh.

Getting results

Current behavior:

  • GET /results returns the list of results
  • GET /results/ returns 404 (Not found)

Expected behavior:

As results is a collection, and the trailing / indicates a collection (as in Unix a trailing / indicates a directory), GET /results should do a permanent redirect to /results/ and return the list of results. This would be a similar behavior what waiverdb implements with the /waivers end-point.

Posting results

Current behavior:

  • POST /results creates a new result
  • POST /results/ returns 404 (Not found)

Expected behavior:

The intent of this operation is to create a new item in the results collection, so imho the expected way this should be done is to use /results/ (with a trailing '/').

If /results redirects to /results/ (see above), POST /results will return the list of returns, as clients are expected to switch from POST to GET while redirecting (curl does this; POST is not idempotent, so this is the safest approach). If the client does not follow redirection, 301 will be returned and a URL with a trailing '/' indicated.

API docs should document /results/ as an end-point.

Similar changes might be required for other collection-type end-points.

For explanation see Relationship between URL and HTTP methods, for example.

All the above is in sync how similar end-points are handled in waiverdb.


Hi,

the trailing slash is actually quite a topic in the REST-api design, and you sure can find some people advocating trailing slashes:
* https://cdivilly.wordpress.com/2014/03/11/why-trailing-slashes-on-uris-are-important/
* https://www.packtpub.com/application-development/building-restful-python-web-services

And quite a lot, saying that trailing slashes are to be omitted (or even an antipattern)
* https://docs.microsoft.com/en-us/azure/architecture/best-practices/api-design
* https://blog.philipphauer.de/restful-api-design-best-practices/
* https://restfulapi.net/resource-naming/
* https://dzone.com/articles/7-rules-for-rest-api-uri-design-1
* https://hackernoon.com/restful-api-designing-guidelines-the-best-practices-60e1d954e7c9
* https://www.safaribooksonline.com/library/view/rest-api-design/9781449317904/

The other thing is, that there is an actual difference between .../api/v2/results, and .../api/v2/results/, the first has path elements ('api', 'v2', 'results'), the second one ('api', 'v2', 'results', ''). Compare this to .../api/v2/results/1 and the respective ('api', 'v2', 'results', '1') path elements. It IMO is quite obvious, that the .../api/v2/results/ requests a resource identified by an empty string from the results collection (see RFC 3986 for reference).

Also, while I understand where the Linux-fs-directory-simile comes from, I do not really believe it is an appropriate one. Can linux directories do .../results?item=foobar? This is also one more reason (for me) against defaulting to trailing slashes - if nothing else, I really, really do not like .../results/?item=foobar.

tl;dr; AFAIK there is no definitive answer, and these are mostly just suggestions/best practices. One could make a case for .../collection vs .../collecion/ to be that the first one gives you metadata/information about the collection itself, whilst the latter returns the list of entries, but then we probably could go even deeper, and discuss what "the list" should be, and whether it's not "more right" to just return a list of URIs, which can be fetched, instead of the (paginaged) raw data. Also, ResultsDB does not really have any meaningful 'metadata' to share, so it is a moot case anyway... Turns out, API design is hard, and one should generally mostly strive for consistency.


This said, I understand that you might have some technical reasons for requiring the trailing slash in the URLs, and I'd be interested in those.

I also believe, that the resutlsdb api could be "nice about it", and provide a HTTP 303 response for the URLs with the trailing slash instead of HTTP 404, even though this can cause issues of its own (especially caching related).

Depending on the technical issues/reasons you have, would that be OK for you?

Any input/thoughts on the topic?

Hey, sorry, I'll give some input towards the end of this week. Thanks!

Metadata Update from @jskladan:
- Issue close_status updated to: Invalid

6 years ago

Log in to comment on this ticket.

Metadata