5. API Style Guide
• OPERATION [base]/[type]/[id] {?_format=[mime-type]}
• Content surrounded by {} is optional
6. HTTP Status Codes
• Specification makes rules about the use of specific HTTP status
codes in particular circumstances where the status codes SHALL
map to particular states correctly
• FHIR defines an OperationOutcome resource that can be used to
convey specific detailed processable error information.
• For a few combinations of interactions and specific return codes, an
OperationOutcome is required to be returned as the content of the
response.
• OperationOutcome may be returned with any HTTP 4xx or 5xx
response, but is not required
7. Content Types and encodings
• The correct mime type SHALL be used by clients and
servers.
• Servers SHOULD support the optional "_format" parameter
to specify alternative response formats by their MIME-types.
8. Content Types and encodings (contd..)
• For the _format parameter, the values "xml", "text/xml",
"application/xml", and "application/xml+fhir" SHALL be
interpreted to mean the normative XML format
• FHIR uses UTF-8 for all request and response bodies.
• Responses SHALL explicitly set the character encoding to
UTF-8 using the 'charset' parameter of the MIME-type in
the Content-Type header
• Requests MAY also specify this charset parameter in the
Accept header
9. Read (instance-level)
• GET [base]/[type]/[id] {?_format=[mime-type]}
• Servers are required to return a content-location header with the
response and Last-Modified header.
• Systems that do not track deleted records will treat deleted records
as an unknown resource.
Http Method Description
410 deleted resource
404 An unknown resource
200 If found resource
10. Vread (instance Level)
• GET [base]/[type]/[id]/_history/[vid] {?_format=[mime-type]}
Http Method Description
410 deleted resource
404 An unknown resource
405 If a request is made for a previous version of a resource,
and the server does not support accessing previous
versions
200 If found resource
11. update
• PUT [base]/[type]/[id] {?_format=[mime-type]}
• If successful , it will response with a Last-Modified header, and a Location
and Content-Location header
Http Method Description
200 interaction is successful
201 if the resource was created
405 the resource did not exist prior to the update
400(Bad Request ) Resource could not be parsed or failed basic FHIR validation
404 Resource type not supported, or not a FHIR end point
409 version conflict management
422 To reject update interactions because of integrity concerns or
business rules implemented on the server
412(Precondition
Failed)
For version aware server, Content-Location in the PUT request.
If the value is missing the will
12. delete
• DELETE [base]/[type]/[id]
• Resources that have been deleted may subsequently be brought back to
life by PUTting an update to them subsequent to the deletion.
Http Method Description
204 successful deletion
410 resource is no longer found through search interactions
405 If the server refuses to delete resources of that type on
principle
409 If the server refuses to delete a resource because of reasons
specific to that resource, such as referential integrity
13. create
• POST [base]/[type] {?_format=[mime-type]}
• The server returns a 201 Created, along with a Location
header which contains the new Logical Id and Version Id
• Location: [base]/[type]/[id]/_history/[vid]
• A server SHOULD accept the resource as submitted when
accepts the create, and return the same content when it is
subsequently read
14. Create (contd..)
Http Method Description
201 if the resource was created
400(Bad Request ) Resource could not be parsed or failed basic FHIR
validation
404(Not Found) Resource type not supported, or not a FHIR end point
422(Unprocessable
Entity)
the proposed resource violated applicable FHIR profiles
or server business rules. This should be accompanied by
anOperationOutcome resource providing additional
detail
15. search
• To search all resources at once:
– GET [base]?[parameters] {&_format=[mime-type]}
• To search a single resource type:
– GET [base]/[type]?[parameters] {&_format=[mime-type]}
– GET [base]/[type]/_search?[parameters] {&_format=[mime-type]}
• To search a compartment:
– GET [base]/[compartment]/[id]/?[parameters] {&_format=[mime-type]}
– GET [base]/[compartment]/[id]/[type]?[parameters] {&_format=[mime-type]}
• All these search interactions take a series of
parameters that are a series of name'='value pairs
encoded in the URL
16. search
• If the search fails, the return value is a status
code 4xx or 5xx with an OperationOutcome.
• If the search succeeds, the return content is
an Bundle containing the results of the search as
a list of resources in a defined order.
• If the search succeeds, the return content is
an Bundle containing the results of the search as
a list of resources in a defined order.
17. validate
• POST [base]/[type]/_validate{/[id]}
• The content is first checked against the general
specification and against the conformance profile that
applies to the application.
• if the optional [id] section is also provided, the resource is
considered as a proposed update to the specific resource.
• Additional instance specific rules such as referential
integrity and update logic (including version control) are
applied as well.
18. Validate (contd..)
• The client can ask the server to validate
against a particular resource by attaching
a profile tag to the resource.
• This is an assertion that the resource conforms
to the specified profile(s)
• The server SHALL check all the things it
requires of the resource as part of it's normal
operations
19. Validate (contd..)
Http Method Description
200 resource passed all validation rules
400(Bad Request ) Resource could not be parsed or failed basic FHIR
validation
422(Unprocessable
Entity)
the resource was valid, but as a proposed update, it
violates applicable FHIR profiles or server business rules
Notas del editor
vread interaction preforms a version specific read of the resource
Servers are encouraged to support a version specific retrieval of the current version of the resource even if they are do not provide access to previous versions.
update interaction creates a new current version for an existing resource or creates a new resource if no resource already exists for the given id.
Servers MAY choose to preserve XML comments, instructions, and formatting or JSON whitespace when accepting updates, but are not required to do so. The impact of this on digital signatures may need to be considered.
The delete interaction removes an existing resource.
The create interaction creates a new resource in a server assigned location. If the client wishes to have control over the id of a newly submitted resource,
This interaction searches a set of resources based on some filter criteria..
The validate interaction checks whether the attached content would be acceptable as an update to an existing resource.