precedence for format while content negotiation #5893
Description
Steps to reproduce
curl -uadmin:admin "http://localhost:8080/alfresco/service/hellouser.pl?format=json"
curl -uadmin:admin "http://localhost:8080/alfresco/service/hellouser.pl?format=xml"
Expected behavior
for first request format should be json
for second request format should be xml
Actual behavior
for both cases it is pl because of this
Relevant links how other frameworks and APIs do
please take them into account
Rails picks up the expected format from the query parameter format, or if not there from the URL path suffix, or it not there from the Accept header
Blog post: https://dzone.com/articles/rest-with-rails-part-2-serving
format query parameter is useful for rendering JSON output from a web browser without
special tools to modify the Accept header
IBM knowledge base: https://www.ibm.com/support/knowledgecenter/en/SS4GCC_6.1.1/com.ibm.urelease.doc/topics/rest_api_ref_conventions.html
However, if a request uses multiple methods simultaneously,
then the HTTP parameter (query string) takes precedence and the HTTP Accept
header will be ignored.
API: https://services.faa.gov/docs/formats/
Rule: Media type selection using a query parameter may be supported
To enable simple links and easy debugging, REST APIs may support media type
selection via a query parameter named
accept
with a value format that mirrors that of the
Accept
HTTP request header. For example:
GET /bookmarks/mikemassedotcom?accept=application/xml
This is a more precise and generic approach to media type identification that should
be preferred over the common alternative of appending a virtual file extension
like .xml to the URI’s path.
The virtual file extension approach binds the resource and
its representation together, implying that they are one and the same
REST API Design Rulebook
In our case this is format parameter
Should the media type change based on Accept headers or based on the URL?
To ensure browser exportability, it should be in the URL.
The most sensible option here would be to append a .json or .xml extension to
the endpoint URL
Best Practices for Designing a Pragmatic RESTful API. He is designer API and Founder of Enchant (Zendesk?)
The query string parameter solves the issue in the context of a developer
testing the API in a browser. Adding a query parameter is trivial, configuring
your browser to send a different set of Accept types is difficult if possible
at all.
curl -uadmin:admin "http://localhost:8080/alfresco/service/hellouser.json"
curl -uadmin:admin "http://localhost:8080/alfresco/service/hellouser?format=json"
curl -uadmin:admin -H "Accept: text/html" "http://localhost:8080/alfresco/service/hellouser"
Documentation how to select format and based on this SO question
The API returns JSON as the default content type. This can be overridden by using the format query string parameter with the value json, jsonp, or xml. The API also respects Accept header entries (EX: application/json, application/xml), with precedence given to the format parameter.