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

Secure Search HSDA #86

Open kinlane opened 5 years ago

kinlane commented 5 years ago

Adding a secure search to HSDA, allowing POST searches using definition schema as BODY.

Issue: #46 : https://github.com/openreferral/api-specification/issues/46#issuecomment-427612848 OpenAPI: https://gist.github.com/kinlane/e27557e87a5007b6e0014d9437b2bcc9

boxfoot commented 5 years ago

Glad to see this supported. I'm curious why we need a separate URI for this, though. Couldn't we define that /search can respond to either GET or POST, and that GET looks for parameters in the query string while POST parses the body? It seems like it would be almost the same definition, just combined under one endpoint...

What's the benefit of describing this as a unique endpoint?

NeilMcKLogic commented 5 years ago

My understanding is that GET should be used for all idempotent requests, and any search is idempotent.

http://restcookbook.com/HTTP%20Methods/idempotency/

A GET can have content either in the URL or in the BODY of the request.

POST doesn't mean "there's content in the BODY" - it means "This request is going to issue a data change to the resource I'm pointing to." At least, that is my understanding.

boxfoot commented 5 years ago

@NeilMcKechnie yes, as for as common REST practices and semantics are concerned, then GET means "ask for information from the server w/o changing it" and POST/PUT/PATCH means "add or update new information to the server", but I've seen many variations and implementations.

As far as the spec is concerned, GET requests should not include a message body. While some servers support this, not all do, and (as per the discussion here), even if a message body is sent for a GET request, it should be ignored. So whatever we do, we're working around the edges of the "spec" and in the land of "how folks make RESTful interfaces work for real-life use-cases"

Using POST to initiate searches with secure params make sense to me, and I've seen many APIs do this. I've heard people align this to RESTful principles by imagining a "search" object that represents a specific search. You create a new search request by POSTing to that collection, and then you could even GET back that object to learn metadata about the search -- who requested it, when, the parameters used, the information found. In fact, APIs that support async search often use this paradigm to let you queue up a search request and then pull down the results later when they're available.

NeilMcKLogic commented 5 years ago

Alrighty, thanks for clarifying @boxfoot !

kinlane commented 5 years ago

I do not have any reason to challenge it being available as POST on existing path, over adding a new path. @boxfoot recommendations seems logical.