Copyright © 2005-2020

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 WMS Receiving Service module 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.


A description of all used API resources.

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’s absolutely required 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,
    "status": 500,
    "error": "Internal Server Error",
    "exception": "org.ameba.oauth2.InvalidTokenException",
    "message": "JWT expired at 2017-12-04T15:04:43Z. Current time: 2017-12-04T15:20:54Z, ...",
    "path": "/v1/transport-units?bk=00000000000000004711"

The JSON structure contains the following fields.

Property Name Description


When the error occurred on server side


The http status of the error


A short error text


Internal class name of the Java exception type


A more descriptive error text describing the error in detail


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

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",
    "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 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.

Unresolved directive in 1-index.adoc - include::/home/travis/build/openwms/org.openwms.core.uaa/target/generated-snippets/get-index/http-request.adoc[]

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.

Unresolved directive in 1-index.adoc - include::/home/travis/build/openwms/org.openwms.core.uaa/target/generated-snippets/get-index/http-response.adoc[]

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


A User represents a human user of the system, usually in front of an UI who interacts with the system. User representations can be created, modified and retrieved. An User is also allowed to authenticate against an UAA endpoint.

Create an User

To create a new User instance a POST request must be send to the server with the mandatory fields of the User in the request body

POST /users HTTP/1.1
Content-Type: application/json
Content-Length: 76
Host: localhost:8080

  "links" : [ ],
  "username" : "admin",
  "email" : ""
Path Type Description



The unique name of the User in the system



The email address used by the User, unique in the system

If the User has been created successfully, the server returns the URI to the created resource:

HTTP/1.1 201 Created
Location: http://localhost:8080/users/eafffa5a-ab8b-4c77-b468-da92d537df9d/

Find an User by persistent key

A newly created User can be retrieved by following the URI in the LOCATION header of the response. This URI points to the created resource:

GET /users/eafffa5a-ab8b-4c77-b468-da92d537df9d/ HTTP/1.1
Host: localhost:8080

If the resource exists the server responds with a 200-OK and the User representation in the response body.

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

  "pKey" : "eafffa5a-ab8b-4c77-b468-da92d537df9d",
  "username" : "admin",
  "externalUser" : false,
  "locked" : false,
  "enabled" : true

Get the User Details (OAuth2 UserDetails)

An endpoint exists to get the details of the current logged-in User from. An OAuth2 Access Token must be provided as Bearer token in order to access the endpoint.

GET /oauth/userinfo HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MDAzMjg1NDcsInVzZXJfbmFtZSI6InRlc3RlciIsImp0aSI6ImE4N2IwZTRkLTdmZDgtNDMzYS04ODA4LTFhYzNkMjliM2NmZSIsImNsaWVudF9pZCI6ImdhdGV3YXkiLCJzY29wZSI6WyJnYXRld2F5Il19.AzQzhae3JysEVjBv3Sa2niOHNiJyrFlsVRPydDo17yM
Host: localhost:8080

If the access token is valid and the server granted access to the resource, a JSON object with the user details is returned.

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 307
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

  "sub" : "tester",
  "gender" : "FEMALE",
  "name" : "tester",
  "phone_number" : "001-1234-56789",
  "given_name" : "Mister Jenkins",
  "family_name" : "Mister Jenkins",
  "email" : "",
  "picture" : "http://localhost:8080/uaa/user/96baa849-dd19-4b19-8c5e-895d3b7f405d/image/"
Path Type Description



Subject is the logged in end-user



The end-users gender



Name of the end-user



Her phone number



The given name



Her family name



Her primary email address



A link to a profile picture