This page is a supplement for the Documents service Open API documentation. It provides supplementary information that is not included in the endpoint documentation on Swagger UI. It also provides documentation for endpoints that are not documented on the Swagger UI.

Atomic Operations

Documents service supports JSON:API Atomic Operations. The current implementation limits to operations on documents and documentMetadataItems resource types only. For details of authorization requirements for using atomic operations on supporting resource types, please refer to the following table.

For samples of atomic operations that are currently supported by this service, please see the attached file.

Upload Documents

Upload documents to Seamless

• Steps

  • Create a document record:
    Request:

  POST '<https://{{host-documents}}/api/v1/documents>' Content-Type: application/vnd.api+json { "data": { "type": "documents", "attributes": { "name": "test1.txt", "description": "My test file", "fileType": "txt", "tags": [ "tagA", "tagB" ] } } }

  Response:

  HTTP/1.1 201 Created Content-Type: application/vnd.api+json Location: <http://{documents-host}/api/v1/documents/0438151c-8dae-4b04-b360-b656c3f33487> { "data": { "type": "documents", "id": "0438151c-8dae-4b04-b360-b656c3f33487", "attributes": { "name": "test1.txt", "description": null, "fileType": "txt", "isExternal": false, "size": 0, "tags": "tagA;tagB", "sourceId": null, "ownerId": "3d21921c-1887-48da-9665-093356c89f4b", "sourceSystemReference": null, "createdByUserId": null, "createdDate": "0001-01-01T00:00:00+00:00", "lastModifiedByUserId": null, "lastModifiedDate": "0001-01-01T00:00:00+00:00", "tenantId": null, "scope": "contemi-testing", "actions": {}, "numberOfCoverPages": null, "templateId": null, "relatedTo": null } } }

  • Upload file content to the document record:

    • Generate an upload URL:

      POST '<https://{{host-documents}}/api/v1/documents/generateUploadLink/0438151c-8dae-4b04-b360-b656c3f33487>' Accept: application/json

      • If the server responds with a ToApiServer upload strategy, the client should upload the file content to the server

        • Response

          { "url": "<https://{document-host}/api/v1/documents/0438151c-8dae-4b04-b360-b656c3f33487/content>", "storageStrategy": "local", "uploadStrategy": "ToApiServer", "additionalInfo": {} }

        • Upload the file content to the server

          PUT /api/v1/documents/38cad9d2-6548-470c-aa50-5d983eae29bf/content HTTP/1.1 Accept: application/json, text/plain, */* Content-Length: 248064 Content-Type: text/plain

      • If the server responds with a DirectToStorage upload strategy, the client should upload the file content to the storage location (at the time of writing this, there is only AWSS3 storage) directly:

        • Response

          { "url": "an-s3-bucket-url", "storageStrategy": "AWSS3", "uploadStrategy": "DirectToStorage", "additionalInfo": { "bucket": "an-s3-bucket-name", "key": "an-object-key", "Policy": "a-long-base64-encoded-policy-whose-content-you-dont-need-to-know", "X-Amz-Signature": "a-sigurature-string", "X-Amz-Algorithm": "AWS4-HMAC-SHA256", "X-Amz-Credential": "test/20240523/eu-west-2/s3/aws4_request", "AWSAccessKeyId": "test" } }

        • Upload directly to the S3 bucket

          POST the-s3-bucket-url-received-from-the-previous-step Accept: application/json, text/plain, */* Content-Type: multipart/form-data; boundary=----abcdefhg ------abcdefhg Content-Disposition: form-data; name="bucket" seamless-documents-bucket-development ------abcdefhg Content-Disposition: form-data; name="key" contemi-testing/0438151c-8dae-4b04-b360-b656c3f33487.csv ------abcdefhg Content-Disposition: form-data; name="Policy" <policy_received_from_the_previous_step> ------abcdefhg Content-Disposition: form-data; name="X-Amz-Signature" <signature_received_from_the_previous_step> ------abcdefhg Content-Disposition: form-data; name="X-Amz-Algorithm" AWS4-HMAC-SHA256 ------abcdefhg Content-Disposition: form-data; name="X-Amz-Credential" <credential_string_received_from_the_previous_step> ------abcdefhg Content-Disposition: form-data; name="AWSAccessKeyId" <access_key_received_from_the_previous_step> ------abcdefhg Content-Disposition: form-data; name="file"; filename="test1.txt" Content-Type: text/plain ------abcdefhg--

• It is not mandatory to generate an upload URL if you decide to upload the file content to the API server. Howerver, uploading large files is only possible by generating an upload URL and uploading the file content directly to the storage location.

Link a Seameless document record to a real document in an external system

Use: POST /api/v1/documents/externalLinkDocument

Download Documents

• Download from API server:
  Request:

  GET /api/v1/documents/0b9ca6d7-f314-4b1a-b0bb-1f90bc509b69/content HTTP/1.1 Accept: application/json, text/plain, */*

  Response:

  HTTP/1.1 200 OK Content-Length: 0 Content-Type: application/octet-stream Date: Thu, 23 May 2024 07:25:51 GMT Server: Kestrel Access-Control-Allow-Origin: * Access-Control-Expose-Headers: Content-Disposition Content-Disposition: attachment; filename=Test; filename*=UTF-8''Test

• Download directly from storage location (Neccessary if the file is large in size)

  • Generate download URL

    • Request

    POST /api/v1/documents/generateDownloadLink/6437f132-1bf4-48b7-b404-cf6d0c681506 HTTP/1.1 Accept: application/json, text/plain, */*

    • Response

    HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 { "url": "a-presigned-url", "isExternal": false }

  • Download the file from the presigned URL

    GET <the_presigned_url_received_from_the_previous_step> Accept: application/json, text/plain, */*