Hexagon Geospatial

API

Turn on suggestions Auto-suggest helps you quickly narrow down your search results by suggesting possible matches as you type.
Auto-suggest helps you quickly narrow down your search results by suggesting possible matches as you type.
Showing results for 
Search instead for 
Do you mean 

Foundation - Download API

by Technical Evangelist on ‎11-09-2016 12:15 PM (466 Views)

Foundation - Download API

Provides download operations of geospatial datasets to client machines. This involves packaging all supplemental files that make up the dataset into a ZIP based on the download.

 

Note: Before attempting to make request to our Foundation API, please ensure you are properly authenticated. For instructions on the authentication process, please see the Foundation - Authentication API article. 

 

Request all running downloads

A successful request to this endpoint will return a JSON array of objects. Each object will contain information about a specific download that is current processing.

 

Request Endpoint:
GET /api/v1/downloads

 

Successful Response:
HTTP Status Code Description Payload
200 Successfully retrieved all running downloads 
[
  {
    "id": "",
    "displayableStatus": "COMPLETE",
    "progress": "100",
    "state": "COMPLETE",
    "startTime": "2016-9-14T15:28:17Z",
    "endTime": ""
  },
  ...
]

 

Error Response:
HTTP Status Code Description
401 Error, not authorized to access the catalog.
403 Error, forbidden to access the item.
404 Error, item not found.
500 Unexpected error while processing the request.

 

 

Initiate dataset download

This request will initiate the packaging of every catalog item that corresponds to an id included. When status is complete, the location of the packaged ZIP file will be in the response location header.

 

Downloading datasets using the Download API is a three-step process. This process begins with the user initiating a download request. The second, optional step, is to request the status of the download.  Finally, the third step is to download the packaged ZIP file. The HTTP request method must be a POST, and the following endpoint is used will make the request:

 

Request Endpoint:
POST /api/v1/downloads

 

The user must include a JSON payload to be sent with the request. This payload will contain a JSON string array with the catalog id of each catalog item the user wants to download. With this structure the user can create an array with as many ids as necessary, meaning a single download job can handle downloading multiple catalog items. The request payload should follow the structure below: 

 

Sample Request Payload:
[
    "id1",
    "id2",
    ...
]

 

Successful Response:
HTTP Status Code Description Payload
201 This indicates that your download request has been accepted, and that your download job has started. 
{
    "id": "download-1553c2bv-42dp-4841-82e3-2e2163369165",
    "displayableStatus": "WAITING",
    "progress": "15",
    "state": "WAITING",
    "startTime": "2016-10-19T18:17:50Z",
    "endTime": "",
    "datasetIds": [
        "e18b0308-47c3-42ef-a9a9-fabf56ceda19_2c918083566d176f015671de5379742f",
        "e18b0308-47c3-42ef-a9a9-fabf56ceda19_2c918083566d176f015671de60847447"
    ],
    "downloadURI": null
}

 

Error Responses:
HTTP Status Code Description
401 Error, not authorized to access the catalog
403 Error, forbidden to access the item
404 Error, item not found
500 Unexpected Error while processing the request

 

 

Request status of a running download.

This endpoint will return all information about a specific download job.

 

While a download job is running, a user can check the status of this job. This is done by using the downloadId (returned in the HTTP response of the initial request) to make another request to the following endpoint:

 

Request Endpoint:
GET /api/v1/downloads/{downloadId}

 

Request Parameters:
Title Required Type Values Description
downloadId true QueryString Parameter Any valid download job id Id of the download job.

 

Note: When a download is started in M.App Chest, M.App Chest uses this endpoint to update the user about the status of the running download job. When the job is complete, M.App Chest updates the user of the completion and enables the option to download the resulting ZIP file. 

 

Successful Response:
HTTP Status Code Description Payload
200 Successfully retrieved the status of the requested download job. 
{
    "id": "download-1553c2bv-42dp-4841-82e3-2e2163369165",
    "displayableStatus": "COMPLETE",
    "progress": "100",
    "state": "COMPLETE",
    "startTime": "2016-10-19T18:17:50Z",
    "endTime": "2016-10-19T18:17:55Z",
    "datasetIds": [
        "e18b0308-47c3-42ef-a9a9-fabf56ceda19_2c918083566d176f015671de5379742f",
        "e18b0308-47c3-42ef-a9a9-fabf56ceda19_2c918083566d176f015671de60847447"
    ],
    "downloadURI": null
}

 

Error Response:
HTTP Status Code Description
401 Error, not authorized to access the catalog
403 Error, forbidden to access the item
404 Error, item not found
500 Unexpected error while processing the request

 

Request the zip file containing datasets.

When the creation of the ZIP file is complete, the user should initiate this request using the original download id.

 

When the download job is complete, users must make a final request to the following endpoint to actually download the ZIP file:

 

Request Endpoint:
GET /api/v1/downloads/{downloadId}/zip

 

Request Parameters:
Title Required Type Values Description
downloadId true QueryString Parameter Any valid download job id Id of the job responsible for packaging catalog items

 

This endpoint will contain the resulting ZIP file from the download job. When users make a request from the endpoint above the browser should handle the rest with its default download workflow.

 

Successful Response:
HTTP Status Code Description Payload
200 Successful request made to this endpoint will also provide the user with additional download information. The JSON payload will match the sample payload. 
{
  "description": "string",
  "filename": "string",
  "inputStream": {},
  "open": true,
  "outputStream": {},
  "path": "string",
  "readable": true,
  "writable": true
}

 

Error Response:
HTTP Status Code Description
401 Error, not authorized to access the catalog
403 Error, forbidden to access the item
404 Error, item not found
500 Unexpected error while processing the request

 

Cancel a running download.

Uses the given download id to stop all effort on completing the corresponding job.

 

Request Endpoint:
PUT /api/v1/downloads/{downloadId}/cancel

 

Request Parameters:
Title Required Type Values Description
downloadId true QueryString Parameter Any valid download job id Id of the download job responsible for packaging catalog items

 

Successful Response:
HTTP Status Code Description Payload
202 Successfully canceled this download job There is no payload for this response.

Error Response:
HTTP Status Code Description Payload
401 Error, not authorized to access the catalog There is no payload for this response.
403 Error, forbidden to access the item
500 Unexpected error while processing the request

 

Delete an existing download.

Uses the given download id to delete an existing download.

 

Request Endpoint:
DELETE /api/v1/downloads/{downloadId}

 

Request Parameters:
Title Required Type Values Description
downloadId true QueryString Parameter Any valid download job id Id of the download job responsible for packaging catalog items

 

Successful Response:
HTTP Status Code Description Payload
204 Successfully deleted the download content from the download location. There is no payload for this response.

Error Response:
HTTP Status Code Description Payload
400 Error with details in the response body There is no payload for this response.
401 Error, not authorized to access the catalog
403 Error, forbidden to access the item
404 Error, item not found
500 Unexpected error while processing the request

 

Rate this article:
0 HexPoints
Did you find this article helpful? Yes No
Contributors