resource type specified via an extension??

miqui

unread,

Nov 17, 2016, 3:31:25 PM11/17/16

to API Craft

hi

i am getting a request to create a new route to an API that generates different mime types depending on the extension, for example

GET /api/myresouce.json

or

GET /api/myresource.html

or

GET /api/myresource

(no extension then can just use some default)

i have have always suggested the consumer specify the proper header.... any thoughts? thanks!

rgds,

Miguel

Jørn Wildt

unread,

Nov 18, 2016, 4:05:53 AM11/18/16

to api-...@googlegroups.com

Extensions like .html and .json etc. can be useful for debugging in the browser as the user (client developer) can get different media types returned by playing with the URLs only.

With a hypermedia API it becomes "odd" (in lack of better terms) to have different URLs for the same resource - you would need one link relation type for each content type representation of the linked resource or use a format that allows the media type to be included in the link.

Example: assume the link relation "up" refers to some parent resource P. This resource P can be represented in either JSON or XML. Without media types in links you would need this:

... which in turn means you cannot use a single link relation like "up".

If the link definition include media type (and ATOM for instance does that) you could write:

... and now you can have your single link relation and let the client decide which content type it wants.

If you depend on content negotiation instead you could reduced all this to:

... which seems more elegant, but does not inform the client of the possible content type variantions, so you would still need two links to inform the client completely about available representations:

If you are not using hypermedia then none of this matters and content negotiation vs. URL extensions is an irrelevant discussion - both solutions work well (but adding .json or .xml does make it easier to debug as mentioned earlier).

You can although start a more philosophical discussion about the same resource having different URLs (.xml and .json) when URL = identifier ... but in the end a resource is allowed to have multiple URLs although one of them should be considered "canonical".

/Jørn

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+unsubscribe@googlegroups.com.
Visit this group at https://groups.google.com/group/api-craft.
For more options, visit https://groups.google.com/d/optout.

miqui

unread,

Nov 23, 2016, 3:48:34 PM11/23/16

to API Craft

..cool.. thanks for your feedback Jorn.., yeah i am not using hypermedia, so for now i will stick to with the extension approach