Copyright © 2005-2025

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.

Overview

This guide describes the RESTful API of the OpenWMS.org COMMON Transactions 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 described in a 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,
    "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

timestamp

When the error occurred on server side

status

The http status of the error

error

A short error text

exception

Internal class name of the Java exception type

message

A more descriptive error text describing the error in detail

path

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",
    "messageKey": "owms.common.common.lg.notFoundByName",
    "obj" : [ "NOT_EXISTS" ],
    "httpStatus" : "404",
    "class" : "String"
}

The JSON structure contains the following fields.

Property Name Description

message

A short error text

messageKey

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

obj

An array of possible passed arguments to the message

httpStatus

The http status of the error

class

The arguments type

Following message keys are currently used:

Message Key Description Action

Index

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: 115

{
  "_links" : {
    "transactions-index" : {
      "href" : "http://localhost:8080/transactions/index"
    }
  }
}

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

Transaction

A Transaction represents an arbitrary remarkable action with some kind of business value, that needs to be persisted after it happened. In a simple case this could be some User action or any kind of business transaction spawned across multiple APIs.

model.drawio
Property Name Description

pKey

The persistent key used to identify a single existing Transaction resource

description

A human readable descriptive text of the Transaction that happened

type

A defined transaction type or key

createdByUser

The human user or system that initiated the Transaction

sender

The service name that created the Transaction

details

Arbitrary detail information with values according to the specific Transaction

Find a Transaction by Persistent Key

One particular Transaction can be looked up by its identifying persistent key, the pKey. If the client has the pKey on hand a GET request to the Transaction resource with the pKey returns the single Transaction instance.

GET /transactions/1 HTTP/1.1
Host: localhost:8080

If the Transaction exists it is returned.

HTTP/1.1 200 OK
Content-Type: application/vnd.openwms.common.transaction-v1+json
Content-Length: 234

{
  "pKey" : "1",
  "description" : "Updated user [openwms]",
  "type" : "user.created",
  "createdByUser" : "openwms",
  "createDt" : "05-06-2025 23:00:58",
  "sender" : "uaa-service",
  "details" : {
    "username" : "openwms"
  }
}
Path Type Description

pKey

String

The persistent technical key of the Transaction

description

String

A human readable descriptive text of the Transaction

type

String

The defined transaction type or key

createdByUser

String

The human user who initiated the Transaction

createDt

String

When the Transaction has been created

sender

String

The service name that send the Transaction

details

Object

Arbitrary detail information of the Transaction

If the Transaction does not exist, the server responds with:

HTTP/1.1 404 Not Found
Content-Type: application/hal+json
Content-Length: 196

{
  "message" : "Transaction with key [UNKNOWN] does not exist",
  "messageKey" : "owms.common.transactions.notFoundByPKey",
  "obj" : [ "UNKNOWN" ],
  "httpStatus" : "404",
  "class" : "String"
}

Find all Transactions by Type

A client might be interested in searching for all Transactions of a specific type.

If Transactions for that type exist they are returned:

HTTP/1.1 200 OK
Content-Type: application/vnd.openwms.common.transaction-v1+json
Content-Length: 238

[ {
  "pKey" : "1",
  "description" : "Updated user [openwms]",
  "type" : "user.created",
  "createdByUser" : "openwms",
  "createDt" : "05-06-2025 23:00:58",
  "sender" : "uaa-service",
  "details" : {
    "username" : "openwms"
  }
} ]

Find all existing Transactions

To find all existing Transactions a client sends a HTTP GET request to the primary Transaction resource.

GET /transactions HTTP/1.1
Host: localhost:8080

An array of all Transactions is returned:

HTTP/1.1 200 OK
Content-Type: application/vnd.openwms.common.transaction-v1+json
Content-Length: 238

[ {
  "pKey" : "1",
  "description" : "Updated user [openwms]",
  "type" : "user.created",
  "createdByUser" : "openwms",
  "createDt" : "05-06-2025 23:00:57",
  "sender" : "uaa-service",
  "details" : {
    "username" : "openwms"
  }
} ]

If no Transactions exist the response remains empty:

HTTP/1.1 204 No Content

Create a Transaction

To create a new Transaction a client sends a HTTP POST request to the primary Transaction resource.

POST /transactions HTTP/1.1
Content-Type: application/vnd.openwms.common.transaction-v1+json
Content-Length: 91
Host: localhost:8080

{
  "description" : "The message text",
  "type" : "created",
  "sender" : "service-name"
}
Path Type Description

type

String

The defined transaction type or key

sender

String

The service name that send the Transaction

description

String

(Optional) A human readable descriptive text of the Transaction

If the Transaction can be created successfully, the server responds like:

HTTP/1.1 201 Created
Location: http://localhost:8080/transactions/25f8e3f5-3d48-4131-8720-d84a68c91862
Content-Type: application/vnd.openwms.common.transaction-v1+json
Content-Length: 230

{
  "pKey" : "25f8e3f5-3d48-4131-8720-d84a68c91862",
  "description" : "The message text",
  "type" : "created",
  "createDt" : "05-06-2025 23:00:58",
  "sender" : "service-name",
  "traceId" : "12a6abd7b8d0e993046c4bb6fe3b66c6"
}
Path Type Description

type

String

The defined transaction type or key

sender

String

The service name that send the Transaction

description

String

(Optional) A human readable descriptive text of the Transaction