Consider simplified Search endpoint (vs. standard FHIR)

[jmandel]

Reported by @carloseberhardt via http://wiki.siframework.org/BlueButtonPlus+Pull+API+Documentation+Consensus

1) Default format should be consistent. app registration, oauth all appear to be json, so json should be default here.

2) Would prefer to see endpoints like:

search: /bb/me/record?q={searchstring}&additionalFilters
document: /bb/me/record/{recordid}
all docs: /bb/me/records (return default 10 items, most recent first, w/ pagination support) 

Additionally, /record appears to be redundant here. Unless there are plans to provide more information under /me (profile, etc), then you could just eliminate records, leaving /bb/me?q={}, /bb/me/{id}, etc.

3) unclear of the value of searching for a record in a specific format. Why not eliminate?

4) query param naming should be consistent and javascript friendly. period-before and period-after should be before, after. 'to' and 'from' are more common.

5) comma-separating types can be easier for analytics for the provider, and cleaner for devs rather than multiple queryparams.

6) would prefer simple name:value json for responses.

rather than

"created" : {
"value" : "2005-12-24T09:35:00+11:00"
},
"indexed" : {
"value" : "2005-12-24T09:43:41+11:00"
},
"status" : {
"value" : "current"
},
"format" : {
"value" : "application/hl7-ccda+xml"

do this

"created" : "2005-12-24T09:35:00+11:00",
"indexed" : "2005-12-24T09:43:41+11:00",
"status" : "current",
"format" : "application/hl7-ccda+xml"

Much easier on devs!

[jmandel]

This issue really boils down to "We're trying to use FHIR's API to expose FHIR DocumentReference resources" -- which means we're simply taking what FHIR specifies for most of these points.

It's important to recognize this is a moving target, and FHIR has made several recent changes + proposals to the DocumentReference representation.

More details below...

json should be default here.

For background: FHIR considers the XML formats normative, and JSON informative; sample FHIR servers provide XML responses as a default (which is why we're preliminarily doing likewise)

Would prefer to see endpoints like: search: /bb/me/record?q={searchstring}&additionalFilters document: /bb/me/record/{recordid} all docs: /bb/me/records (return default 10 items, most recent first, w/ pagination support) Additionally, /record appears to be redundant here query param naming should be consistent and javascript friendly

The endpoints URIs themselves are established by each provider (apps learn about them via discovery) -- so whether "record" appears, etc. can differ with implementations. As for the formatting of query parameters: we're tracking FHIR's DocumentReference search parameters here -- and FHIR's definitions are still a work in progress. I agree with the suggestions here and would very strongly encourage discussion with the FHIR group to advocate for friendlier conventions! (But I'm also recommending we follow FHIR's spec here, whatever they choose.)

unclear of the value of searching for a record in a specific format.

Agree there's no strong use case at present (but mimeType is a required parameter, and FHIR defines how to query on it.)

comma-separating types can be easier for analytics

Agree strongly -- again we're following FHIR's spec here. Please do raise this issue in discussion with the FHIR group.

would prefer simple name:value json

Me too. Again, this is FHIR's JSON rendering. (The complexity comes from the fact that individual strings can have additional metadata associated with them -- unique identifiers, for example, can be attached to even primitive data values.) Again, I'd strongly encourage discussion with the FHIR group about cleaner JSON representations for FHIR resources.

[jmandel]

Q. @jricher Does hData support search?

[jmandel]

Closing for now on understanding that search is unavailable. Feel free to re-open if needed.