Integrating Amazon Health with other systems using the Amazon Health API - Amazon Health
Signing Amazon Health API requestsChoosing endpoints for Amazon Health API requests
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Integrating Amazon Health with other systems using the Amazon Health API

Amazon Health is a RESTful web service that uses HTTPS as a transport and JSON as a message serialization format. Your application code can make requests directly to the Amazon Health API. When you use the REST API directly, you must write the necessary code to sign and authenticate your requests. For more information about the Amazon Health operations and parameters, see the Amazon Health API Reference.

Note

You must have a Business, Enterprise On-Ramp, or Enterprise Support plan from Amazon Web Services Support to use the Amazon Health API. If you call the Amazon Health API from an Amazon account that doesn't have a Business, Enterprise On-Ramp, or Enterprise Support plan, you receive a SubscriptionRequiredException error.

You can use the Amazon SDKs to wrap the Amazon Health REST API calls, which can simplify your application development. You specify your Amazon credentials, and these libraries take care of authentication and request signing for you.

Amazon Health also provides a Amazon Health Dashboard in the Amazon Web Services Management Console that you can use to view and search for events and affected entities. See Getting started with your Amazon Health Dashboard.

Topics

Signing Amazon Health API requests

When you use the Amazon SDKs or the Amazon Command Line Interface (Amazon CLI) to make requests to Amazon, these tools automatically sign the requests for you with the access key that you specify when you configure the tools. For example, if you use the Amazon SDK for Java for the previous high availability endpoint demo, you don't need to sign requests yourself.

Java code examples

For more examples on how to use the Amazon Health API with the Amazon SDK for Java, see this example code.

When you make requests, we strongly recommend that you don't use your Amazon root account credentials for regular access to Amazon Health. You can use the credentials for an IAM user. For more information, see Lock Away Your Amazon Account Root User Access Keys in the IAM User Guide.

If you don’t use the Amazon SDKs or the Amazon CLI, then you must sign your requests yourself. We recommend that you use Amazon Signature Version 4. For more information, see Signing Amazon API Requests in the Amazon Web Services General Reference.

Choosing endpoints for Amazon Health API requests

The Amazon Health API follows a multi-Region application architecture multi-Region application architecture and has two regional endpoints in an active-passive configuration. To support active-passive DNS failover, Amazon Health provides a single, global endpoint. You can perform a DNS lookup on the global endpoint to determine the active endpoint and corresponding signing Amazon Region. This helps you know which endpoint to use in your code, so that you can get the latest information from Amazon Health.

When you make a request to the global endpoint, you must specify your Amazon access credentials to the regional endpoint that you target and configure the signing for your Region. Otherwise, your authentication might fail. For more information, see Signing Amazon Health API requests.

For IPv6-only requests, we recommend performing a DNS lookup on the global endpoint to determine the active Amazon Web Services Region and then calling the IPv6 supported dual-stack endpoint for that Region.

The following table represents the default configuration.

Description Signing Region Endpoint Protocol
Active

cn-northwest-1

health.cn-northwest-1.amazonaws.com.cn

 HTTPS
Passive

cn-north-1

health.cn-north-1.amazonaws.com.cn

 HTTPS
Global

cn-northwest-1

Note

This is the signing Region of the current active endpoint.

global.health.amazonaws.com.cn

HTTPS

To determine if an endpoint is the active endpoint, do a DNS lookup on the global endpoint CNAME, and then extract the Amazon Region from the resolved name.

Example : DNS lookup on global endpoint

The following command completes a DNS lookup on the global.health.amazonaws.com.cn endpoint. The command then returns the cn-northwest-1 Region endpoint. This output tells you which endpoint you should use for Amazon Health.

dig global.health.amazonaws.com.cn  | grep CNAME
global.health.amazonaws.com.cn. 10 IN CNAME health.cn-northwest-1.amazonaws.com.cn
Tip

Both the active and passive endpoints return Amazon Health data. However, the latest Amazon Health data is only available from the active endpoint. Data from the passive endpoint will be eventually consistent with the active endpoint. We recommend that you restart any workflows when the active endpoint changes.