Response Envelope

[kinlane]

THis would be the time to adopt JSON API, HAL, or other evolutionary approach to responses - let's discuss.

[switzersc]

Yes! I'm a major fan of collection+JSON for collection data sets that are primarily read (rather than read+write or write-only) and need to support API querying functionality. Do we have the API user stories solidified, in terms of who we think will be the primary developer consumers of these APIs and what their consumption use cases look like? I think that'll help us determine the best format type.

Questions I have around this:

• How much tooling/support do we think will be needed by dev/IT teams consuming Open Referral APIs? What has a lot of tooling and support? Does this matter much anyway if the Open Referral project aims to provide SDKs? (IMO hypermedia APIs are easier to build clients and tools for anyway, but some format types have more of a community around them than others, and we may want to consider that)
• Will API consumers ever be writing back to the APIs? Is the typical use case the consumers will read Open Referral APIs and update their own databases, and then explore their own APIs for others to read? Or do we think API consumers will choose to write back to those APIs?
• Would we want to support multiple format types, e.g. HAL and JSON API? What about JSON and XML? HAL is pretty strong in this regard because it's design to work as JSON and XML. Also, not that I'm advocating for this, but has anyone talked about the need to represent this data in some sort of EDI format?

[greggish]

These look like great questions. I can speak a bit to the user types, although they are still in early stages.

So far we've identified four types of use:

• Software developer who needs to redeliver data through their tool (primarily read, at least in this phase, although we could easily anticipate use cases in which third party software should be able to write to an API)
• Researcher / analyst who needs to pull bulk data for analysis (primarily read)
• Database administrator who wants editing data across distributed systems (read + write)
• Organization that wants to update its own service information (read + write)

I think there's still some uncertainty as to whether that fourth bullet is indeed its own use case (rather than say a subtype of the third user type)...

[kinlane]

Great thoughts @switzersc -- I definitely need to do more thinking about the client implementations, weighing that in relation to @greggish user / implementation list he is cultivating. I'm pretty confident I'm going to go suggest collection+JSON for a v2.0 rework, but will weigh maintaining to versions side by side -- keeping the basic, light weight simple JSON, and then more advanced users / clients can negotiate the collection+JSON edition.

[kinlane]

I think your content negotiation question is critical @switzersc -- I want to support HTML, CSV, XML, and JSON versions coming out of gate. I could see continued support of many media types, even some very legacy once.

[kinlane]

This is really overlapping with hypermeda #7 as @switzersc points out, but also with schma filter #21. To make things worse, I think I'm going to introduce another thread specifically on content-type negotation, aside from hypermedia conversations, and augmenting schema filtering conversation, but with alternate path than using prefer header. I'm looking to head of complexity debates with content-negotiation.