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

Schema Definition for Core Paths GET and POST #29

Closed kinlane closed 1 year ago

kinlane commented 7 years ago

Migrating from a Slack channel discussion around the number of available APIs I'd like to open a thread specifically about what the core paths GET and POST structures should look like

When you GET, what can be expected? Simple or complete nested (ie. phone, contacts,)? When you POST or PUT, what can be expected? Simple or complete nested (ie. phone, contacts,)?

This overlaps with other conversation regarding schema filtering, or how you tell the API which schema the user would like returned - https://github.com/openreferral/api-specification/issues/21

This also overlaps with conversation regarding /search/ and it's relationship to /organization/, /locations/, and /services. Where the results should be - https://github.com/openreferral/api-specification/issues/22

My recommendation is that all four core paths have a simple and complete schema representations that the consumer can choose from when GET, or POST and PUT. You choose whether you want to get a full listing or summary listing -- we can also craft other views in the future.

This conversation is probably one of the most pressing regarding the v1.1 design discussion.

switzersc commented 7 years ago

My recommendation is that all four core paths have a simple and complete schema representations that the consumer can choose from when GET, or POST and PUT. You choose whether you want to get a full listing or summary listing -- we can also craft other views in the future.

+1 on these three endpoints having a full (incl nested resources) representation and a summary representation (and the summary should perhaps include links so the client knows where to access any nested resources that weren't provided in full).

I think for a foundational API it might be preferable to opt out of a search endpoint for now and instead allow these three core endpoints to be queryable by taxonomy id/name and geographic area.

kinlane commented 7 years ago

Definitely the type of implementational thinking I'm trying to get at. I can see the API used for a pure management solution, not as heavily on search -- known ids, with updates.

Or maybe even for voice, bot, and other conversational interfaces. Asking number. Asking address. Even Update address...IDK.

Trying to think and learn about all the heavy foundational API search uses, as well as out of the box implementations.

NeilMcKLogic commented 7 years ago

I agree and I know this was also discussed on a subsequent phone call. In addition to "summary/simple" and "full/complete" I think we discussed a flexible in-between option where the request can express exactly what child record types it wants returned in the object hierarchy. I like that option too and I know Kate (where's her @name in autosuggest?) echoed support but the first two are probably good for now.

greggish commented 7 years ago

cc @klambacher

kinlane commented 7 years ago

Will consider an approach for schema filtering in future versions, but for now it is just simple or #45 /complete -- Once we get more feedback on use cases, and examples of usage, we'll run with implementation.

Currently I have performance, and complexity concerns. As dynamic schemas will not be cached. Keeping around, but lowering in priority.

mrshll1001 commented 1 year ago

We will be archiving this repository soon. We're closing this issue because we believe it has been conclusively addressed as part of work on the main HSDS standard.

In this case, we've achieved this effect in HSDS 3.0 as the API specification is linked to the HSDS schemas. There are parameters for requesting fully nested models or not.