When implementing a server operation, there are a number of failure conditions - specified. For example, an - Instance Read request might specify an unknown - resource ID, or a Type Create request might contain an + specified. For example, an + Instance Read + request might specify an unknown + resource ID, or a + Type Create + request might contain an invalid resource which can not be created.
In these cases, an appropriate exception should be thrown. The HAPI RESTful - API includes a set of exceptions extending + API includes a set of exceptions extending BaseServerResponseException which represent specific HTTP failure codes.
- See the + See the Exceptions List - for a complete list of these exceptions. Note that these exceptions are all unchecked + for a complete list of these exceptions. Note that these exceptions are all + unchecked exceptions, so they do not need to ne explicitly declared in the method signature.
- + ++ FHIR RESTful servers may support a feature known as tagging. Tags are a set of + named flags called "terms" (with an optional accompanying human friendly name + called a "label", + and an optional namespace called a "scheme"). +
++ Tags have very specific semantics, which may not be + obvious simply by using the HAPI API. It is important to review the specification + pages + here + and + here + before attempting to implement tagging in your own applications. +
+ ++ Tags are stored within a resource object, in the + IResource.html#getResourceMetadata() + map, under the key + TAG_LIST. +
+ ++ In a server implementation, you may populate your tags into the + returned resource(s) and HAPI will automatically place these tags into + the response headers (for read/vread) or the bundle category tags (for search). + The following example illustrates how to return tags from a server method. This + example shows how to supply tags in a read method, but the same approach applies + to vread and search operations as well. +
+ ++ In a client operation, you simply call the read/vread/search method as you + normally would (as described above), and if any tags have been returned + by the server, these may be accessed from the resource metadata. +
+ ++ Within a Type Create + or Instance Update method, it is + possible for the client to specify a set of tags to be stored + along with the saved resource instance. +
++ Note that FHIR specifies that in an update method, any tags supplied + by the client are copied to the newly saved version, as well as any + tags the existing version had. +
+ ++ To work with tags in a create/update method, the pattern used in the + read examples above is simply revered. In a server, the resource which + is passed in will be populated with any tags that the client supplied: +
+ ++ FHIR also provides a number of operations to interact directly + with tags. These methods may be used to retrieve lists of tags + that are available on the server, or to add or remove tags from + resources without interacting directly with those resources. +
+ ++ On a server these methods may be placed in a plain provider, or in a resource + provider in the case of resource type specific methods. +
++ On a client, the methods are defined in the exact same way, except that + there is no method body in the client interface. +
+ +