Should I use the accept http header or a more explicit rest api resource to define the data format requested by the client?

Question

Let's say I have an API like: /api/v1//modify?txtUri={a-text-file-uri-goes-here} which filters and modify a given text file located at a given URI and returns in the payload response the filtered text file based on some internal business rules.

At first I wanted to return only JSON but I would like to allow different return formats.

Is it better (i.e. the most standard way) to:

• use different resources:

  • /api/v1/modify?txtUri={a-text-file-uri-goes-here}/json
  • /api/v1/modify?txtUri={a-text-file-uri-goes-here}/xml returns
  • /api/v1/modify?txtUri={a-text-file-uri-goes-here} default fallback, returns json

• add another optional query string parameter format:

  • /api/v1/modify?txtUri={a-text-file-uri-goes-here}?format=json return json format
  • /api/v1/modify?txtUri={a-text-file-uri-goes-here}?format=xml returns xml format
  • /api/v1/modify?txtUri={a-text-file-uri-goes-here}default fallback, returns returns json

• set the Accept http header: https://developer.mozilla.org/fr/docs/Web/HTTP/Headers/Accept with the return format we want to get, if not set then we return a 406 http code.

Answer 1

Use the Accept header as a REST API is HTTP and it's the way HTTP works. It's also what the users of your API would expect.

Definitely don't use the QueryString if you don't want to use the accept header - you could use an extension at a a push e.g. /api/v1/modify.json?txtUri={a-text-file-uri-goes-here} Twitter do this, but my preference would be Accept header.