For similar capabilities to Amazon Timestream for LiveAnalytics, consider Amazon Timestream for InfluxDB. It offers simplified data ingestion and single-digit millisecond query response times for real-time analytics. Learn more [here](https://docs.aws.amazon.com//timestream/latest/developerguide/timestream-for-influxdb.html).

# Using the API
<a name="Using.API"></a>

 In addition to the [SDKs](getting-started-sdks.md), Amazon Timestream for LiveAnalytics provides direct REST API access via the *endpoint discovery pattern*. The endpoint discovery pattern is described below, along with its use cases. 

## The endpoint discovery pattern
<a name="Using-API.endpoint-discovery"></a>

Because Timestream Live Analytics's SDKs are designed to transparently work with the service's architecture, including the management and mapping of the service endpoints, it is recommended that you use the SDKs for most applications. However, there are a few instances where use of the Timestream for LiveAnalytics REST API endpoint discovery pattern is necessary: 
+ You are using [VPC endpoints (AWS PrivateLink) with Timestream for LiveAnalytics](VPCEndpoints.md)
+ Your application uses a programming language that does not yet have SDK support
+ You require better control over the client-side implementation

This section includes information on how the endpoint discovery pattern works, how to implement the endpoint discovery pattern, and usage notes. Select a topic below to learn more. 

**Topics**
+ [The endpoint discovery pattern](#Using-API.endpoint-discovery)
+ [How the endpoint discovery pattern works](Using-API.endpoint-discovery.how-it-works.md)
+ [Implementing the endpoint discovery pattern](Using-API.endpoint-discovery.describe-endpoints.implementation.md)

# How the endpoint discovery pattern works
<a name="Using-API.endpoint-discovery.how-it-works"></a>

 Timestream is built using a [cellular architecture ](architecture.md#cells) to ensure better scaling and traffic isolation properties. Because each customer account is mapped to a specific cell in a region, your application must use the correct cell-specific endpoints that your account has been mapped to. When using the SDKs, this mapping is transparently handled for you and you do not need to manage the cell-specific endpoints. However, when directly accessing the REST API, you will need to manage and map the correct endpoints yourself. This process, the *endpoint discovery pattern*, is described below: 

1.  The endpoint discovery pattern starts with a call to the `DescribeEndpoints` action (described in the [https://docs.aws.amazon.com/timestream/latest/developerguide/API_Reference.html](https://docs.aws.amazon.com/timestream/latest/developerguide/API_Reference.html) section). 

1.  The endpoint should be cached and reused for the amount of time specified by the returned time-to-live (TTL) value (the [https://docs.aws.amazon.com/timestream/latest/developerguide/API_Endpoint.html#timestream-Type-Endpoint-CachePeriodInMinutes.html](https://docs.aws.amazon.com/timestream/latest/developerguide/API_Endpoint.html#timestream-Type-Endpoint-CachePeriodInMinutes.html)). Calls to the Timestream Live Analytics API can then be made for the duration of the TTL. 

1.  After the TTL expires, a new call to DescribeEndpoints should be made to refresh the endpoint (in other words, start over at Step 1). 

**Note**  
 Syntax, parameters and other usage information for the `DescribeEndpoints` action are described in the [API Reference](https://docs.aws.amazon.com/timestream/latest/developerguide/API_DescribeEndpoints.html). Note that the `DescribeEndpoints` action is available via both SDKs, and is identical for each. 

For implementation of the endpoint discovery pattern, see [Implementing the endpoint discovery pattern](Using-API.endpoint-discovery.describe-endpoints.implementation.md).

# Implementing the endpoint discovery pattern
<a name="Using-API.endpoint-discovery.describe-endpoints.implementation"></a>

 To implement the endpoint discovery pattern, choose an API (Write or Query), create a **DescribeEndpoints** request, and use the returned endpoint(s) for the duration of the returned TTL value(s). The implementation procedure is described below. 

**Note**  
Ensure you are familiar with the [usage notes](#Using-API.endpoint-discovery.describe-endpoints.usage-notes).

## Implementation procedure
<a name="Using-API.endpoint-discovery.describe-endpoints.implementation.procedure"></a>

1.  Acquire the endpoint for the API you would like to make calls against ([Write](https://docs.aws.amazon.com/timestream/latest/developerguide/API_Operations_Amazon_Timestream_Write.html) or [Query](https://docs.aws.amazon.com/timestream/latest/developerguide/API_Operations_Amazon_Timestream_Query.html)). using the [https://docs.aws.amazon.com/timestream/latest/developerguide/API_DescribeEndpoints.html](https://docs.aws.amazon.com/timestream/latest/developerguide/API_DescribeEndpoints.html) request. 

   1.  Create a request for [https://docs.aws.amazon.com/timestream/latest/developerguide/API_DescribeEndpoints.html](https://docs.aws.amazon.com/timestream/latest/developerguide/API_DescribeEndpoints.html) that corresponds to the API of interest ([Write](https://docs.aws.amazon.com/timestream/latest/developerguide/API_Operations_Amazon_Timestream_Write.html) or [Query](https://docs.aws.amazon.com/timestream/latest/developerguide/API_Operations_Amazon_Timestream_Query.html)) using one of the two endpoints described below. There are no input parameters for the request. Ensure that you read the notes below.   
*Write SDK:*  

      ```
      ingest.timestream.<region>.amazonaws.com
      ```  
*Query SDK:*  

      ```
      query.timestream.<region>.amazonaws.com
      ```

      An example CLI call for region `us-east-1` follows.

      ```
      REGION_ENDPOINT="https://query.timestream.us-east-1.amazonaws.com"
      REGION=us-east-1
      aws timestream-write describe-endpoints \
      --endpoint-url $REGION_ENDPOINT \
      --region $REGION
      ```
**Note**  
 The HTTP "Host" header *must* also contain the API endpoint. The request will fail if the header is not populated. This is a standard requirement for all HTTP/1.1 requests. If you use an HTTP library supporting 1.1 or later, the HTTP library should automatically populate the header for you.
**Note**  
Substitute *<region>* with the region identifier for the region the request is being made in, e.g. `us-east-1`

   1. Parse the response to extract the endpoint(s), and cache TTL value(s). The response is an array of one or more [`Endpoint` objects ](https://docs.aws.amazon.com/timestream/latest/developerguide/API_Endpoint.html). Each `Endpoint` object contains an endpoint address (`Address`) and the TTL for that endpoint (`CachePeriodInMinutes`). 

1.  Cache the endpoint for up to the specified TTL. 

1.  When the TTL expires, retrieve a new endpoint by starting over at step 1 of the Implementation. 

## Usage notes for the endpoint discovery pattern
<a name="Using-API.endpoint-discovery.describe-endpoints.usage-notes"></a>
+ The **DescribeEndpoints** action is the only action that Timestream Live Analytics regional endpoints recognize. 
+ The response contains a list of endpoints to make Timestream Live Analytics API calls against. 
+  On successful response, there should be at least one endpoint in the list. If there is more than one endpoint in the list, any of them are equally usable for the API calls, and the caller may choose the endpoint to use at random. 
+ In addition to the DNS address of the endpoint, each endpoint in the list will specify a time to live (TTL) that is allowable for using the endpoint specified in minutes.
+ The endpoint should be cached and reused for the amount of time specified by the returned TTL value (in minutes). After the TTL expires a new call to **DescribeEndpoints** should be made to refresh the endpoint to use, as the endpoint will no longer work after the TTL has expired.