Get data from a versioned layer
Note
Currently, the blob
service supports REST API versions v1
and v2
. Version v1
should be used to access versioned, index and stream (if the stream payload is larger than 1MB) layers. Version v2
should be used to access the object store layer. Always pick the proper API version from API Lookup to ensure you get back the correct API version response. For instructions, see the API Lookup Developer's Guide.
You can get data from a versioned layer using the REST APIs metadata
v1
(for metadata) and blob
v1
(for data).
The typical flow for getting data consists of the following steps.
- Obtain an authorization token
- Get API base URLs
- Get the data handle
- Get partition data
Obtain an authorization token
Obtain an authorization token for your HTTP requests. For instructions, see the Identity & Access Management Guide.
Get API base URLs
Use the API Lookup service to get the API endpoints for the metadata
v1
and blob
v1
APIs for the catalog you want to get data from. For instructions, see the API Lookup Developer's Guide.
Get the data handle
In order to get data from the blob
API, you must obtain the data handle of the partition that contains the data you want. To get the data handle, use the metadata
API.
GET /<Base path for the metadata API from the API Lookup Service>/layers/<Layer ID>/partitions?version=<Catalog Version> HTTP/1.1
Host: <Hostname for the metadata API from the API Lookup Service>
Authorization: Bearer <Authorization Token>
Content-Type: application/json
Cache-Control: no-cache
The response contains an array of partition metadata. For example:
{
"partitions": [
{
"dataHandle": "1b2ca68f-d4a0-4379-8120-cd025640510c",
"layer": "my-layer",
"partition": "314010583",
"partitionType": "reference",
"version": 0
}
]
}
Get partition data
Now that you have the partition metadata, search it to find the data handle for the partitions you want. Then, use the data handle to retrieve data using the blob
API:
GET /<Base path for the blob API from the API Lookup Service>/layers/<Layer ID>/data/<Data Handle> HTTP/1.1
Host: <Hostname for the blob API from the API Lookup Service>
Authorization: Bearer <Authorization Token>
Cache-Control: no-cache
The response consists of the binary data that was uploaded most recently to the given data handle.
Get partial partition data
To resume download of a large response when there is a connection issue between the client and server or to fetch a specific slice of the data, you can provide a Range
header as RFC 7233, for example Range: bytes=10-
.
GET /<Base path for the blob API from the API Lookup Service>/layers/<Layer ID>/data/<Data Handle> HTTP/1.1
Host: <Hostname for the blob API from the API Lookup Service>
Range: bytes=10-
Authorization: Bearer <Authorization Token>
Cache-Control: no-cache
The response includes only the byte slice you requested.
Note
We recommend that your application includes retry logic for handling HTTP 5xx errors. Use exponential backoff in the retry logic.