Upload API

Required permissions

Upload requests require the following:

• If non-interactive application authorization is used, then the client can upload assets to any location where upload is supported.
• If the client is impersonating a specific user then that user must have upload permission on the upload location.

Note:  The maximum file size for upload is 25 GB.

Upload procedure

An asset is uploaded using the following 4 step process:

POST /fotoweb/api/uploads/

POST /fotoweb/api/uploads/<UPLOAD_ID>/chunks/<CHUNK_INDEX>

POST /fotoweb/api/uploads/<UPLOAD_ID>/xmp

GET /fotoweb/api/uploads/<UPLOAD_ID>/status

1. Send initial upload request

The initial upload request begins the process for uploading a single asset by setting up an upload task with a unique Upload ID which is used in all following API requests. The Upload ID is not a credential, and the API requests still use the regular authentication and permission checking, which means each user can only access their own uploads.

Metadata can be specified in this step.

The destination parameter of the initial upload request determines where the asset will be uploaded to. To upload a new asset to an archive, set the destinationto the URL of the collection. For On-Premises systems, it is possible to upload an asset to the Upload Area by setting the destination to null.

Metadata fields can be overwritten, extended, or deleted using metadata patch instructions in the metadata parameter. Metadata patch instructions are applied relative to the existing XMP metadata in the uploaded asset. 

Metadata of the uploaded asset is applied as follows:

• If an XMP sidecar file is uploaded, then the metadata in the XMP sidecar file is used. Any embedded metadata in the asset file itself is ignored.
• Otherwise, embedded XMP metadata in the asset file is used, if present (and if the file format supports it).
• Finally, metadata patch instructions, provided in the metadata attribute of the initial upload request, are applied relative to the provided XMP metadata. See the section about applying metadata for details.

POST /fotoweb/api/uploads/
Content-Type: application/json
Accept: application/json

{
  "destination": "/fotoweb/archives/5000/DocFolder/SubFolder/",
  "folder": "NewFolder1/NewSubFolder2/" | null
  "filename": "image.jpeg" | null 
  "hasXmp": true | false,
  "fileSize": 3145728,
  "checkoutId": "..." | null,
  "metadata": {
    fields: [...],
    attributes: [...]
    } | null
    "comment": "..." | null
}

{
  ...
  "metadata": {
    "fields": [
     {"id": 5, "value": "Roadrunner"},
     {"id": 80, "value": "Wyle E. Coyote", "action": "add"},
     {"id": 25, "action": "erase"},
     {"id": 25, "action": "add", "value": ["chicken", "food"]}
    ]
  }
  ...
}

// If the field is a non-bag field:
"value": "foo"           // Replaces existing value with "foo"
"value": ["foo"]         // Replaces existing value with "foo"
"value": []              // valid, but does nothing
"value": ["foo", "bar"]  // INVALID, because at most one value may be given

// If the field is a bag field:
"value": "foo"           // Adds "foo" to existing values
"value": ["foo"]         // Adds "foo" to existing values
"value": ["foo", "bar"]  // Adds "foo" and "bar" to existing values
"value": []              // valid, but does nothing

{
  "fields": [
    {"id": 500, "value": "V1"},
    {"id": 501, "action": "erase"},
    {"id": 502, "action": "append", "value": "V3"},
    {"id": 503, "action": "prepend", "value": "V4"}
  ]
}

{
  "fields": [
    {"id": 25, "action": "erase"},
    {"id": 25, "action": "add", "value": ["food", "chicken"]},
    {"id": 80, "action": "add", "value": "Wyle E. Coyote"}
  ]
}

{
  ...
  "metadata": {
    "attributes": [
     {"key": "mt", "value": "2022-12-24T11:22:33Z"}
    ]
  }
  ...
}

{
  "destination": "/fotoweb/archives/5000/",
  "filename": "sunset.jpg"
  "hasXmp": false,
  "fileSize": 895841,
  "checkoutId": null,
  "metadata": {    
    "attributes": [
     {"key": "mt", "value": "2022-02-10T14:22:33Z"}
    ]
  }  
  "comment": null
}

{
  "destination": "/fotoweb/archives/5000/DocFolder/SubFolder/",
  "folder": "NewFolder1/NewSubFolder2/"
  "filename": "roadrunnervideo.mp4"
  "hasXmp": false,
  "fileSize": 5368709120,
  "checkoutId": null,
  "metadata": {
    "fields": [
     {"id": 5, "value": "Roadrunner"},
     {"id": 80, "value": "Wyle E. Coyote", "action": "add"},
     {"id": 25, "action": "erase"},
     {"id": 25, "action": "add", "value": ["chicken", "food"]}
    ],
    "attributes": [
     {"key": "mt", "value": "2022-12-24T11:22:33Z"}
    ]
  }  
  "comment": null
}

200 OK
Content-Type: application/json

{
  "id": "<UPLOAD_ID>",
  "chunkSize": 4194304,
  "numChunks": 1280,
  "hasXmp": false
}

400 Bad Request

{
    "value": "<VALUE>",
    "heading": "...",
    "description": "...",
    "technicalInfo": "..."
}

403 Forbidden

2. Send file data

Using the information from the initial upload response begin uploading the file in "chunks".

Chunking

The chunk size is returned in the response to the initial upload request. The number of chunks of a file depends only on the file size:

numChunks = ceil(fileSize / chunkSize)

Chunk indexes are zero-based so the first chunk to upload will have <CHUNK_INDEX> = 0.

Chunks can be uploaded in any order, even in parallel. The client application will need to keep track of which chunks have been successfully received by the server or have failed and need to be retried. The server will return 204 No Content when a chunk has been successfully received. Truncated upload requests are rejected.

Clients may retry uploading the same chunk after a request timeout. If a chunk has already been received successfully, then a request to upload it again will fail with 409 Conflict with no other side effects.  If any number of multiple upload requests of the same chunks are made simultaneously, then at most one of them may return  204 No Content  (and its content will be used). All others should fail with  409 Conflictif no other error occurs. In this case, it is unspecified which request will succeed. This means that it is safe to retry upload requests, even when it is unknown if the server has received a previous attempted request, as long as all requests to upload the same chunk have an identical payload.

Once all the chunks have been successfully received, the upload is finalized on the server by creating an upload background task to merge the chunks into a single file. Uploading chunks after an upload is finalized results in a 409 Conflict error but has no other side effects and the upload background task will continue.

If an upload is not finalized, and no more chunks have been received for a certain amount of time, then the upload has expired. All future attempts to upload with the same <UPLOAD_ID> will result in response 404 Not Found.
 

HTTP Multipart requests

Upload uses HTTP Multipart requests, as defined in RFC1341 (external link).

Note: You usually do not need to implement RFC1341 yourself. Most likely, the HTTP client library of your programming platform, which you use for sending HTTP requests, has built-in support for HTTP multipart requests. This is the standard format for uploading files, so check if your HTTP client library has functions for attaching files to requests.

All line breaks must be CR+LF. For more information, see RFC 7578 (external link).

POST /fotoweb/api/uploads/<UPLOAD_ID>/chunks/<CHUNK_INDEX>
Content-Type: multipart/form-data;boundary=<RANDOM_BOUNDARY>

--<RANDOM_BOUNDARY>
Content-Disposition: form-data;name="chunk";filename="chunk"
Content-Type: application/octet-stream

<BINARY_CHUNK_DATA>

--<RANDOM_BOUNDARY>--

POST /fotoweb/api/uploads/<UPLOAD_ID>/chunks/<CHUNK_INDEX>
Content-Type: multipart/form-data; boundary=WUG7zDvyA3hVq16Q

--WUG7zDvyA3hVq16Q
Content-Disposition: form-data;name="chunk";filename="chunk"
Content-Type: application/octet-stream
 
<BINARY_CHUNK_DATA>
--WUG7zDvyA3hVq16Q--

204 No Content

404 Not Found

415 Unsupported Media Type

400 Bad Request

{
    "value": "<VALUE>",
    "heading": "...",
    "description": "...",
    "technicalInfo": "..."
}

409 Conflict

{
    "value": "<VALUE>",
    "heading": "...",
    "description": "...",
    "technicalInfo": "..."
}

3. Send XMP sidecar file (optional)

This step is only necessary if the original file has metadata stored in an XMP sidecar file. If the original file does not have an XMP sidecar file, this step can be skipped.

This is an optional request to upload an XMP sidecar file that contains the metadata of the asset file. If the asset has an XMP sidecar file, then the initial upload request must declare it usinghasXmpis true. The XMP sidecar file can then be uploaded in one go using the following request, and the upload will be finalized once the server has received all the chunks and the XMP sidecar file.

POST /fotoweb/api/uploads/<UPLOAD_ID>/xmp
Content-Type: multipart/form-data;boundary=<RANDOM_BOUNDARY>

--<RANDOM_BOUNDARY>
Content-Disposition: form-data;name="xmp";filename="xmp"
Content-Type: application/octet-stream

<XMP_DATA>

--<RANDOM_BOUNDARY>--

HTTP Multipart requests

Upload uses HTTP Multipart requests, as defined in RFC1341 (external link).

Note: You usually do not need to implement RFC1341 by yourself. Most likely, the HTTP client library of your programming platform which you use for sending HTTP requests has built-in support for HTTP multipart requests. This is the standard format for uploading files, so check if your HTTP client library has functions for attaching files to requests.

All line-breaks must be CR+LF. For more information, see RFC 7578 (external link).

204 No Content

404 Not Found

415 Unsupported Media Type

400 Bad Request

{
    "value": "<VALUE>",
    "heading": "...",
    "description": "...",
    "technicalInfo": "..."
}

409 Conflict

{
    "value": "<VALUE>",
    "heading": "...",
    "description": "...",
    "technicalInfo": "..."
}

4. Poll status for completion

This request is made to poll the status of the upload.

GET /fotoweb/api/uploads/<UPLOAD_ID>/status
Accept: application/json

200 OK
Content-Type: application/json

{
  "status": "awaitingData" | "pending" | "inProgress" | "done" | "failed",
  "result": {
    "assetUrl": "/fotoweb/archives/5000/DocFolder/SubFolder/file.jpeg" | null,
    "assetDetails": {...} | null
  } | null,
  "error": {
    "value": "...",
    "message": "..."
  } | null
}

403 Forbidden

Using the Upload API for Version Control

The Version Control system allows an existing asset to be replaced with a new revision by setting the destinationto the URL of the asset in the initial upload request. The uploaded asset will be added as the latest revision and replace all the metadata with the contents of the uploaded file.