Core API Concepts

The OMN Core API follows the Common Concepts. But it has some specifica which are described as follows.

What means 'REST over HTTP`-like?

The Core API implements the REST style, but extends it by operations on resources beside the standard HTTP methods. This is mainly done to support bulk requests. This enables the client to manage several resources within a single request. This reduces the number of requests and simplifies the client logic for same kind of operations on same resources.

Depending on which resource you want to access and how you construct an HTTP request, you can perform several types of operations, including:

Determine available API versions
Create, read, update, delete data objects or its metadata
Create, read, update, delete the virtual structures of data objects
Create, read, update, delete of classifications, keywords
Linking data objects

For details see API methods.

API Methods

HTTP Methods

For simple API requests (managing single resources) the Core API supports standard HTTP request methods (HEAD, GET, POST, PATCH, PUT, and DELETE), which follow the specifications at RFC 9110 HTTP Semantics.

API Operations

In addition to the HTTP methods the Core API supports additional operations on resources that represent more specific operations on a specific resource or even a list of resources which are not covered by the HTTP methods.

They are also used to support bulk requests. This enables the client to manage several resources within a single request. This reduces the number of requests and simplifies the client logic for same kind of operations on same resources.

Operations are represented as a segment of the Core API URI schema in an HTTP POST request .

Operation	Usecase	Response body
query	fetches the resource(s collection)	only a list of IDs or TIDs without concrete resources or details
retrieve	fetches the resource(s)	the resource(s) with details
persist	create or update the resource(s)	the created/updated resource(s)
perform	to execute specific actions on resources. E.g. delete	if action was executed successfully and the results of the actions (depends on the actions)

Operation

Usecase

Response body

query

fetches the resource(s collection)

only a list of IDs or TIDs without concrete resources or details

retrieve

fetches the resource(s)

the resource(s) with details

persist

create or update the resource(s)

the created/updated resource(s)

perform

to execute specific actions on resources. E.g. delete

if action was executed successfully and the results of the actions (depends on the actions)

API Actions

Dependent to the related resources Core API supports actions in perform operations that are performed on the defined resources. The actions are defined in the request body.

Actions give the flexibility to choose different kind of actions for different resource instances in 1 single request (if they are not interdependent). Which means that bulk processing is more flexible. In addition, the list of supported actions can be extended without necessity to change the URI.

Sample actions

delete
create
update
move

When to use what?

The Core API concept is very powerful and supports complex scenarios (bulk operations, reduction of network communications). On the other side this power is not needed in simpler scenarios. The following table helps to decide which API endpoint methods, operations and actions to be used when.

When What Why

When	What	Why
you want to manage a single resource	use `HTTP` methods (if such exist) for your requirements	the requests are simpler. In best case with no or only query parameters and without (complex) request body. Then a request can also be easily executed in a browser or any HTTP client (cURL, Postman, …).
you want to retrieve a list of resources (IDs or data)	use the `operations` query or retrieve	here you can differ between list of identifiers or concrete resource data and get a corresponding list
you want to create or update (change the resources' (meta-)data) a list of resources	use the `operation` persist	here you can create a list of resources within 1 request
you want to execute specialized actions on a list of resources	use the `operation` perform	to have the flexibility to perform different types of actions on a number list of resources.

you want to manage a single resource

use HTTP methods (if such exist) for your requirements

the requests are simpler. In best case with no or only query parameters and without (complex) request body. Then a request can also be easily executed in a browser or any HTTP client (cURL, Postman, …).

you want to retrieve a list of resources (IDs or data)

use the operations query or retrieve

here you can differ between list of identifiers or concrete resource data and get a corresponding list

you want to create or update (change the resources' (meta-)data) a list of resources

use the operation persist

here you can create a list of resources within 1 request

you want to execute specialized actions on a list of resources

use the operation perform

to have the flexibility to perform different types of actions on a number list of resources.

With the flexibility to use bulk operations the error handling will become more complex. We support this by a response type that gives detailed information what operation/action for which resources went wrong. The client must be able to handle those responses.

So a design decision must be made dependent to your requirements whether to use simple endpoints for managing single resources or using additional operations/actions for managing a list of resources at once.

But you have the flexibility to mix them.

Core API URI Schema

The Core API provides access to OMN resources (data entities) and related operations via REST over HTTP. Each resource is exposed by a uniform resource identifier (URI).

Main Schema

The OMN Core URI has the following main schema:

https://\{host}/api/core/{api version}/\{module}/\{resources}/\{operation}

host: the OMN host name

/api/core/: represents the base path for all OMN Core API endpoints

api version: the Core API version (not the OMN version!)

module: the OMN module name (e.g. dam, pim, …) or common for cross-module endpoints.

resource: the name of the resource (data entity) in plural notation (e.g. assets)

operation: the operation to be executed on the resource (e.g. perform, persist, retrieve, query)

For example:

https://localhost/api/core/v1/dam/assets/persist

This endpoint will persist (create or update) the asset in DAM.

Binary Endpoint Schema

Endpoints for managing binary files have a different schema:

https://\{host}/api/core/{api version}/\{module}/\{resources}/bin/(chunked)\{operation}

/bin/: indicates that the endpoint is related to a binary file

chunked (optional): indicates that chunked file upload mechanism is used.

The HTTP specification (RFC 9110) limits the maximum URL size to 255 bytes due to compatibility reasons. That is a reason why we avoid to use complex URIs and URI parameters.

Chunked file upload mechanism

Uploading large (binary) files might become problematic as your connection can be interrupted or if the files pass an edge servers/reverse proxy which has file size limitations and blocks the transfer or processing runs into a timeout your entire upload will fail.

With the chunked file upload mechanism we reduce those risks to a minimum.

The mechanism splits the binary files into a sequence of small parts (chunks) that will be transferred instead of one big file. The chunks will be assembled on the server once they are all uploaded.

The mechanism knows 3 endpoints which must be used to upload chunks:

start: Initialize chunk upload session for the binary file.
upload: Upload a specific chunk
persist: Finalize the chunked upload (tell the server he can assemble the chunks)

Welcome to the AI Chat!

Write a prompt to get started...