Content Negotiation

[kinlane]

I want to introduce this thread to overlap with discussions around data filtering #22, schema filtering #21, response structure #6, and hypermedia #7.

Basics of content negotiation would be, do we offer application/csv, and text/html, as well as applicaiton/json (which is current default).

Advanced would be offering application/vnd.api+json, application/hal+json, or application/vnd.siren+json.

I'm thinking that offering a simple CSV and JSON response for default make sense for newbies. Content negotiation 101. Then we could start loading up some of the more detailed requests, and solving the "return everything" and "return exactly what I want" with introduction of hypermedia type, or even possibly something like application/vnd.hsds+api.

[NeilMcKLogic]

Have you also considered XML? I think you had mentioned it, or maybe @timgdavies , related to the HSDS spec. I'm not strongly advocating it as we prefer JSON now, just wanted to mention it.

[kinlane]

HSDA will support:

• CSV
• JSON
• XML

Out of the box. Every path except for /complete will support all three--it will only support JSON & XML.

All other projects will support JSON & XML.

My plan was to establish vendor media types, and eventually submit to IANA as projects mature, but my current stance is to hold off:

application/vnd.hsda.csv
application/vnd.hsda.json
application/vnd.hsda.xml

application/vnd.hsda.search.json
application/vnd.hsda.search.xml

application/vnd.hsda.bulk.json
application/vnd.hsda.bulk.xml

application/vnd.hsda.meta.json
application/vnd.hsda.meta.xml

application/vnd.hsda.meta.json
application/vnd.hsda.meta.xml

application/vnd.hsda.taxonomy.json
application/vnd.hsda.taxonomy.xml

application/vnd.hsda.orchestration.json
application/vnd.hsda.orchestration.xml

application/vnd.hsda.custom.json
application/vnd.hsda.custom.xml

application/vnd.hsda.aggregate.json
application/vnd.hsda.aggregate.xml

application/vnd.hsda.utility.json
application/vnd.hsda.utility.xml

[kinlane]

I will revisit the media type formats in the future, but opting to add a simple format property:

      - in: query
        name: format
        description: |-
          The data format of the response (csv, json, xml).
        schema:
          type: string 
``

Which will return one of the three formats with CSV being the default for all.