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 - Attachment Uploads API

by Technical Evangelist ‎11-15-2016 02:06 PM - edited ‎11-15-2016 02:24 PM (791 Views)
Labels:

Foundation - Attachment Uploads API

Provides upload operations to upload files that are meant to be associated with an existing catalog item as attachments.

 

Overview

The process used to perform an attachment upload is very similar to that of the Foundation Upload API. Like the Foundation Upload API, the Attachment Upload provides various endpoints for initiating aatchment upload jobs, uploading client files to be used as attachments, retreiving status a running job, canceling a running job, and deleting an attachment upload job. The details of how to perform each of these operations is in their descriptions below. If you are trying to use this API for the first time please start with the "Initiate an attachment upload" section and following the instructions thereafter.

 

Request all running attachment uploads

Returns a json array of objects, each with detailed information about an attachement upload job that is currently processing.

 

Request Endpoint:
GET https://mapp.hexagongeospatial.com/api/v1/attachmentuploads

 

Successful Response:
HTTP Status Code Description
200 Successfully retrieved all running uploads

 

Successfull Response Payload:
[
  {
    "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
500 Unexpected error while processing the request

 

 

Initiate an attachment upload

Initites the upload process by creating an attachment upload job, and providing an attachmentUploadId that will be used to perform all following operations on this job and the files included.

 

Registration of parameters

To initiate an attachment upload, users will need to send an HTTP post request to the specified endpoint, your request will also need to contain a JSON payload containing the proper parameters. Information about the available parameters and an example payload are below.

 

Request Endpoint:
POST https://mapp.hexagongeospatial.com/api/v1/attachmentuploads

 

Request Parameters:
Title Required Type Values Description
parentId true  String  Any valid catalog item id Catalog item id of the item we want the files attached.
uploadStoreType  true  String 
  • S3(Preferred)
  • Direct
  • ActiveStore 

This property is used to specify how the user is going to upload the attachment files.

  • S3 - This is the preffered method of upload because it can be done without restrictions. If you specify this method you will need to upload the files directly to s3 using the information in the "s3Properties" object of the response.
  • Direct - This method requires users to upload files to another Foundation endpoint, please see the "Upload client files" section to handle uploading files using this method.
  • ActiveStore - This method is reserved for internal services with access to our active storage location. Using this method users will need to copy their attachment files to the active storage location provided in the "activeStoreProperties" object of the response.

 

Request Payload:
{
  "parentId": "e18b0308-47c3-42ef-a9a9-fabf56ceda19_2c91808355e0c2b5015628b3ed3662b5",
  "uploadStoreType": "Direct"
}
 
Successful Response:
HTTP Status Code Description
201 Successully started an upload

 

Successfully Response Payload:

{
  "activeStorageProperties": {
    "activeStoragePath": "string"
  },
  "addedAttachmentIds": {},
  "displayableStatus": "string",
  "endTime": "string",
  "errors": "string",
  "id": "string",
  "parentId": "string",
  "progress": "string",
  "registerAttachmentsProperties": {
    "parentId": "string",
    "uploadStoreType": "Direct"
  },
  "s3Properties": {
    "accessKeyId": "string",
    "bucket": "string",
    "encodedPolicy": "string",
    "keyPrefix": "string",
    "signature": "string"
  },
  "startTime": "string",
  "state": "WAITING",
  "uploadComplete": true,
  "uploadedFiles": [
    "string"
  ]
}

 

If you have received a successful response, please capture the response location header. Here we have supplied you with the attachmentUploads job URL. This URL can be used to request information about your upload in the future. Also, make note of the {id} property in your response payload. This is identifier that will be used to reference this job, this property will need to be used anywhere we specifiy {attachmentUploadId}.

 

Error Response:
HTTP Status Code Description
400 Error with details in the response body.
401 Error, not authorized to access the catalog
403 Error, forbidden to access the item
500 Unexpected Error while processing the request

 

Next Steps

After receiving a successful response, users will need to upload the files to proper location. If you chose to upload you files directly, please see the "Upload client files" section for instructions. If you chose to upload your files via S3 or Active storage, please the information in the response to upload your files to the proper locations. After uploading your files, please see the "Complete attachment upload" section for instructions on finializing your upload.

 

 

Upload client files

Handles the process of uploading client attachment files when the "Direct" upload method is used.

 

For each attachment file please perform an HTTP Post request to the endpoint below. Your request will need to contain your file uploaded with a content type of multipart/formdata. 

 

Request Endpoint:
POST https://mapp.hexagongeospatial.com/api/v1/attachmentuploads/{attachmentUploadId}/files

 

Request Parameters:
Title Required Type Values Description
attachmentUploadId true QueryString Any valid attachmentUpload id Id for the attachment upload job we want to upload the files to. This is necessary so that the files correspond to the correct attachment upload job.

 

Successful Response:
HTTP Status Code Description Payload
201 Successfully uploaded client file There is no payload for this response

 

Error Response:
HTTP 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

 

Next Steps

After you have successfully uploaded all of your attachment files, please see the "Complete attachment upload" section to finalize your upload.

 

 

Complete attachment upload

Triggers completion of all client file uploads for the given attachment uploads job. Once this is done processing of the files will commence.

 

After successfully uploading your attachment files to your desired location, please make an HTTP put request to the following endpoint.

 

Request Endpoint:
PUT https://mapp.hexagongeospatial.com/api/v1/attachmentuploads/{attachmentUploadId}/complete

 

Request Parameters:

Title Required Type Values Description
attachmentUploadId true QueryString Any valid attachmentUpload id Id for the attachmentUpload job

 

Successful Response:
HTTP Status Code Description Payload
201 Successfully received client upload completion request. There is no payload for this request.

 

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

 

 

Request status of running attachment upload

Provides all available information for the given attachment upload.

 
Request Endpoint:
GET https://mapp.hexagongeospatial.com/api/v1/attachmentuploads/{attachmentUploadId}

 

Request Parameters:
Title Required Type Values Description
attachmentUploadId true QueryString Any valid attachmentUpload id Id for the attachmentUpload job

 

Successful Response:
HTTP Status Code Description
200 Successfully retrieved status for upload

 

Successful Response Payload:

{
  "activeStorageProperties": {
    "activeStoragePath": "string"
  },
  "addedAttachmentIds": {},
  "displayableStatus": "string",
  "endTime": "string",
  "errors": "string",
  "id": "string",
  "parentId": "string",
  "progress": "string",
  "registerAttachmentsProperties": {
    "parentId": "string",
    "uploadStoreType": "Direct"
  },
  "s3Properties": {
    "accessKeyId": "string",
    "bucket": "string",
    "encodedPolicy": "string",
    "keyPrefix": "string",
    "signature": "string"
  },
  "startTime": "string",
  "state": "WAITING",
  "uploadComplete": true,
  "uploadedFiles": [
    "string"
  ]
}

 

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 attachment upload

Immediately stops all effort of uploading files for the specified attachment upload job.

 
Request Endpoint:
PUT https://mapp.hexagongeospatial.com/api/v1/attachmentuploads/{attachmentUploadId}/cancel

 

Request Parameters:
Title Required Type Values Description
attachmentUploadId true QueryString Any valid attachmentUpload id Id for the attachmentUpload job

 

Successful Response:
HTTP Status Code Description Payload
202 Successfully canceled the specified attachment upload There is no payload for this response

 

Error Response:
HTTP Status Code Description
400 Error with details in the response body.
401 Error, not authorized to access the catalog
403 Error, forbidden to access the item
500 Unexpected error while processing the request

 

 

Delete an existing attachment upload

Deletes the attachment upload job for the given id. 

 
Request Endpoint:
DELETE https://mapp.hexagongeospatial.com/api/v1/attachmentuploads/{attachmentUploadId}

 

Request Parameters:
Title Required Type Values Description
attachmentUploadId true QueryString Any valid attachmentUpload id Id for the attachmentUpload job

 

Successful Response:
HTTP Status Code Description Payload
204 Successfully deleted an existing attachment upload There is no payload for this response

 

Error Response:
HTTP Status Code Description
400 Error with details in the response body
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
Users online (277)