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

Path Filtering #38

Closed kinlane closed 3 years ago

kinlane commented 7 years ago

I'm opening up a 3rd dimension to the whole filtering conversation. It is relevatng data filtering (#22) and schema filtering (#21), but is at a higher level.

It answers other concerns about the overall API design surface area being too large, too many paths. Path filtering in the API documentation would all for a default set of paths (ie. orgs, locations, services, search), then mid, and advanced tiers.

This would reduce cognitive load for developers when first getting going, but allow for knowledgeable users to get at a wealth of more advanced or precise search endpoints.

I am suggesting this also to handle future addition of API paths, such as utility ones like schema validators, or possible universal ID, taxonomy, messaging, etc. Additional projects, relevant to, and sometimes part of core spec, but off in separate namespace.

NeilMcKLogic commented 6 years ago

Thanks @kinlane but I'm not sure what exactly you are asking for here, can you clarify please?

kinlane commented 6 years ago

Some way of tagging paths. Going to do this in APIs.json index for site.

So when you land on documentation, you get the core resources

/organizations /locations /services

Tag for secondary resources -- everything else.

Allow for other grouping in future.

The goal is to prevent overload for new users, but give advanced uses what they need.

The separation of each project into separate microservices is part of this, how I moved /search into it's own. But within each microservice we can group /paths.

Will have example shortly.