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

HAL representation #59

Closed kinlane closed 6 years ago

kinlane commented 6 years ago

I would like to propose a separate HAL representation be developed, allowing for HSDA access to be done via relationships between the data.

This is the second first proposal to use media types for breaking projects into smaller chunks so they do not affect other types of users -- meeting the needs of systems users, without impact say web, spreadsheet, SPA, or conversational interface users.

Implementors can choose to follow core schema, or be HAL compliant, choosing to go a more hypermedia path for all clients.

While I am putting this under v1.2 -- the hypermedia API would branch and take on its own versioning, as separate branch.

NeilMcKLogic commented 6 years ago

@kinlane definition of HAL please?

kinlane commented 6 years ago

HAL is a hypermedia media type (application/hal+json) that provides a consistent wrapper for API responses, that provides a number of affordances y'all have been asking for in a consistent way that many developers will automatically understand. Things like sorting, pagination, and links to other actions, connecting relationships, etc. It helps automate this as a number of APIs use HAL, making clients reusable. (http://stateless.co/hal_specification.html)

kinlane commented 6 years ago

I am also considering JSON API, which is in the same camp - http://jsonapi.org/

However, after last spec, I'm thinking I should probably keep thing simpler, and focused around what the community knows.