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

Search URLs vs params #22

Closed switzersc closed 9 months ago

switzersc commented 7 years ago

IMO, search URLs are always tough. Right now, the search URL in the Ohana API I've seen is a bit confusing because I don’t know what kind of resource it will return. Will it return locations, or organizations, or any type of resource that fits the keyword? Also, a search isn’t a resource exactly, so having it in the URL doesn’t feel very RESTy (although arguably this doesn’t matter much). My convention would be to just add those search params to the /locations endpoint, unless the search action is meant to return multiple resources, in which case I think a dedicated search URL is appropriate.

On this note, is it necessary to have an endpoint for /locations/nearby when that URL accepts params anyway? Thoughts on just allowing those possible params on the /locations endpoint instead of dedicating a separate endpoint for it?

switzersc commented 7 years ago

This seems related to this issue: https://github.com/openreferral/api-specification/issues/11

kinlane commented 7 years ago

I agree with you that I prefer search to be baked into any endpoint where relevant, allowing for search, nearby, etc. in the context of the endpoint. I think this helps folks discover at the resource level, and this hopefully can be used to influence it's designed in future iterations, adding more meaningful paths and queries that support and augment its purpose.

with that said, I can envision some sort of master search endpoint for folks who don't understand the nuance of specific endpoints (ie. locations, orgs.) I agree the Ohana search confuses the hell out of me. I'd like to see a comprehensive search design with meaningful collections (organizations, locations, services, etc.) as part of response -- we will see.

kinlane commented 7 years ago

I am also considering the implications of taxonomy at the endpoint level. meaning can I get at organizations, location, and services by taxonomy /[organization_id]/[taxonomy]/ or /[location_id]/[taxonomy]/. It might be a v1.3 suggestion.

switzersc commented 7 years ago

I am also considering the implications of taxonomy at the endpoint level

This is very compelling! It seems that a lot of clients and users think about and search for orgs, services, locations, in taxonomy terms already (take a look at almost any united way service directory), so anticipating that use case with the API I think would be valuable.

switzersc commented 7 years ago

I also wonder at the intersection of taxonomy use cases and search use cases. In some directories, you see search as merely an auto-fill of taxonomy terms and that's all you can search by. That feels like too limiting of an approach for a robust search API, but I also wonder what lessons we can learn from taxonomy ideas/semantics/uses when implementing a great search endpoint and response.

kinlane commented 7 years ago

I am thinking a lot about the intersection of upfront design over after the fact querying -- even as far as GraphQL. When does design become limiting? When does it empower a consumer group who may not understand what is possible? I'm going to simmer on taxonomy all by itself here for a while.

kinlane commented 7 years ago

Also related. Maybe will merge with this - https://github.com/openreferral/api-specification/issues/11

boxfoot commented 7 years ago

In general, I think we should go for supporting query parameters on the various collection objects -- I think that's a sound approach and accomplishes a lot of what users need to do.

At the same time, I'm not sure that's sufficient for the general use case of "searching for resources for a specific person" -- supporting a general search where you pass in criteria that likely cut across the whole data structure (eligibility rules, taxonomy, geography, etc.) and need to get back enough information to build a meaningful UX for the end-user (basically, a list of ServiceAtLocations with a ton of related information). Is the "query parameter" approach sufficient for this? Which resource endpoint would folks be querying to accomplish this?

kinlane commented 7 years ago

hey @boxfoot - finally getting to your emails and this. I think you hit the slipperyness of this. Honestly, my perspective is let's do both. allow for getting at what they need at endpoints, and make search a first class citizen with a robust set of results. Also allowing for simple, and complex searches at both levels. I will open up to more discussion at gathering.

NeilMcKLogic commented 6 years ago

I agree we need a "general" search for all the reasons stated above. Also the searcher may not be sure in which object type they may find the search term. "Saint Mary's Church" could be the name of an Organization, Location and/or Service. Heck it could also just be part of an Address, or the name of a Phone Number. Imagine how much fun it would be (not!) poking at every object type individually with API calls and trying to blend the results back together yourself. Yuck.

rasmus-storjohann-PG commented 6 years ago

This is what we're currently planning to do for a search functionality at the services API end point https://github.com/pg-irc/pathways-backend/issues/163 . We likely will also have a /search end point which I imagine will be broadly similar. I'd be interested to hear any comments you might have.

kinlane commented 6 years ago

Good timing @rasmus-storjohann-PG we are addressing this right now. Will provide feedback.

mrshll1001 commented 9 months 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 have dropped the /search endpoint in favour of a RESTful approach, with a search parameter included on all endpoints.