The Rosetta API is a REST-based interface, which means that applications make requests to the API by accessing specific URLs using HTTP. One of the hallmarks of REST is that the API calls are stateless, meaning each request is a single, self-contained operation.
The API does not persist data, so the typical REST “CRUD” (create-read-update-delete) model does not apply. All operations are transient requests to analyze or transform the provided data.
Contents
The endpoint for the Rosetta API is:
https://api.rosetta.careevolution.com
For example:
https://api.rosetta.careevolution.com/terminology/v1/classify/condition
In the API reference, the base URL is usually omitted for brevity, and only the bolded part given.
Every API call requires the following fields in the HTTP request header:
Field | Required Value | Description |
---|---|---|
x-api-key | YOUR_API_KEY | Contains your API key, obtained from the Developer Portal. See API Keys for details. |
content-type | See Data Formats. | Defines the format of the data sent to Rosetta. |
accept | See Data Formats. | Defines the desired output format. |
Most data sent to and received from the Rosetta API will be in JSON format, so both the content-type
and accept
headers will be application/json
.
A few operations can accept or return content in other formats, such as application/xml
, application/x-ndjson
, or even text/plain
. These are noted in their respective API details.
No additional authorization is required beyond the API key header (see required headers).
This section gives a brief introduction to REST APIs in general, and discusses how that model applies to Rosetta.
In the Rosetta API, REST resources are services. These services are organized into collections, such a terminology and convert. Versioning is built into the URLs (see versioning for details).
For example, the URL terminology/v1
is the root for all “version 1” terminology-based services, with resources like terminology/v1/standardize/condition
and terminology/v1/classify/medication
.
Some segments of the API URLs begin with a : to indicate that they are variables conveying information about the specific resource you wish to access. For example, the URL /convert/v1/cdatofhirr4/:patientID
lets you specify a patient identifier.
Every API call uses a specific HTTP verb, which tells the system what kind of action you want to take with the resource. Different verbs are supported for each resource; consult the API documentation for details. Most Rosetta operations use the POST
verb, reflecting a request to analyze or perform a transformation on the provided data.
Many API calls use query parameters and/or request body data to send data to the server. For example, a POST
to the /terminology/v1/standardize/condition
API might contain the body data:
{
"code": "A000",
"system": "ICD-10-CM"
}
Be sure to specify the content type in your requests.
The response header for each request contains a status code indicating whether the request was successful. Common status codes you will encounter are:
Code | Description |
---|---|
200 Success | The request was successful. |
400 Bad Request | There was a problem with your request parameters. |
403 Forbidden | Check your API key (see Required Headers). |
429 Too Many Requests | You have exceeded the API usage limits. See Rate Limits for details. |
500 Internal Server Error | There was an unknown issue processing the request. Check the response body for details, and contact us if you need help determining the problem. |
In addition to the HTTP status codes, many of the FHIR-based APIs will include an OperationOutcome resource in their output. An OperationOutcome is a collection of issue
elements detailing what was parsed from the input, as well as any problems with the conversion. The issue severity, code, and details elements will describe the specifics of the issue and its location within the input data. The issue code will be one of the following values from the FHIR IssueType list:
For example:
{
"resource": {
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "warning",
"code": "processing",
"details": {
"text": "Labs: Missing description in the reference dictionary for #labgroup_3. Line Number - 662, XPath - ClinicalDocument/component/structuredBody/component/section/entry/organizer/code/originalText/reference"
}
},
{
"severity": "information",
"code": "informational",
"details": {
"text": "Processed 2 entries from Encounters section."
}
},
... (additional issues if applicable)
]
}
}
When using the development sandbox, issues from the OperationOutcome will automatically be highlighted in the alert area for easy reference.