REST API Usage

Architecture

The OMN REST APIs are "REST over HTTP"-like APIs following the REST architectural style and its guiding constraints:

  • HTTPS only — all communication between client and server is encrypted.

  • Client-server — client and API concerns are separated and evolve independently.

  • Stateless — the server keeps no client state; every request carries all the information required to process it (including the JWT, see Authentication).

  • Cacheable — responses are marked cacheable or not, so clients and intermediaries can cache safely.

  • Layered system — clients cannot see beyond the server layer; proxies and load balancers can be added transparently.

  • Uniform interface — resources are exposed under a consistent namespace and are manipulated through the representations the client receives.

Supported formats

JSON and XML are supported as request and response formats. JSON (UTF-8) is the default. XML requests are accepted in UTF-8 and UTF-16; XML responses are UTF-8. Use the Accept header to choose the response format and Content-Type for the request body.

Cross-Origin Resource Sharing (CORS)

The APIs support CORS so that browser-based client applications served from another origin can call them directly.

URI schema

The Core API exposes each resource through a uniform resource identifier:

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

  • host — the OMN host name

  • /api/core/ — base path of all Core API endpoints

  • api version — the Core API version (v1), not the OMN product version

  • module — the OMN module (pim, dam, cm, peo) or common for cross-module endpoints

  • resources — the resource name in plural notation (for example assets)

  • operation — the operation executed on the resource (query, retrieve, persist, perform)

Example: https://<OMN_SERVER>/api/core/v1/dam/assets/persist creates or updates assets in DAM.

Endpoints managing binary files use an extended schema — …​/{resources}/bin/{operation} — with an optional chunked segment (…​/bin/chunked/…​) for the chunked file upload mechanism.

The Search API uses the base path /api/v1/search, the Workflow API /api/v1/workflow (see Getting Started for the API overview).

HTTP methods and OMN operations

For simple requests on single resources the Core API supports the standard HTTP methods (HEAD, GET, POST, PATCH, PUT, DELETE) per RFC 9110.

In addition, the Core API defines operations on resources — POSTed URI segments that cover more specific use cases and enable bulk requests on lists of resources:

Operation Use case Response body

query

fetch a resource collection

only IDs/TIDs, no resource details

retrieve

fetch resources

the resources with details

persist

create or update resources

the created/updated resources

perform

execute specific actions on resources (e.g. delete, move)

action results

perform requests carry actions (for example delete, create, update, move) in the request body. Different actions for different resource instances can be mixed in a single request, as long as they are not interdependent.

When to use what: manage a single resource with plain HTTP methods where they exist (simplest requests); fetch lists with query (IDs) or retrieve (data); create/update lists with persist; run specialized actions on lists with perform. Bulk flexibility makes error handling more involved — the response details which operation or action failed for which resource, and the client must handle that (see Error Handling).

Bulk operations

For asynchronous processing of large requests, use bulk in place of perform or persist in the endpoint URL. The bulk endpoint accepts the same request body as the corresponding perform/persist endpoint.

Create a bulk operation:

  • POST …​/bulk — body: JSON/XML specifying a perform action or persist operation. Returns 202 Accepted with an operation-id (GUID) for polling, or 400 Bad Request for invalid input.

Poll the status:

  • GET …​/bulk/{operation-id} — 200 OK: completed, result returned (fetchable once, available for 1 hour; inspect it for per-resource errors) · 204 No Content: still in progress, keep polling · 404 Not Found: unknown operation id · 500 Internal Server Error: server-side failure.

Limitations: bulk operations cannot be canceled or resumed (a server restart loses the in-flight remainder and invalidates the operation-id), there is no progress indication, result and status are only available on the instance that accepted the request, and the server executes queued bulk requests FIFO (two simultaneously by default).