api-specification
api-specification copied to clipboard
openreferral
Secure Search HSDA
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
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?
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.
@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.
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.