I've notice most if not all fhir resource types have a property 'identifier', which is of type identifier.
I have set this on my resources to have a system, and a value, I'm wondering how I now search for resources with a given identifier?
Ideally I would like to search for all resources of all types with a given identifier, but I don't think there's an easy way to specify a url which searches across all types, so for example, I have a patient resource with an identifier of system:www.mydomain.com value:1, and I want to find them. My server is a hapi dstu2 instance.
You could perform a search for identifier with the standard search syntax:
GET [base]/Patient?identifier=12345
or, if you also want to specify the system:
GET [base]/Patient?identifier=www.mydomain.com|12345
and do that for each of the resource types you want to perform the search on.
As of STU3 you can also search across multiple types that share a common search parameter. Identifier is one of them. You still have to specify the types you want to search on, and can do that with this syntax - if the server supports it:
GET [base]?_type=Patient,Organization&identifier=12345
and you can also search on identifiers with a specific system without the value:
GET [base]/Patient?identifier=www.mydomain.com|
Please take a look at the search page of the spec for more information and examples.
Related
Consider a need to create a GET endpoint for fetching Member details using either of 4 options (It's common in legacy application with RPC calls)
Get member by ID
Get member by SSN
Get member by a combination of Phone and LastName (both must be passed)
What's a recommended strategy to live the REST spirit and yet provide this flexibility?
Some options I could think of are:
Parameters Based
/user/{ID}
/user?ssn=?
/user?phone=?&lname=?
Separate Endpoints
/user/{ID}
/user/SSN/{SSNID}
/user/{lname}/{phone}
RPC for custom
/user/{ID}
/user/findBySSN/
/user/findbycontact/
REST doesn't care what spelling you use for your identifiers.
For example, think about how you would do this on the web. You would provide forms, one for each set of search criteria. The consumer would choose which form to use, and submit the form, without ever knowing what the URI is.
In the case of HTML forms, there are specific processing rules for describing how the form information will be copied into the URI. The form takes on the aspect of a URI Template.
A URI Template provides both a structural description of a URI space and, when variable values are provided, machine-readable instructions on how to construct a URI corresponding to those values.
But there aren't any rules saying that restrict the server from providing a URI template that directs the client to copy the variable values into path segments rather than into the query string.
In other words, in REST, the server retains control of its own URI space.
You might sometimes prefer to use path segments because of their hierarchical nature, which may be convenient if you want the client to use relative resolution of relative references in your representations.
REST ≠ pretty URLs. The two are orthogonal.
Your question is about the latter, I feel.
Whilst the other answers have been good, if you want your API to work with HTML forms, go with query parameters on the collection /user resource for all fields, even for ID (assuming a human is typing these in based on information they are getting from sheets of paper on their desk, etc.)
If your server is able to produce links to each record, always produce canonical links such as /users/{id}, don't duplicate data under different URLs.
Say we want to send a list of client IDs to some endpoint. Should we use the name "client" or "clients" for the query? I think both cases have pros and cons, but is there some convention for this?
GET https://somedomain.com/some/endpoint?client(s)=1&client(s)=2
REST doesn't care what spelling you use for your resource identifiers. Any information encoded into the identifier is done at the discretion of the server and for its own exclusive use.
Part of the reason for this: as the server, you want to be able to change how you encode information into the URI to make it work better for your infrastructure.
For example, if you were working with an query string parsing library that could automatically handle list arguments, provided that they matched some particular pattern, then you would want to be able to take advantage of that.
So the spelling conventions for query parameters is a local choice; very similar to the way that the spellings of variable names in code is a local choice.
Is it possible to search for a parameter in all the resources on a FHIR based server (currently using HAPI)?
{{url}}/Basic?_id=1
Returns the correct Basic resource but I want to be able to search through all resource types (Basic, Patient, Observation, etc.). I was hoping that there would be a way to do something like this:
{{url}}/ALL?_id=1
Thanks,
Stephen
You can search system wide by performing a search with this syntax
GET [base]?[parameters]{&_format=[mime-type]}
so in your case that would be
GET [base]?_id=1
Note that this only works for parameters defined on all resources, like _id.
See http://hl7.org/fhir/DSTU2/search.html for more search syntax and explanation/examples.
My api should support text search on specified fields. So I am thinking what kind of URL style handles it in the best way.
The below pattern, using "q" ,is mentioned in many blogs and documents to be used for full text search but I also need to specify field names:
GET /groups?q=bank+org
So I am thinking to use wildcards like below:
GET /groups?name=*bank*&owner=*org*
I am just wondering if this is aligned with the best practices in the market?
Thanks
Soheil, you are thinking right. "Search" is a "filter parameter" wich always go in the Query String.
When sending parameters that will be used to query a collection of resources you should use... Guess what! Query parameters!
As far as I know, there's no official documentation that states that. It's a common approach and it's widely adopted. The only offical documentation about query string that I'm aware of is the RFC 3986. Quoting:
3.4. Query
The query component contains non-hierarchical data that, along with
data in the path component, serves to identify a
resource within the scope of the URI's scheme and naming authority
(if any). The query component is indicated by the first question
mark ("?") character and terminated by a number sign ("#") character
or by the end of the URI. [...]
For a full text search, you can choose the parameter you find most convenient. Do you think q is a good one? Go for it! But provide a good documentation for it.
I'm developing the search functionality of my REST API and currently URI's structured as:
api/items?type=egg,potato
Let's say each item resource has 4 properties:
Id, Name, Type, Rating
What would be the most restful way to design my URI and return a subset of properties of each resource, e.g. only names of these resources?
--
The reason I ask this is I often want a less heavy duty result-set. For instance, I may build an AJAX search with dynamically populated names as dropdowns - but I do not want extra bloat coming back with each request.
REST isn't really a set of rock-solid standards, but there are some nice practices.
In this particular case I would recommend using the query parameter of an existing resource field as you are now, to select items which have the type value of egg or potato. But to select only a subset, you can introduce a field query parameter. So you can call your API like api/items?type=egg&fields=name, to get only the name field of all the resources with the egg type.
P.S
This is not my invention, I already seen this in other API's, somewhere called select. As far as I know, Facebook has this feature in its API's.