Provides upload operations to upload files that are meant to be associated with an existing catalog item as attachments.
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.
Returns a json array of objects, each with detailed information about an attachement upload job that is currently processing.
GET https://mapp.hexagongeospatial.com/api/v1/attachmentuploads
HTTP Status Code | Description |
200 | Successfully retrieved all running uploads |
[ { "id": "", "displayableStatus": "COMPLETE", "progress": "100", "state": "COMPLETE", "startTime": "2016-9-14T15:28:17Z", "endTime": "" }, ... ]
HTTP Status Code | Description |
401 | Error, not authorized to access the catalog |
500 | Unexpected error while processing the request |
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.
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.
POST https://mapp.hexagongeospatial.com/api/v1/attachmentuploads
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 |
|
This property is used to specify how the user is going to upload the attachment files.
|
{
"parentId": "e18b0308-47c3-42ef-a9a9-fabf56ceda19_2c91808355e0c2b5015628b3ed3662b5",
"uploadStoreType": "Direct"
}
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}.
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 |
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.
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.
POST https://mapp.hexagongeospatial.com/api/v1/attachmentuploads/{attachmentUploadId}/files
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. |
HTTP Status Code | Description | Payload |
201 | Successfully uploaded client file | There is no payload for this 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 |
After you have successfully uploaded all of your attachment files, please see the "Complete attachment upload" section to finalize your 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.
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 |
HTTP Status Code | Description | Payload |
201 | Successfully received client upload completion request. | There is no payload for this request. |
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 |
Provides all available information for the given attachment upload.
GET https://mapp.hexagongeospatial.com/api/v1/attachmentuploads/{attachmentUploadId}
Title | Required | Type | Values | Description |
attachmentUploadId | true | QueryString | Any valid attachmentUpload id | Id for the attachmentUpload job |
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" ] }
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 |
Immediately stops all effort of uploading files for the specified attachment upload job.
PUT https://mapp.hexagongeospatial.com/api/v1/attachmentuploads/{attachmentUploadId}/cancel
Title | Required | Type | Values | Description |
attachmentUploadId | true | QueryString | Any valid attachmentUpload id | Id for the attachmentUpload job |
HTTP Status Code | Description | Payload |
202 | Successfully canceled the specified attachment upload | There is no payload for this 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 |
Deletes the attachment upload job for the given id.
DELETE https://mapp.hexagongeospatial.com/api/v1/attachmentuploads/{attachmentUploadId}
Title | Required | Type | Values | Description |
attachmentUploadId | true | QueryString | Any valid attachmentUpload id | Id for the attachmentUpload job |
HTTP Status Code | Description | Payload |
204 | Successfully deleted an existing attachment upload | There is no payload for this 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 |