Copyright © 2005-2022

Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically.


This guide describes the RESTful API of the CORE Preferences Service and its usage. Some general terms and definitions are explained and declared in the first part of the document whereas in the second part the usage of the API is shown in a more use-case-driven approach.

Representation Formats

Basically JSON is used as representation format by default if not otherwise requested or mentioned below. XML format is supported for the index pages as well, but must be requested explicitly. Furthermore a vendor specific JSON format is used to represent resource representations. Therefore it is absolutely required that the Accept header denotes the demanded type. Find the type in the examples below.

Dates in JSON

Date or datetime fields are not treated specially in JSON. Within the scope of this API a date or datetime field is always expected and rendered as JSON String in ISO8601 format with timezone information and milliseconds: yyyy-MM-dd’T’HH:mm:ss.SSSTZD.

Embedded Entities

For the sake of convenience some response entities may included embedded entities or even parts of it. A reference to the actual entity is provided as HAL link as well.

Error Responses

Beside the actual representation of resources, the server may result an error response in JSON format that contains basic information about the error occurred. This information is additional to the standard HTTP status code and may help clients to identify the error cause in order to re-phrase and send the request again.

Currently there are two types of errors with their own response formats.

Server Declined Errors

This kind of errors are sent by the server runtime environment even before the request had a chance to be processed.

An example response looks like this:

  "timestamp" : 1512400854941,
  "path" : "/v1/preferences",
  "status" : 409,
  "error" : "Conflict",
  "message" : "",
  "requestId" : "7acb57f4"

The JSON structure contains the following fields.

Property Name Description


When the error occurred on server side


The part of the URI for the REST resource that was queried


The http status of the error


A short error text


A more descriptive error text describing the error in detail


Server assigned unique id of each request, used for tracing and profiling

API Declined Errors

Those errors are thrown within the REST API validation and processing logic. For example, if a client request does not match the expected format or has produced an error on server side, the API will decline the request and return a response with status client-side error (4xx).

The structure of the response is aligned to the RFC7808. An example response looks like this:

    "message": "LocationGroup with name [NOT_EXISTS] not found",
    "messageKey": "owms.common.common.lg.notFoundByName",
    "obj" : [ "NOT_EXISTS" ],
    "httpStatus" : "404",
    "class" : "String"

The JSON structure contains the following fields.

Property Name Description


A short error text


An unique identifier across the API that can be used to identify and translate the error message on the client side


An array of possible passed arguments to the message


The http status of the error


The arguments type

Following message keys are currently used:

Message Key Description Action


The requested resource has not been found

The resource does not exist anymore or has never existed. The resource identifier must be verified


The TransportUnit does not exist

Verify the identifying attribute passed to the API


The requested Location does not exist

Verify the identifying attribute passed to the API


The requested LocationGroup does not exist

Verify the identifying attribute passed to the API


The requested TransportUnitType does not exist

Verify the identifying attribute passed to the API


A description of all used API resources.



The initial HTTP request to retrieve information about all available resources looks like the following. The Index page is a public available resource and does not need any authentication.

GET /index HTTP/1.1
Host: localhost:8080

The Index resource is returned in the response body with the response status of 200-OK. This main Index lists all primary resource entities to follow next.

HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 116

  "_links" : {
    "preferences-index" : {
      "href" : "http://localhost:8080/v1/preferences/index"

A client application must only know about the agreed link names and follow the corresponding href link to navigate further.


A Preference represents a configuration value in a particular scope. So a Preference could only be visible and editable by one particular user in the system, then this is an UserPreference. If a Preference should be valid for many users then it can be assigned to a user role and is of type RolePreference.

Apart from users and roles a Preference can also be assigned to an abstract thing called Module. This could be a single Microservice for example. This is of type ModulePreference. The whole application consists of several Microservices that may require common preferences that are valid for all modules, those are stores of type ApplicationPreference.

All kind of preferences share same data stored in a supertype called Preference. Each subtype defines the scope as a property and an owner of the Preference. This might be the name of the user, the role name or the microservice name. A Preference is identified by type, owner and the key field.

Preferences Index

The Preferences Index with all possible operations can be retrieved with the following GET request: Unresolved directive in 2-configuration.adoc - include::/home/runner/work/org.openwms.core.preferences/org.openwms.core.preferences/target/generated-snippets/prefs-index/http-request.adoc[]

The response lists all the operations with a name and the corresponding href link: Unresolved directive in 2-configuration.adoc - include::/home/runner/work/org.openwms.core.preferences/org.openwms.core.preferences/target/generated-snippets/prefs-index/http-response.adoc[]

Find all Preferences (preferences-findall)

Send a HTTP GET request without any further query parameters to find and return all existing Preferences Unresolved directive in 2-configuration.adoc - include::/home/runner/work/org.openwms.core.preferences/org.openwms.core.preferences/target/generated-snippets/prefs-findall/http-request.adoc[]

The server responds with an array of all Preferences, that might be empty if no Preferences exist Unresolved directive in 2-configuration.adoc - include::/home/runner/work/org.openwms.core.preferences/org.openwms.core.preferences/target/generated-snippets/prefs-findall/http-response.adoc[]

Find a Preference by Key (preferences-findbypkey)

Send a HTTP GET request with the persistent key as part of the path to find and return the Preference Unresolved directive in 2-configuration.adoc - include::/home/runner/work/org.openwms.core.preferences/org.openwms.core.preferences/target/generated-snippets/prefs-findbykey/http-request.adoc[]

The server returns the Preference resource in case it exists Unresolved directive in 2-configuration.adoc - include::/home/runner/work/org.openwms.core.preferences/org.openwms.core.preferences/target/generated-snippets/prefs-findbykey/http-response.adoc[]

or responds with a 404 NOT-FOUND if the Preference does not exist Unresolved directive in 2-configuration.adoc - include::/home/runner/work/org.openwms.core.preferences/org.openwms.core.preferences/target/generated-snippets/prefs-findbykey404/http-response.adoc[]

Find all Preferences of particular Scope (preferences-findallofscope)

Send a HTTP GET request with the desired scope as request parameter to find and return all Preferences that belong to the given scope Unresolved directive in 2-configuration.adoc - include::/home/runner/work/org.openwms.core.preferences/org.openwms.core.preferences/target/generated-snippets/prefs-findallofscope/http-request.adoc[]

The server responds with an array of Preferences, or an empty array if no Preferences exist Unresolved directive in 2-configuration.adoc - include::/home/runner/work/org.openwms.core.preferences/org.openwms.core.preferences/target/generated-snippets/prefs-findallofscope/http-response.adoc[]

Notice: It is not allowed to query UserPreferences without a particular user parameter to prohibit spoofing of private user settings. The attempt to do so is blocked by the server with: Unresolved directive in 2-configuration.adoc - include::/home/runner/work/org.openwms.core.preferences/org.openwms.core.preferences/target/generated-snippets/prefs-findallofscope-403/http-response.adoc[]

Create a new Preference (preferences-create)

New Preferences can be created either with the definition in XML files or over the REST API. A client must send a POST request to the Preferences resource in order to create a new instance. The content is passed in the request body. Unresolved directive in 2-configuration.adoc - include::/home/runner/work/org.openwms.core.preferences/org.openwms.core.preferences/target/generated-snippets/prefs-create/http-request.adoc[]

The server responds with 201 CREATED if the operation succeeds. Unresolved directive in 2-configuration.adoc - include::/home/runner/work/org.openwms.core.preferences/org.openwms.core.preferences/target/generated-snippets/prefs-create/http-response.adoc[]

If the Preference to create already exists, the server returns: Unresolved directive in 2-configuration.adoc - include::/home/runner/work/org.openwms.core.preferences/org.openwms.core.preferences/target/generated-snippets/prefs-create-fails/http-response.adoc[]

Update an existing Preference (preferences-update)

To modify an existing Preference an PUT request with the Preference as request body is expected. The Preference to update is identified by the persistent key as part of the path. Unresolved directive in 2-configuration.adoc - include::/home/runner/work/org.openwms.core.preferences/org.openwms.core.preferences/target/generated-snippets/prefs-update/http-request.adoc[]

The server responds with 204 NO-CONTENT. Unresolved directive in 2-configuration.adoc - include::/home/runner/work/org.openwms.core.preferences/org.openwms.core.preferences/target/generated-snippets/prefs-update/http-response.adoc[]

Delete a Preference (preferences-delete)

To delete an existing Preference one can call the URI to the resource with a HTTP DELETE request. The persistent key of the Preference is required to identify the resource to delete. Unresolved directive in 2-configuration.adoc - include::/home/runner/work/org.openwms.core.preferences/org.openwms.core.preferences/target/generated-snippets/prefs-delete/http-request.adoc[]

The server responds with 204 NO-CONTENT is the resource has been deleted successfully. Unresolved directive in 2-configuration.adoc - include::/home/runner/work/org.openwms.core.preferences/org.openwms.core.preferences/target/generated-snippets/prefs-delete/http-response.adoc[]

If the resource doesn’t exist and could not be deleted the server responds with a 404 NOT-FOUND.


A UserPreference is a Preference that is only valid for a single user.

Find all UserPreferences of an User (user-preferences-findbyuser)

Send a HTTP GET request without the user name as query parameter to find all existing UserPreferences of that user.

Unresolved directive in 3-userprefs.adoc - include::/home/runner/work/org.openwms.core.preferences/org.openwms.core.preferences/target/generated-snippets/prefs-findforuser/http-request.adoc[]

The server responds with an array of all UserPreferences, that might be empty if no UserPreferences exist.

Unresolved directive in 3-userprefs.adoc - include::/home/runner/work/org.openwms.core.preferences/org.openwms.core.preferences/target/generated-snippets/prefs-findforuser/http-response.adoc[]

Find a UserPreference by Key (user-preferences-findbyuserandkey)

Send a HTTP GET request with the persistent key and the user name as query parameters to find and return the UserPreference.

Unresolved directive in 3-userprefs.adoc - include::/home/runner/work/org.openwms.core.preferences/org.openwms.core.preferences/target/generated-snippets/prefs-findforuserkey/http-request.adoc[]

The server returns the UserPreference if exists.

Unresolved directive in 3-userprefs.adoc - include::/home/runner/work/org.openwms.core.preferences/org.openwms.core.preferences/target/generated-snippets/prefs-findforuserkey/http-response.adoc[]

or responds with a 404 NOT-FOUND if the UserPreference does not exist.

Unresolved directive in 3-userprefs.adoc - include::/home/runner/work/org.openwms.core.preferences/org.openwms.core.preferences/target/generated-snippets/prefs-findforuserkey404/http-response.adoc[]