search

openreferral / api-specification

This is the working repository for Open Referral's Human Services Data API protocols.
https://openreferral.readthedocs.io/en/latest/hsda/
Other
29 stars 13 forks source link

Content Negotiation #39

Closed kinlane closed 3 years ago

kinlane commented 7 years ago

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 commented 6 years ago

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 commented 6 years ago

HSDA will support:

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 commented 3 years ago

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.