Versions API

Provides operations on OMN assets version and related version information.

Version chunked upload. Start

/dam/assets/versions/bin/chunked/start Initialize chunk upload session for the version file.

Initialize chunk upload session for the file

Version chunk upload workflow consist from 3 general steps like the asset upload:

  1. Initialize/start upload

  2. Upload N chunks

  3. Finish version upload

Upload as version feature will create a version for the file that currently is on the system and then replace the file on the system with the uploaded.
Table 1. Details

Resource path

/api/core/v1/dam/assets/versions/bin/chunked/start

HTTP method

POST

Request content type

application/json

Response content type

  • application/xml; charset=UTF-8;

  • application/json

  • application/json+compact
Body parameters

Specified by AssetVersionUploadRequest

tid - is required and refers to asset for which version file will be uploaded.
Return Type

PimType with filled ResponsesType

Response type contains upload tid - the unique identity of the upload session. Upload tid is required for next upload steps.

Responses
Table 2. Http response codes
Code Message Datatype

200

PimType with filled ResponsesType

PimType

400

Invalid input provided

ResponseType

500

An unknown internal error occurred

ResponseType
Samples
Please use transform endpoint to get the JSON/compact-JSON samples from the XML one.
Start upload session
curl
curl --location --request POST 'https://<OMN_SERVER>/api/core/v1/dam/assets/versions/bin/chunked/start' \
--header 'Authorization: Bearer <TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "tid": "0AA31C0C-F2AE-422C-9C6A-25BAB368706E",
}'
Request body AssetVersionUploadRequest
{
    "tid":"0AA31C0C-F2AE-422C-9C6A-25BAB368706E",
}
Response body. With upload tid.
<?xml version="1.0" encoding="UTF-8"?>
<pim xmlns="http://www.apollon.de/omn">
    <responses>
        <response tid="614cde94-fdd6-47aa-86e6-c090d900032c">
            <status>SUCCESS</status>
            <description>Version chunk upload could be started by upload UUID/tid</description>
        </response>
    </responses>
</pim>
Error responses
No asset by tid
<?xml version="1.0" encoding="UTF-8"?>
<response xmlns="http://www.apollon.de/omn">
    <details>
        <itm key="supportId">8dbfd28d-9487-4c6c-a878-9f30557f2e1b</itm>
    </details>
    <issues>
        <itm key="code">1002</itm>
        <itm key="description">The requested resource could not be found</itm>
        <itms type="details">
            <itm key="errorMessage">Isy object with meta tag guid '0AA31C0C-F2AE-422C-9C6A-25BAB368706E' is not found.</itm>
        </itms>
    </issues>
    <status>ERROR</status>
</response>
No access to the asset
<?xml version="1.0" encoding="UTF-8"?>
<pim xmlns="http://www.apollon.de/omn">
    <responses>
        <response action="update"
                dataType="asset"
                tid="0AA31C0C-F2AE-422C-9C6A-25BAB368706E">
            <status>ERROR</status>
            <description>Asset is not available by access rights</description>
        </response>
    </responses>
</pim>

Version chunked upload. Upload a chunk

/dam/assets/versions/bin/chunked/upload/{uploadTid} Upload a specified chunk of an asset.
Upload session must be started before a chunk upload.
Table 3. Details

Resource path

/api/core/v1/dam/assets/versions/bin/chunked/upload/{uploadTid}

HTTP method

POST

Request content type

multipart/form-data

Response content type

  • application/xml; charset=UTF-8;

  • application/json

  • application/json+compact
Parameters
Path Parameters
Name Description Required Default Pattern

uploadTid

The session identifier of the started chunked upload.

X
Form Parameters
Name Description Required Default Pattern

chunkId

Identity of an asset chunk which should be uploaded

X

Int32. Positive numbers starting from 0.

payload

Blob file

X
Return Type

PimType with filled ResponsesType

Response contains status of the chunk upload.

Responses
Table 4. Http response codes
Code Message Datatype

200

PimType with filled ResponsesType

PimType

500

An unknown internal error occurred

ResponseType
Samples
Please use transform endpoint to get the JSON/compact-JSON samples from the XML one.
Upload a chunk
curl
curl --location --request POST 'https://<OMN_SERVER>/api/core/v1/dam/assets/versions/bin/chunked/upload/614cde94-fdd6-47aa-86e6-c090d900032c' \
--header 'Authorization: Bearer <TOKEN>' \
--form 'payload=@"<PATH_TO_FILE>500x500.jpg"' \
--form 'chunkId="0";type=application/json'
Response body. With upload status
<?xml version="1.0" encoding="UTF-8"?>
<pim xmlns="http://www.apollon.de/omn">
    <responses>
        <response action="create" id="0" tid="614cde94-fdd6-47aa-86e6-c090d900032c">
            <status>SUCCESS</status>
            <description>Chunk has been uploaded</description>
        </response>
    </responses>
</pim>

Version chunked upload. Finish

/dam/assets/versions/bin/chunked/persist/{uploadTid} Finalize the chunk upload of the asset version.

Finalize the chunking upload of the asset version.

Upload as version feature will create a version for file that currently is on the system and then replace the file on the system with the uploaded.

Some chunks should be uploaded before notifying the server that API consumer uploaded all chunks.
Table 5. Details

Resource path

/api/core/v1/dam/assets/versions/bin/chunked/persist/{uploadTid}

HTTP method

PUT

Request content type

application/json

Response content type

  • application/xml; charset=UTF-8;

  • application/json

  • application/json+compact
Parameters
Path Parameters
Name Description Required Default Pattern

uploadTid

The session identifier of the started chunked upload.

X
Body parameters

Specified by AssetVersionUploadRequest.

Version of the existing file will be created with provided parameters AssetVersionUploadRequest

It’s a finalization step for file version upload. The AssetVersionUploadRequest's tid parameter should be the same as was sent for /dam/assets/versions/bin/chunked/start.
Return Type

PimType with filled ResponsesType

Response type contains status and info about asset that was uploaded to the system.

Responses
Table 6. Http response codes
Code Message Datatype

200

PimType with filled ResponsesType

PimType

400

Invalid input provided

ResponseType

500

An unknown internal error occurred

ResponseType
Samples
Please use transform endpoint to get the JSON/compact-JSON samples from the XML one.
Finalize upload session
curl
curl --location --request POST 'https://<OMN_SERVER>/api/core/v1/dam/assets/versions/bin/chunked/persist/614cde94-fdd6-47aa-86e6-c090d900032c' \
--header 'Authorization: Bearer <TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "tid": "0AA31C0C-F2AE-422C-9C6A-25BAB368706E",
    "versionComment": "Created before upload via API",
    "timeoutDate": "2022-09-07T09:16:09.171Z",
    "protectedAfterDate": "2022-09-07T09:16:09.171Z",
    "protectedBeforeDate": "2022-09-07T09:16:09.171Z",
}'
Request body AssetVersionUploadRequest
{
    "tid":"0AA31C0C-F2AE-422C-9C6A-25BAB368706E",
    "versionComment": "Created before upload via API",
    "timeoutDate": "{Date in the ISO8601 format}",
    "protectedAfterDate": "{Date in the ISO8601 format}",
    "protectedBeforeDate": "{Date in the ISO8601 format}"
}}
Response body. With status and uploaded asset info
<?xml version="1.0" encoding="UTF-8"?>
<pim xmlns="http://www.apollon.de/omn">
    <responses>
        <response action="update"
                dataType="asset"
                tid="0AA31C0C-F2AE-422C-9C6A-25BAB368706E">
            <status>SUCCESS</status>
            <description>Old file has been versioned and new file has been uploaded</description>
        </response>
    </responses>
</pim>
Error responses

It is possible, that during chunks upload, the target is not available.

No asset by tid
<?xml version="1.0" encoding="UTF-8"?>
<response xmlns="http://www.apollon.de/omn">
    <details>
        <itm key="supportId">8dbfd28d-9487-4c6c-a878-9f30557f2e1b</itm>
    </details>
    <issues>
        <itm key="code">1002</itm>
        <itm key="description">The requested resource could not be found</itm>
        <itms type="details">
            <itm key="errorMessage">Isy object with meta tag guid '0AA31C0C-F2AE-422C-9C6A-25BAB368706E' is not found.</itm>
        </itms>
    </issues>
    <status>ERROR</status>
</response>
No access to the asset
<?xml version="1.0" encoding="UTF-8"?>
<pim xmlns="http://www.apollon.de/omn">
    <responses>
        <response action="update"
                dataType="asset"
                tid="0AA31C0C-F2AE-422C-9C6A-25BAB368706E">
            <status>ERROR</status>
            <description>Asset is not available by access rights</description>
        </response>
    </responses>
</pim>

Version upload

/dam/assets/versions/bin/persist Upload asset as version to the system.

Semantic is the same as in chunked version upload. Within this endpoint it’s possible to upload file per one request without splitting to chunks.

Upload as version feature will create a version for file that currently is on the system and then replace the file on the system with the uploaded.

Table 7. Details

Resource path

/api/core/v1/dam/assets/versions/bin/persist

HTTP method

POST

Request content type

multipart/form-data

Response content type

  • application/xml; charset=UTF-8;

  • application/json

  • application/json+compact
Form Parameters
Name Description Required Default Pattern

params

Version upload and creation parameters AssetVersionUploadRequest

X

payload

Blob file

X
Return Type

PimType with filled ResponsesType

Response type contains status and info about upload asset version operation.

Responses
Table 8. Http response codes
Code Message Datatype

200

PimType with filled ResponsesType

PimType

400

Invalid input provided

ResponseType

404

No asset by tid

ResponseType

500

An unknown internal error occurred

ResponseType
Samples
Please use transform endpoint to get the JSON/compact-JSON samples from the XML one.
Upload file version 
curl --location --request POST 'https://<OMN_SERVER>/api/core/v1/dam/assets/versions/bin/persist' \
--header 'Authorization: Bearer <TOKEN>' \
--form 'payload=@"/<FILE_PATH>/artworks-bQbImNIL55TZ52he-gAKJ7w-t500x500.jpg"' \
--form 'params="{\"versionComment\": \"Created before upload via API\", \"tid\":\"F103F147-428C-4427-AA65-8A46AE066803\"}";type=application/json'
Request body AssetVersionUploadRequest
{
    "tid":"F103F147-428C-4427-AA65-8A46AE066803",
    "versionComment": "Created before upload via API",
    "timeoutDate": "{Date in the ISO8601 format}",
    "protectedAfterDate": "{Date in the ISO8601 format}",
    "protectedBeforeDate": "{Date in the ISO8601 format}"
}
Response body
<?xml version="1.0" encoding="UTF-8"?>
<pim xmlns="http://www.apollon.de/omn" schemaVersion="5.6.0">
    <meta>
        <itm key="messageType">request</itm>
        <itm key="messageTime">2022-07-16T09:30:46.743Z</itm>
        <itm key="sourceEnv">web</itm>
    </meta>
    <responses>
        <response dataType="asset"
                tid="F103F147-428C-4427-AA65-8A46AE066803"
                action="update">
            <status>SUCCESS</status>
            <description>Old file has been versioned and new file has been uploaded</description>
        </response>
    </responses>
</pim>
Error response
No access to the asset
<?xml version="1.0" encoding="UTF-8"?>
<pim xmlns="http://www.apollon.de/omn" schemaVersion="5.6.0">
    <meta>
        <itm key="messageType">request</itm>
        <itm key="messageTime">2022-07-16T09:45:15.768Z</itm>
        <itm key="sourceEnv">web</itm>
    </meta>
    <responses>
        <response dataType="asset"
                tid="BA7A3E08-A48B-47FE-8150-6986A61588732"
                action="update">
            <status>ERROR</status>
            <description>Asset is not available by access rights</description>
        </response>
    </responses>
</pim>

Retrieve Binary Versions

/dam/assets/versions/bin Retrieves the binary data of asset version.
Table 9. Details

Resource path

/api/core/v1/dam/assets/versions/bin

HTTP method

POST

Request content type

Request params

Response content type

application/octet-stream
Body parameters

Specified by request URL params

  • assetTid - (String) - tid of asset

  • assetId - (Integer) - identity of asset

  • format - (String) - type of version preview

  • versionNumber - (Integer) - number of version

  • versionTid - (String) - tid of version

Return Type

Binary data of asset version file.

Responses
Table 10. Http response codes
Code Message Datatype

200

OmnType with list of keywords

OmnType

404

The requested resource could not be found

ResponseType

500

An unknown internal error occurred

ResponseType
Samples
1. Retrieve binary version by assetId
curl
curl --location --request POST 'http://<OMN_SERVER>/api/core/v1/dam/assets/versions/bin?assetId=<ASSET_IDENTITY>&versionNumber=<VERSION_NUMBER>' \
--header 'Authorization: Bearer <TOKEN> ' \
--data-raw ''

Request params:

assetId=12345, versionNumber=1

Response body:

apollon_logo_original.png
2. Retrieve binary version by assetTid
curl
curl --location --request POST 'http://<OMN_SERVER>/api/core/v1/dam/assets/versions/bin?assetTid=<ASSET_TID>&versionNumber=<VERSION_NUMBER>' \
--header 'Authorization: Bearer <TOKEN> ' \
--data-raw ''

Request params:

assetId=B29ECF60-0AB0-431D-8510-94490F27B229, versionNumber=1

Response body:

apollon_logo_original.png
3. Retrieve version preview by version tid and preview type
curl
curl --location --request POST 'http://<OMN_SERVER>/api/core/v1/dam/assets/versions/bin?versionTid=<VERSION_TID>&format=<PREVIEW_FORMAT>' \
--header 'Authorization: Bearer <TOKEN> ' \
--data-raw ''

Request params:

versionTid=B29ECF60-0AB0-431D-8510-94490F27B229, previewType=previewThumbnail

Response body:

thumbnail.png

Welcome to the AI Chat!

Write a prompt to get started...