/search

[kinlane]

I will be moving the /search option beyond just returning locations, and give it a collection of organizations, locations, services, and contracts.

I will also give /search an /everything, so that we can have a simple, and expanded results.

[NeilMcKLogic]

Makes sense. I will be looking more closely at the Search documentation soon, it is a super important part of the spec.

[kinlane]

I'm recommending that /search be broken off from HSDA into it's own specification. I'd like to break /organizations, /locations, /services into their own microservices, but I feel its too far down the road for that. However /search can be severed at this point into a separate concern. Core resources will be all about managing those resources, where search will be all about search across everything. Similar to bulk loading, the separation of concerns will help move projects forward independently, as opposed to a monolith.

[rasmus-storjohann-PG]

@NeilMcKechnie: @greggish suggests that we compare notes on search APIs. I have a design up for our implementation here https://github.com/pg-irc/pathways-backend/issues/163, and I would be very interested in any comments or suggestions you might have on that, as well as anything you can share about how you are building search in your implementation.

[NeilMcKLogic]

Thanks @rasmus-storjohann-PG . I like where you are heading with your concepts. Here's my originally articulated list of gaps with HSDA's Search definition: #62

Regarding your ideas, I would like to take some time to think about them. I tend to prefer putting parameters in the request body for a little more structure and segmentation versus putting them in querystring parameters. It has the added benefit of being encrypted when using HTTPS, whereas URLs are not encrypted. But that is a comment on just one small part of your thorough writeup. Let me try to find some time to dive in more deeply, or perhaps we connect by voice with others interested in advancing the Search definition in HSDA to get some progress on it.

[rasmus-storjohann-PG]

Passing search arguments in the body so it's encrypted is an important point I had not considered. Can it still be GET then? Some say no. Using POST for search feels awkward. I had already seen your comments on #62 and incorporated quite a bit, it was very helpful.

[rasmus-storjohann-PG]

@NeilMcKechnie I just added this to our search story in the pathways repo, duplicating it here:

There are arguments for passing the search parameters in the request body. The main benefit is that they would be encrypted over HTTPS, which is admittedly a very significant advantage. There may also be some benefit to having more structure to the search parameters represented in JSON than in the URL. Since passing search parameters in the body of a GET request is inconsistent with standard GET semantics, we would need to use POST for searches. This means we can't use /services/ as the endpoint for search, since POST to /services/ creates a new service entity. It seems decidedly more intuitive to search using a GET request to /services/ than a POST request to something like /services/search/. The POST approach will also render caching ineffective.

So what is more important, an intuitive and cached API or confidentiality of the search parameters? I'm torn. I guess it's always possible to do both, in which case I'd suggest the POST end point be something like /services/secure_search/ to make the motivation of the two end points clear.

[NeilMcKLogic]

@rasmus-storjohann-PG you raise some very interesting points! I don't have a strong suggestion on which way(s) to go, but lots to consider.