New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Response Envelope #6

Open
kinlane opened this Issue Apr 13, 2017 · 5 comments

Comments

Projects
None yet
3 participants
@kinlane
Contributor

kinlane commented Apr 13, 2017

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

@switzersc

This comment has been minimized.

Show comment
Hide comment
@switzersc

switzersc May 21, 2017

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?

switzersc commented May 21, 2017

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?

@switzersc switzersc referenced this issue May 21, 2017

Open

Hypermedia #7

@greggish

This comment has been minimized.

Show comment
Hide comment
@greggish

greggish May 22, 2017

Member

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)...

Member

greggish commented May 22, 2017

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

This comment has been minimized.

Show comment
Hide comment
@kinlane

kinlane May 23, 2017

Contributor

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.

Contributor

kinlane commented May 23, 2017

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

This comment has been minimized.

Show comment
Hide comment
@kinlane

kinlane May 23, 2017

Contributor

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.

Contributor

kinlane commented May 23, 2017

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 comment has been minimized.

Show comment
Hide comment
@kinlane

kinlane Jul 9, 2017

Contributor

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.

Contributor

kinlane commented Jul 9, 2017

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.

@kinlane kinlane added hold and removed road map labels Aug 31, 2017

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment