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

Search URLs vs params #22

Open
switzersc opened this Issue May 21, 2017 · 12 comments

Comments

Projects
None yet
5 participants
@switzersc

switzersc commented May 21, 2017

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

This comment has been minimized.

Show comment
Hide comment
@switzersc

switzersc May 21, 2017

This seems related to this issue: #11

switzersc commented May 21, 2017

This seems related to this issue: #11

@kinlane

This comment has been minimized.

Show comment
Hide comment
@kinlane

kinlane May 23, 2017

Contributor

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.

Contributor

kinlane commented May 23, 2017

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

This comment has been minimized.

Show comment
Hide comment
@kinlane

kinlane May 23, 2017

Contributor

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.

Contributor

kinlane commented May 23, 2017

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

This comment has been minimized.

Show comment
Hide comment
@switzersc

switzersc May 23, 2017

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 May 23, 2017

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

This comment has been minimized.

Show comment
Hide comment
@switzersc

switzersc May 23, 2017

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.

switzersc commented May 23, 2017

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

This comment has been minimized.

Show comment
Hide comment
@kinlane

kinlane May 24, 2017

Contributor

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.

Contributor

kinlane commented May 24, 2017

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

This comment has been minimized.

Show comment
Hide comment
@kinlane

kinlane May 24, 2017

Contributor

Also related. Maybe will merge with this - #11

Contributor

kinlane commented May 24, 2017

Also related. Maybe will merge with this - #11

@boxfoot

This comment has been minimized.

Show comment
Hide comment
@boxfoot

boxfoot Jun 26, 2017

Contributor

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?

Contributor

boxfoot commented Jun 26, 2017

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

This comment has been minimized.

Show comment
Hide comment
@kinlane

kinlane Jul 9, 2017

Contributor

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.

Contributor

kinlane commented Jul 9, 2017

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.

This was referenced Jul 9, 2017

@NeilMcKechnie

This comment has been minimized.

Show comment
Hide comment
@NeilMcKechnie

NeilMcKechnie Aug 10, 2017

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.

NeilMcKechnie commented Aug 10, 2017

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

This comment has been minimized.

Show comment
Hide comment
@rasmus-storjohann-PG

rasmus-storjohann-PG Jan 13, 2018

This is what we're currently planning to do for a search functionality at the services API end point pg-irc/pathways-backend#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.

rasmus-storjohann-PG commented Jan 13, 2018

This is what we're currently planning to do for a search functionality at the services API end point pg-irc/pathways-backend#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

This comment has been minimized.

Show comment
Hide comment
@kinlane

kinlane Jan 13, 2018

Contributor

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

Contributor

kinlane commented Jan 13, 2018

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

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