Implementation Guide
23.1.0 - R4 APIs

Publish Box goes here

RESTful API

Read

Read interactions are executed as specified in the HL7 FHIR RESTful API implementation definition.

GET [base]/fhir/r4/[type]/[id]{?_format=[json|xml]&_summary=[true|data]}

Where:

Parameter Description
[base] Specifies the base URL of the FHIR Server, e.g., https://apsandbox.fhirapi.athenahealth.com/demoAPIServer
[type] Specifies the name of a resource type
[id] Specifies the logical id of a specific resource to retrieve
[_format] Specifies the format of the output and may be xml or json. When present, the _format value overrides the value of the Accept header in the request.
[_summary] Filters the output to include only summary elements (_summary=true) or to omit the generated narrative (_summary=data). Note: If the generated html narrative for the resource is not going to be used by the call, using _summary=data provides slightly improved API response times.
HTTP Response Codes

The following HTTP response codes are returned by read API call:

Response code Description
200 OK The requested resource was found and is contained within the body of the HTTP response.
401 Unauthorized Authorization is required for this request, and either the Authorization header is missing or the supplied user credentials in the Authorization header are not valid or have expired. The body of the HTTP response will contain an OperationOutcome resource that indicates that Authorization is required.
404 Not Found The requested resource does not exist. The body of the HTTP response will contain an OperationOutcome resource that indicates that the resource could not be found.
500 Server Error The server may return other error codes to indicate other error conditions. The body of the HTTP response will contain an OperationOutcome resource that indicates the nature of the error.

Create

Create interactions are executed as specified in the HL7 FHIR RESTful API implementation definition. To create a new resource, an application must perform an HTTP POST, specifying the content of the resource in the body of the request.

POST [base]/fhir/r4/[type]?{_format=[json|xml]}

Where:

[_format]
Specifies the format of the output and may be xml or json. When present, the _format value overrides the value of the Accept header in the request.
HTTP Response Codes

The following HTTP response codes are returned by this API call:

Response code Description
201 Created The resource was created at the location specified in the HTTP Location header. Note: Unsupported fields will be accepted in a request but will not be persisted to the database. Some fields may be mapped to database specific codes which closely but not perfectly match the input. See the HL7 FHIR specification for more detail on server permitted changes.
400 Bad Request The resource could not be parsed, or failed basic validation rules. The body of the HTTP response will contain an OperationOutcome resource that provide more detail about the reason for the failure.
401 Unauthorized Authorization is required for this request, and either the Authorization header is missing or the supplied user credentials in the Authorization header are not valid or have expired. The body of the HTTP response will contain an OperationOutcome resource that indicates that Authorization is required.
422 Unprocessable Entity The proposed resource violated server business rules. For example, a required field may be missing or a field may contain a value that is not supported by the API Server. The body of the HTTP response will contain an OperationOutcome resource that provide more detail about the reason for the failure.
500 Server Error The server may return other error codes to indicate other error conditions. The body of the HTTP response will contain an OperationOutcome resource that indicates the nature of the error.

Update

Update interactions are executed as specified in the HL7 FHIR RESTful API implementation definition. To update an existing resource, an application must perform an HTTP PUT, specifying the content of the resource in the body of the request.

PUT [base]/fhir/r4/[type]/[id]?{_format=[json|xml]}

Where:

[_format]
Specifies the format of the output and may be xml or json. When present, the _format value overrides the value of the Accept header in the request.
HTTP Response Codes

The following HTTP response codes are returned by this API call:

Response code Description
200 OK The resource was updated at the location specified in the HTTP Location header. Note: Unsupported fields will be accepted in a request but will not be persisted to the database. Some fields may be mapped to database specific codes which closely but not perfectly match the input. See the HL7 FHIR specification for more detail on server permitted changes.
400 Bad Request The resource could not be parsed, or failed basic validation rules. The body of the HTTP response will contain an OperationOutcome resource that provide more detail about the reason for the failure.
401 Unauthorized Authorization is required for this request, and either the Authorization header is missing or the supplied user credentials in the Authorization header are not valid or have expired. The body of the HTTP response will contain an OperationOutcome resource that indicates that Authorization is required.
422 Unprocessable Entity The proposed resource violated server business rules. For example, a required field may be missing or a field may contain a value that is not supported by the API Server. The body of the HTTP response will contain an OperationOutcome resource that provide more detail about the reason for the failure.
500 Server Error The server may return other error codes to indicate other error conditions. The body of the HTTP response will contain an OperationOutcome resource that indicates the nature of the error.

Delete

Delete interactions are executed as specified in the HL7 FHIR RESTful API implementation definition. To delete an existing resource, an application must perform an HTTP DELETE command

DELETE [base]/fhir/r4/[type]/[id]?{_format=[json|xml]}

Where:

[_format] Specifies the format of the output and may be xml or json. When present, the _format value overrides the value of the Accept header in the request.
HTTP Response Codes

The following HTTP response codes are returned by this API call:

Response code Description
200 OK The resource has been deleted
400 Bad Request The resource could not be parsed, or failed basic validation rules. Id may be missing or does not follow required format.
401 Unauthorized Authorization is required for this request, and either the Authorization header is missing or the supplied user credentials in the Authorization header are not valid or have expired.
500 Server Error The server may return other error codes to indicate other error conditions. The body of the HTTP response will contain an OperationOutcome resource that indicates the nature of the error.