Data Syndication API v1

Data Syndication facilitates the bulk delivery of HealtheIntent data. It provides direct, low-level, asynchronous access to the information that HealtheIntent solutions create, curate, and operate against. This API is used mainly to populate a data warehouse or other third-party data store for research, reporting, or analytical activities.

Release Considerations: The Data Syndication endpoints are available at both of the URLs below; however, as of December 5, 2018, the /syndication path is deprecated and should not be used. Any existing scripts that use /syndication should be updated to use /data-syndication. This note will be removed or updated when the /syndication path no longer is supported.

• https://{tenantMnemonic}.api.{region}.healtheintent.com/data-syndication/v1/{resource}
• https://{tenantMnemonic}.api.{region}.healtheintent.com/syndication/v1/{resource}

Terminology

To help understand these concepts, consider an analogy to the delivery of physical products. Suppose you want to have a newspaper, the Cerner Post, delivered to you by the postal service every day, but that you are only interested in the classifieds section. In this example:

• The feed type is the Cerner Post.
• The feed specifies that you want to receive only the classifieds section, and that you want the newspaper every day.
• Every day a bundle is generated containing the classifieds section for that day.
• The channel type is the postal service.
• The delivery channel contains everything the postal service needs to deliver to you, for example, your name and address.
• Every day a delivery happens when the postal service delivers the bundle to your mailbox.

Feed Types

The following feed types are currently available:

Channel Types

The channel types below are currently available. Deliveries have associated metadata, the schema of which depends on the type of the channel the delivery belongs to.

Download Channel Type Archive Structure

Each delivery contains data that corresponds to one or more entities, for example, allergies or claims. Each entity may have one or more parts. The data can be laid out with the parts combined or separate in deliveries for a DOWNLOAD channel.

Parts Combined

This is the default format. Currently, any newly created channels will use this format.

When this format is used, all entity parts are combined into a single file in the delivery archive. For example, if the bundle has two entities (entity1 and entity2) and each entity has two parts (part1 and part2), the part files are combined and the resulting delivery archive file has the following contents after it is unarchived:

|-- entity1
|
|-- entity2

In the above example, entity1 and entity2 are both files that contain the contents of their respective part1 and part2 parts concatenated together. Note that the files do not have file extensions. Depending on the feed type, the format of the data in the files may be different. See the documentation for each feed type for more information.

Parts Separate

When this format is used, all entity parts remain separate in the delivery archive. For example, if the bundle has two entities (entity1 and entity2) and each entity has two parts (part1 and part2), the part files remain separate and the resulting delivery archive file has the following contents after it is unarchived:

|-- entity1
|  |-- part1
|  |-- part2
|
|-- entity2
|  |-- part1
|  |-- part2

In the above example, entity1 and entity2 are both directories that contain their respective part1 and part2 part files. The part files may or may not have file extensions. Depending on the feed type, the format of the data in the files may be different. See the documentation for each feed type for more information.

S3 Channel Type Delivery Structure

For S3 channels, the delivery data is written directly to the bucket and not packaged in an archive file. For example, if the bundle has two entities (entity1 and entity2) and each entity has two parts (part1 and part2), the data written to the bucket has the following structure:

|-- entity1
|  |-- part1
|  |-- part2
|
|-- entity2
|  |-- part1
|  |-- part2

Data Retention

Download Channel Type

Due to the size of archive files, it is not practical for Cerner to retain them indefinitely. Each archive file produced using the DOWNLOAD channel type is available for three weeks from the time when the delivery is completed, as indicated by the deliveredAt timestamp in the corresponding delivery object. After three weeks, Cerner deletes the file and the delivery’s status is changed to PURGE_IN_PROGRESS or PURGED to indicate that the file can no longer be downloaded. If a system attempts to retrieve the delivery after that time, a 404 HTTP status code (Not Found) is sent.

S3 Channel Type

Cerner does not manage files after they are delivered using the S3 channel type to client-owned Amazon S3 buckets. If you use the S3 channel type, you are responsible for defining your data retention policy for the delivered files.

Getting Started

Requesting a Feed

Before you can use the Data Syndication API, you must have at least one feed and at least one channel for that feed. Contact your HealtheIntent engagement leader or log a service record (SR) in eService to the solution related to the feed type to request a new feed for a particular feed type.

You can use the /channels endpoint to create new channels for existing feeds. Note that when a bundle is produced, deliveries are performed using only channels that are active at the time. This means that when a new channel is created, deliveries are not retroactively performed using that channel for bundles that were produced before the channel’s creation.

See Configure Data Syndication Feeds and Channels for more information.

Authorization

Only authorized system accounts can access endpoints. Contact your HealtheIntent engagement leader to request that authorization be granted or authorize the system account for the authorization policy scopes in HealtheIntent Console below. See Configure Data Syndication Feeds and Channels and Viewing, Adding, and Editing API Authorizations Using HealtheIntent Console for more information.

Looking Up Feeds and Deliveries

You can use the /feeds/{feedId}/bundles endpoint to view all the bundles that have been produced for a given feed or the /channels/{channelId}/deliveries endpoint to see all the deliveries that have occurred for a given channel.

Downloading the Latest Deliveries

Example Automated Downloading Script

require 'fileutils'
require 'httparty'

# Replace cernerdemo with your tenant mnemonic.
BASE_URL = 'https://cernerdemo.api.healtheintent.com/data-syndication/v1'
# Replace this with the ID of the channel for your feed.
CHANNEL_ID = '5fcdb1e1-3b82-4272-acfb-1242d456e4f4'
# Insert a valid Authorization header here.
AUTH_HEADER = '...'
# This script divides each download into parts. This constant sets the maximum number of bytes in each part.
PART_SIZE = 1024 * 1024 * 600

def download_new_deliveries
  loop do
    # Get the timestamp of the last downloaded bundle from persistence.
    last_released_at = File.read('checkpoint.txt') if File.exist?('checkpoint.txt')

    query_params = { orderBy: 'bundleReleasedAt', offset: 0, limit: 1 }
    query_params.merge!(bundleReleasedAfter: last_released_at) unless last_released_at.nil?

    headers = { 'Authorization' => AUTH_HEADER, 'Accept' => 'application/json' }
    url = "#{BASE_URL}/channels/#{CHANNEL_ID}/deliveries"
    response = HTTParty.get(url, headers: headers, query: query_params)
    unless response.code == 200
      raise StandardError, "Unable to retrieve latest deliveries. Response code = #{response.code}. Response body:\n#{response.body}"
    end

    delivery = response.parsed_response['items'].first

    if delivery.nil?
      puts 'No more bundles are available for download at this time.'
      break
    end

    if delivery['status'] == 'IN_PROGRESS'
      puts 'The download for the next bundle is still being prepared. Try again later.'
      break
    end

    if delivery['status'] != 'DELIVERED'
      raise StandardError, "The delivery with ID #{delivery['id']} failed. Contact your HealtheIntent engagement leader for support."
    end

    released_at = delivery['bundle']['releasedAt']
    filename = "#{released_at.delete('-:.')}#{get_file_extension(delivery['metadata']['archiveFormat'])}"
    puts "Downloading bundle released at #{released_at}."
    download_file(delivery['id'], filename)

    File.write('checkpoint.txt', delivery['bundle']['releasedAt'])
  end
end

def get_file_extension(archiveFormat)
  if archiveFormat == 'TAR_GZ'
    '.tar.gz'
  elsif archiveFormat == 'TAR_CONTAINING_LZ4'
    '.tar'
  end
end

def get_download_size(id)
  headers = {
    'Authorization' => AUTH_HEADER,
    'Accept' => 'application/octet-stream'
  }

  url = "#{BASE_URL}/downloads/#{id}"
  response = HTTParty.head(url, headers: headers)
  content_length = response.headers['Content-Length']
  unless response.code == 200 && content_length
    raise StandardError, "Unable to retrieve file size. Response code = #{response.code}. Response headers:\n#{response.headers}\nResponse body:\n#{response.body}"
  end

  content_length.to_i
end

def download_range(id, range, part_filename, retries = 3)
  headers = {
    'Authorization' => AUTH_HEADER,
    'Accept' => 'application/octet-stream',
    'Range' => "bytes=#{range}"
  }

  url = "#{BASE_URL}/downloads/#{id}"
  response = HTTParty.get(url, headers: headers)
  if response.code != 206
    raise StandardError, "Unexpected response code when attempting to download range. Response code = #{response.code}. Response body:\n#{response.body}"
  end

  File.binwrite(part_filename, response.body)
rescue StandardError => ex
  puts "Error: #{ex}"
  if retries > 0
    puts 'Retrying...'
    sleep 5
    download_range(id, range, part_filename, retries - 1)
  else
    raise StandardError, 'Unable to download range. Try again later.'
  end
end

def download_file(id, filename)
  length = get_download_size(id)
  puts "File size: #{length} bytes"

  dir = "#{filename}.parts"
  FileUtils.mkdir_p(dir)

  range_start = 0
  part_filenames = []

  while range_start < length
    range_end = [range_start + PART_SIZE, length].min - 1
    range = "#{range_start}-#{range_end}"
    part_filename = File.join(dir, "#{range_start}-#{range_end}")
    part_filenames << part_filename

    if File.exist?(part_filename) && File.size(part_filename) == (range_end - range_start + 1)
      puts "Already downloaded range #{range}."
    else
      puts "Downloading range #{range}."
      download_range(id, range, part_filename)
    end

    range_start += PART_SIZE
  end

  puts "All ranges downloaded. Combining ranges into final file: #{filename}"
  file = File.open(filename, 'wb')
  part_filenames.each do |part_filename|
    part_file = File.open(part_filename, 'rb')
    FileUtils.copy_stream(part_file, file)
    part_file.close
  end
  file.close

  # Delete the temporary files containing the separate parts.
  FileUtils.rm_r(dir)
end

download_new_deliveries

If you have a channel that uses the DOWNLOAD channel type, then you likely want to set up an automated process that regularly scans for new deliveries and downloads them. Complete the following steps to automatically download the delivered bundles:

1. Determine your channel ID. You can use the /feeds endpoint to determine the feed ID, then use the /channels endpoint to determine the channel with that feed ID and a channel type mnemonic of DOWNLOAD.
2. Use the /channels/{channelId}/deliveries endpoint to determine the list of available deliveries.
   • You will use the delivery’s id in the next step to perform the download.
   • Look for deliveries whose status field is DELIVERED, indicating they are available to download now.
   • Each delivery includes a bundle.releasedAt field that indicates the date and time when the bundle was produced. You can order and filter the response by specifying the bundleReleasedAt and bundleReleasedAfter query parameters. You can use those parameters to download all the deliveries up to a certain date and time, then save the bundle.releasedAt value so you can use the value in the bundleReleasedAfter query parameter next time and download only the new deliveries.
3. Use the /downloads/{deliveryId} endpoint to download the data.
   • The format of the downloaded file is determined by the channel configuration’s archiveFormat attribute. If it is not set or is set to TAR_GZ, the file is a gzip-compressed tar archive file and should have a file extension of .tar.gz. If it is set to TAR_CONTAINING_LZ4, the downloaded file is a tar archive containing LZ4-compressed files and should have a file extension of .tar. If it is set to TAR_CONTAINING_GZ, the downloaded file is a tar archive containing gzip-compressed files and should have a file extension of .tar. While a .tar.gz file can be extracted and decompressed all at once, the .tar first needs to be extracted then the files in it can be decompressed using LZ4 or gzip. The archive format used for a delivery also is included in the delivery’s metadata as the archiveFormat attribute. Note that a channel’s configuration can be updated to change the format of future deliveries. The format in a delivery’s metadata should be used to determine how to handle the file, because that reflects the actual format of the file.

Note: The Data Syndication service does not guarantee the order in which deliveries are performed. When incremental data is downloaded, deliveries must be consumed in order of the oldest to the most recent bundleReleasedAt value, regardless of the time of delivery. This means that a given incremental delivery cannot be consumed until all incremental deliveries with older bundleReleasedAt values in the same feed are consumed.

The example automated downloading script demonstrates how to download all the deliveries of a given channel in order. The script can be run automatically on a schedule to ensure that you retrieve new deliveries as they become available. You will likely want to include the following features of the script in your code:

• The Range header is used to download files in chunks of a specific size, rather than downloading the entire file at once. The script reassembles the chunks into the full file once they have all been downloaded.
• If the downloading of a chunk fails, the script retries a fixed number of times. If it still fails, the script resumes the download at that chunk the next time you run it.
• Deliveries are processed in order, and processing stops if any deliveries in a status of FAILED or IN_PROGRESS are encountered. This is because while you can download the files out of order, you may need to import the data the files contain into your system in the correct order to ensure that changes from earlier incremental bundles do not overwrite changes in later incremental bundles.
• The archiveFormat attribute of the delivery’s metadata should be used to identify the format of the file and determine the correct file extension.

Feeds

Retrieve a List of Feeds

Example Request

require 'httparty'

HTTParty.get(
  'https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/feeds?feedTypeMnemonic=long-record&orderBy=name',
  headers: {
    'Accept' => 'application/json',
    'Authorization' => '<auth_header>'
  }
)

curl -X GET -H 'Authorization: {auth_header}' -H 'Accept: application/json'
'https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/feeds?feedTypeMnemonic=long-record&orderBy=name'

Example Response

{
  "items": [
    {
      "id": "0f1c7802-6255-46f0-b898-6e5b851bc0af",
      "name": "Primary Population Records",
      "status": "ACTIVE",
      "scope": {
        "population": {
          "id": "5bdb91f7-c779-450d-8309-e14cd7672589"
        }
      },
      "feedType": {
        "mnemonic": "long-record"
      },
      "createdAt": "2018-04-06T21:17:55.423Z",
      "updatedAt": "2018-04-06T21:17:55.423Z"
    }
  ],
  "totalResults": 1,
  "firstLink": "https://cernerdemo.api.devhealtheintent.com/data-syndication/v1/feeds?feedTypeMnemonic=long-record&orderBy=name&offset=0&limit=20",
  "lastLink": "https://cernerdemo.api.devhealtheintent.com/data-syndication/v1/feeds?feedTypeMnemonic=long-record&orderBy=name&offset=0&limit=20&",
}

GET https://{tenantMnemonic}.api.{region}.healtheintent.com/data-syndication/v1/feeds

Retrieves a list of feeds matching the query.

Query Parameters

Responses

Retrieve a Single Feed

Example Request

require 'httparty'

HTTParty.get(
  'https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/feeds/0f1c7802-6255-46f0-b898-6e5b851bc0af',
  headers: {
    'Accept' => 'application/json',
    'Authorization' => '<auth_header>'
  }
)

curl -X GET -H 'Authorization: {auth_header}' -H 'Accept: application/json'
'https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/feeds/0f1c7802-6255-46f0-b898-6e5b851bc0af'

Example Response

{
  "id": "0f1c7802-6255-46f0-b898-6e5b851bc0af",
  "name": "Primary Population Records",
  "status": "ACTIVE",
  "scope": {
    "population": {
      "id": "5bdb91f7-c779-450d-8309-e14cd7672589"
    }
  },
  "feedType": {
    "mnemonic": "long-record"
  },
  "createdAt": "2018-04-06T21:17:55.423Z",
  "updatedAt": "2018-04-06T21:17:55.423Z"
}

GET https://{tenantMnemonic}.api.{region}.healtheintent.com/data-syndication/v1/feeds/{feedId}

Retrieves a single feed.

Path Parameters

Responses

Bundles

Retrieve a List of Bundles

Example Request

require 'httparty'

HTTParty.get(
  'https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/feeds/0f1c7802-6255-46f0-b898-6e5b851bc0af/bundles?releasedAfter=2018-02-03T01:00:00.000Z&orderBy=releasedAt',
  headers: {
    'Accept' => 'application/json',
    'Authorization' => '<auth_header>'
  }
)

curl -X GET -H 'Authorization: {auth_header}' -H 'Accept: application/json'
'https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/feeds/0f1c7802-6255-46f0-b898-6e5b851bc0af/bundles?releasedAfter=2018-02-03T01:00:00.000Z&orderBy=releasedAt'

Example Response

{
  "items": [
    {
      "id": "5ebcac9e-1f1a-4181-8c0f-4300a3af83d9",
      "feed": {
        "id": "0f1c7802-6255-46f0-b898-6e5b851bc0af"
      },
      "releasedAt": "2018-04-11T18:37:25.063Z",
      "metadata": {}
    },
    {
      "id": "8d75de0e-358b-434d-97fe-6f1ba3598098",
      "feed": {
        "id": "0f1c7802-6255-46f0-b898-6e5b851bc0af"
      },
      "releasedAt": "2018-04-11T20:21:12.461Z",
      "metadata": {}
    }
  ],
  "totalResults": 2,
  "firstLink": "https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/feeds/0f1c7802-6255-46f0-b898-6e5b851bc0af/bundles?releasedAfter=2018-02-03T01:00:00.000Z&orderBy=releasedAt&offset=0&limit=20",
  "lastLink": "https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/feeds/0f1c7802-6255-46f0-b898-6e5b851bc0af/bundles?releasedAfter=2018-02-03T01:00:00.000Z&orderBy=releasedAt&offset=0&limit=20",
}

GET https://{tenantMnemonic}.api.{region}.healtheintent.com/data-syndication/v1/feeds/{feedId}/bundles

Retrieves a list of bundles matching the query.

Path Parameters

Query Parameters

Responses

Retrieve a Single Bundle

Example Request

require 'httparty'

HTTParty.get(
  'https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/bundles/5ebcac9e-1f1a-4181-8c0f-4300a3af83d9',
  headers: {
    'Accept' => 'application/json',
    'Authorization' => '<auth_header>'
  }
)

curl -X GET -H 'Authorization: {auth_header}' -H 'Accept: application/json'
'https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/bundles/5ebcac9e-1f1a-4181-8c0f-4300a3af83d9'

Example Response

{
  "id": "5ebcac9e-1f1a-4181-8c0f-4300a3af83d9",
  "feed": {
    "id": "0f1c7802-6255-46f0-b898-6e5b851bc0af"
  },
  "releasedAt": "2018-04-11T18:37:25.063Z",
  "metadata": {}
}

GET https://{tenantMnemonic}.api.{region}.healtheintent.com/data-syndication/v1/bundles/{bundleId}

Retrieves a single bundle.

Path Parameters

Responses

Channels

Create a Channel

Example Request

require 'httparty'
require 'json'

HTTParty.post(
  'https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/channels',
  headers: {
    'Accept' => 'application/json',
    'Content-Type' => 'application/json'
    'Authorization' => '<auth_header>'
  },
  body: {
    name: 'Download Primary Population Records',
    feed: {
      id: '0f1c7802-6255-46f0-b898-6e5b851bc0af'
    },
    downloadConfig: {
      archiveFormat: 'TAR_GZ'
    }
  }.to_json
)

curl -X POST -H 'Authorization: {auth_header}' -H 'Accept: application/json' -H 'Content-Type: application/json'
-d '{"name": "Download Primary Population Records", "feed": {"id": "0f1c7802-6255-46f0-b898-6e5b851bc0af"}, "downloadConfig": {"archiveFormat": "TAR_GZ"}}'
'https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/channels'

Example Response

{
  "id": "5fcdb1e1-3b82-4272-acfb-1242d456e4f4",
  "name": "Download Primary Population Records",
  "feed": {
    "id": "0f1c7802-6255-46f0-b898-6e5b851bc0af"
  },
  "type": "DOWNLOAD",
  "config": {
    "archiveFormat": "TAR_GZ"
  },
  "status": "ACTIVE",
  "createdAt": "2018-04-11T17:02:40.936Z",
  "updatedAt": "2018-04-11T17:02:40.936Z"
}

POST https://{tenantMnemonic}.api.{region}.healtheintent.com/data-syndication/v1/channels

Creates a new channel.

Note that in the request body, the following config attributes can be used: downloadConfig and s3Config. These correspond to the different channel types that can be created. Only one config attribute is in the response so that the response body schema is consistent between this endpoint and the Retrieve a Single Channel endpoint.

Choosing an Archive Format

When a DOWNLOAD channel is created, an archive format must be provided. The main determining factor in this decision is the speed of delivery versus the resulting archive size and ease of consumption. See the following information about the size and ease of consumption of the file formats:

• The TAR_GZ format produces archives in the regular .TAR.GZ format, which can be unarchived using tools included in most operating systems. This format produces the smallest resulting archive size, but deliveries with this format take the longest. This format is recommended for channels with delivery sizes usually less than a few hundred gigabytes.

• The TAR_CONTAINING_GZ format produces tar archives that contain files individually compressed with gzip. First the archive must be unpacked, then each resulting file must be decompressed individually. This format produces archives comparable in size to the TAR_GZ format much faster, but the archives are more complex to consume due to the need to decompress each file individually. This format is recommended for only channels with delivery sizes regularly more than a few hundred gigabytes.

• The TAR_CONTAINING_LZ4 format produces tar archives that contain files individually compressed with LZ4. As with TAR_CONTAINING_GZ, first the archive must be unpacked, then each resulting file must be decompressed individually. The difference is that the individual files are compressed in the LZ4 format, which is not supported as widely as the gzip format. This format produces larger archives than the TAR_GZ or TAR_CONTAINING_GZ format, but deliveries with this format are the fastest. Compared to TAR_GZ, deliveries with the TAR_CONTAINING_LZ4 format take about one sixth the amount of time, and the resulting archive file is about 1.5 times the size. This format is recommended for only channels with delivery sizes regularly more than a few hundred gigabytes. Before choosing this format, ensure that the LZ4 compression format is supported by the consuming processes.

Note that the relative speeds of the archive formats affect the time it takes to produce deliveries only after bundles are available; it does not affect the amount of time it takes to produce bundles.

S3 Channel Authorization

When an S3 channel is created, the response includes a roleArn attribute. This is the ARN of the AWS role that Cerner will use to deliver data to the bucket provided in the request. For deliveries to be performed successfully, this role needs to be granted s3:PutObject and s3:PutObjectAcl permissions in the bucket’s policy.

The bucket policy statement that grants access should be similar to the following statement:

{
  "Effect": "Allow",
  "Principal": {
    "AWS": "<role ARN>"
  },
  "Action": [
    "s3:PutObject",
    "s3:PutObjectAcl"
  ],
  "Resource": "arn:aws:s3:::<bucket name>/<base bucket path>/*"
}

The above statement is the recommended way to grant permissions, but if a Condition is preferred, it would be in the following format:

Note: If this Condition is used, AWS flags the bucket as having public access.

{
  "Effect": "Allow",
  "Principal": "*",
  "Action": [
    "s3:PutObject",
    "s3:PutObjectAcl"
  ],
  "Resource": "arn:aws:s3:::<bucket name>/<base bucket path>/*",
  "Condition": {
    "ArnEquals": {
      "aws:PrincipalArn": "<role ARN>"
    }
  }
}

Note: If the bucket is encrypted with a custom KMS key, a KMS key ARN should be provided in the request to create the channel, and the role ARN also needs to be granted kms:GenerateDataKey*, kms:Encrypt, and kms:Decryptpermissions for the KMS key.

See the Provide Cross-Account Access to Objects in S3 Buckets page on the AWS website for more information about the strategy Data Syndication uses for cross-account S3 bucket access, which is referred to as resource-based policies and IAM policies in the AWS documentation.

Parameters

Responses

Retrieve a List of Channels

Example Request

require 'httparty'

HTTParty.get(
  'https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/channels?feedId=0f1c7802-6255-46f0-b898-6e5b851bc0af&orderBy=name',
  headers: {
    'Accept' => 'application/json',
    'Authorization' => '<auth_header>'
  }
)

curl -X GET -H 'Authorization: {auth_header}' -H 'Accept: application/json'
'https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/channels?feedId=0f1c7802-6255-46f0-b898-6e5b851bc0af&orderBy=name'

Example Response

{
  "items": [
    {
      "id": "5fcdb1e1-3b82-4272-acfb-1242d456e4f4",
      "name": "Download Primary Population Records",
      "feed": {
        "id": "0f1c7802-6255-46f0-b898-6e5b851bc0af"
      },
      "type": "DOWNLOAD",
      "config": {
        "archiveFormat": "TAR_GZ"
      },
      "status": "ACTIVE",
      "createdAt": "2018-04-11T17:02:40.936Z",
      "updatedAt": "2018-04-11T17:02:40.936Z"
    }
  ],
  "totalResults": 1,
  "firstLink": "https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/channels?feedId=0f1c7802-6255-46f0-b898-6e5b851bc0af&orderBy=name&offset=0&limit=20",
  "lastLink": "https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/channels?feedId=0f1c7802-6255-46f0-b898-6e5b851bc0af&orderBy=name&offset=0&limit=20&"
}

GET https://{tenantMnemonic}.api.{region}.healtheintent.com/data-syndication/v1/channels

Retrieves a list of channels matching the query.

Query Parameters

Responses

Retrieve a Single Channel

Example Request

require 'httparty'

HTTParty.get(
  'https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/channels/5fcdb1e1-3b82-4272-acfb-1242d456e4f4',
  headers: {
    'Accept' => 'application/json',
    'Authorization' => '<auth_header>'
  }
)

curl -X GET -H 'Authorization: {auth_header}' -H 'Accept: application/json'
'https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/channels/5fcdb1e1-3b82-4272-acfb-1242d456e4f4'

Example Response

{
  "id": "5fcdb1e1-3b82-4272-acfb-1242d456e4f4",
  "name": "Download Primary Population Records",
  "feed": {
    "id": "0f1c7802-6255-46f0-b898-6e5b851bc0af"
  },
  "type": "DOWNLOAD",
  "config": {
    "archiveFormat": "TAR_GZ"
  },
  "status": "ACTIVE",
  "createdAt": "2018-04-11T17:02:40.936Z",
  "updatedAt": "2018-04-11T17:02:40.936Z"
}

GET https://{tenantMnemonic}.api.{region}.healtheintent.com/data-syndication/v1/channels/{channelId}

Retrieves a single channel.

Path Parameters

Responses

Retrieve the Status of a Channel

Example Request

require 'httparty'

HTTParty.get(
  'https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/channels/5fcdb1e1-3b82-4272-acfb-1242d456e4f4/status',
  headers: {
    'Accept' => 'application/json',
    'Authorization' => '<auth_header>'
  }
)

curl -X GET -H 'Authorization: {auth_header}' -H 'Accept: application/json'
'https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/channels/5fcdb1e1-3b82-4272-acfb-1242d456e4f4/status'

Example Response

{
  "status": "ACTIVE"
}

GET https://{tenantMnemonic}.api.{region}.healtheintent.com/data-syndication/v1/channels/{channelId}/status

Retrieves the status of a channel.

Path Parameters

Responses

Modify the Status of a Channel

Example Request

require 'httparty'
require 'json'

HTTParty.put(
  'https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/channels/5fcdb1e1-3b82-4272-acfb-1242d456e4f4/status',
  headers: {
    'Accept' => 'application/json',
    'Content-Type' => 'application/json',
    'Authorization' => '<auth_header>'
  },
  body: {
    status: 'ACTIVE'
  }.to_json
)

curl -X PUT -H 'Authorization: {auth_header}' -H 'Accept: application/json' -H 'Content-Type: application/json'
-d '{"status": "ACTIVE"}'
'https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/channels/5fcdb1e1-3b82-4272-acfb-1242d456e4f4/status'

Example Response

{
  "status": "ACTIVE"
}

PUT https://{tenantMnemonic}.api.{region}.healtheintent.com/data-syndication/v1/channels/{channelId}/status

Modifies the status of a channel.

Path Parameters

Parameters

Responses

Deliveries

Retrieve a List of Deliveries

Example Request

require 'httparty'

HTTParty.get(
  'https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/channels/5fcdb1e1-3b82-4272-acfb-1242d456e4f4/deliveries?bundleReleasedAfter=2018-02-03T01:00:00.000Z&orderBy=bundleReleasedAt',
  headers: {
    'Accept' => 'application/json',
    'Authorization' => '<auth_header>'
  }
)

curl -X GET -H 'Authorization: {auth_header}' -H 'Accept: application/json'
'https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/channels/5fcdb1e1-3b82-4272-acfb-1242d456e4f4/deliveries?bundleReleasedAfter=2018-02-03T01:00:00.000Z&orderBy=bundleReleasedAt'

Example Response

{
  "items": [
    {
      "id": "5e8af1e6-1cdf-45f6-9d9a-3c314beac597",
      "bundle": {
        "id": "5ebcac9e-1f1a-4181-8c0f-4300a3af83d9",
        "releasedAt": "2018-04-11T18:37:25.063Z"
      },
      "channel": {
        "id": "5fcdb1e1-3b82-4272-acfb-1242d456e4f4"
      },
      "status": "DELIVERED",
      "deliveredAt": "2018-04-12T16:02:01.333Z",
      "metadata": {
        "bytesSize": 1073741824,
        "archiveFormat": "TAR_GZ"
      }
    },
    {
      "id": "f9647569-aa13-42c2-81ad-a20b46be775c",
      "bundle": {
        "id": "8d75de0e-358b-434d-97fe-6f1ba3598098",
        "releasedAt": "2018-04-11T20:21:12.461Z"
      },
      "channel": {
        "id": "5fcdb1e1-3b82-4272-acfb-1242d456e4f4"
      },
      "status": "IN_PROGRESS"
    }
  ],
  "totalResults": 2,
  "firstLink": "https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/channels/5fcdb1e1-3b82-4272-acfb-1242d456e4f4/deliveries?bundleReleasedAfter=2018-02-03T01:00:00.000Z&orderBy=bundleReleasedAt&offset=0&limit=20",
  "lastLink": "https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/channels/5fcdb1e1-3b82-4272-acfb-1242d456e4f4/deliveries?bundleReleasedAfter=2018-02-03T01:00:00.000Z&orderBy=bundleReleasedAt&offset=0&limit=20"
}

GET https://{tenantMnemonic}.api.{region}.healtheintent.com/data-syndication/v1/channels/{channelId}/deliveries

Retrieves a list of deliveries matching the query.

If the channel corresponds to the DOWNLOAD channel type, this endpoint can be used to list available deliveries that you have not yet downloaded and processed into your application. If you store the releasedAt time of the last delivery that was downloaded, it can be used as the bundleReleasedAfter query parameter of this endpoint to list deliveries after this last downloaded bundle in time sequence order.

Note: The feed type for your channel may have certain processing order requirements that must be followed by API consumers to maintain data integrity. For example, feed types that produce bundles with incremental changes might require processing to strictly follow bundleReleasedAt order as new bundles may depend on previous bundles. See the documentation for your particular feed type for details.

Path Parameters

Query Parameters

Responses

Retrieve a Single Delivery

Example Request

require 'httparty'

HTTParty.get(
  'https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/deliveries/5e8af1e6-1cdf-45f6-9d9a-3c314beac597',
  headers: {
    'Accept' => 'application/json',
    'Authorization' => '<auth_header>'
  }
)

curl -X GET -H 'Authorization: {auth_header}' -H 'Accept: application/json'
'https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/deliveries/5e8af1e6-1cdf-45f6-9d9a-3c314beac597'

Example Response

{
  "id": "5e8af1e6-1cdf-45f6-9d9a-3c314beac597",
  "bundle": {
    "id": "5ebcac9e-1f1a-4181-8c0f-4300a3af83d9",
    "releasedAt": "2018-04-11T18:37:25.063Z"
  },
  "channel": {
    "id": "5fcdb1e1-3b82-4272-acfb-1242d456e4f4"
  },
  "status": "DELIVERED",
  "deliveredAt": "2018-04-12T16:02:01.333Z",
  "metadata": {
    "bytesSize": 1073741824,
    "archiveFormat": "TAR_GZ"
  }
}

GET https://{tenantMnemonic}.api.{region}.healtheintent.com/data-syndication/v1/deliveries/{deliveryId}

Retrieves a single delivery.

Path Parameters

Responses

Downloads

If you have a channel whose channel type mnemonic is DOWNLOAD, then each delivery in that channel with a DELIVERED status is available for download. Use the Deliveries endpoint to find what downloads are available to you; use this endpoint to download the content.

Note: Downloads are available for only three weeks. See the Data Retention section for more information.

Retrieve a Single Download

Example Request

require 'httparty'

response = HTTParty.get(
  'https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/downloads/5e8af1e6-1cdf-45f6-9d9a-3c314beac597',
  headers: {
    'Authorization' => '<auth_header>',
    'Accept' => 'application/octet-stream',
    'Range' => 'bytes=0-104857599'
  }
)


File.binwrite('bundle.tar.gz', response.body)

curl -X GET -H 'Authorization: {auth_header}' -H 'Range: bytes=0-104857599'
'https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/downloads/5e8af1e6-1cdf-45f6-9d9a-3c314beac597' > bundle.tar.gz

GET https://{tenantMnemonic}.api.{region}.healtheintent.com/data-syndication/v1/downloads/{deliveryId}

Retrieves the archive file containing the data from the bundle.

Note: To ensure no data was lost due to a failed connection, check that the downloaded file’s size is correct. If you requested a specific range using the Range header, check that the size matches what you requested. Otherwise, check that the size matches the Content-Length response header.

Path Parameters

Range Header

If a file download times out due to its size, you may optionally include a Range header to indicate that you only want to download a portion of the file. After downloading all portions of the file, you can concatenate the portions and decompress the combined file.

You can also use the Range header in order to download multiple segments of the file in parallel. To do this, you would start multiple threads or processes, each of which makes a request for a different byte range, then concatenate the portions after they have all been downloaded. There are diminishing returns for increasing the number of concurrent requests; we suggest downloading files in segments of about 600MB and retrieving 5-10 segments at a time.

For more information about byte ranges, see Byte Ranges on the RFC 7233 page on the Internet Engineering Task Force (IETF) website.

The range header should take one of the following forms:

• bytes=<start>-<end>, where <start> and <end> are non-negative integers specifying an inclusive range of byte indexes.
• bytes=<start>-, where <start> is a non-negative integer specifying that you want to receive all bytes from that index to the end of the file.
• bytes=-<length>, where <length> is a non-negative integer specifying that you want to receive the last <length> number of bytes in the file.

Although RFC 7233 defines a way to specify multiple ranges in a single request, the downloads endpoint does not currently support this.

See the download example request for an example of this header being set.

Data Syndication API Definitions

Bundle

Bundle List Response

Bundle Reference

Channel

Channel Configuration

The schema of this configuration object varies depending on the channel type. Each channel type can have a different set of configuration options.

Download Channel Type Configuration

S3 Channel Type Configuration

postChannel

When creating a channel, the channel type is determined by which config value is provided. If downloadConfig is provided, a DOWNLOAD channel is created. If s3Config is provided, an S3 channel is created. Exactly one of these config attributes must be provided.

New Download Channel Type Configuration

New S3 Channel Type Configuration

Channel Status

Channel List Response

Channel Reference

Delivery

Delivery Metadata

Download Channel Type Delivery Metadata

S3 Channel Type Delivery Metadata

Delivery List Response

Error

ErrorDetail

Feed

Feed List Response

Feed Reference

Feed Type Reference

Scope

Scope Part