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 Transportation 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.

General Terms and Definitions

The next subsections are valid for all entity interactions described in the rest of this document.

HTTP verbs

This RESTful API tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP verbs.

Verb Usage Idempotent

GET

Used to retrieve a resource

yes

POST

Used to create a new - not existing - resource (although called transient resource)

yes

PUT

Used to update an existing resource, including the whole resource in the request body (the resource is called a detached resource)

yes

PATCH

Used to update an existing resource, including partial updates (the resource to update is called a managed resource)

no

DELETE

Used to delete an existing resource

no

HTTP status codes

This RESTful API tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP status codes.

Status code Usage

200 OK

The request completed successfully. Details

201 Created

A new/transient resource has been created successfully. The resource’s URI is available from the response’s Location header. Details

204 No Content

An update to an existing resource has been applied successfully. Details

400 Bad Request

The request was malformed. The response body will include an error providing further information. Details

403 Forbidden

The requested resource was forbidden to be accessed by the currently authenticated user. Details

404 Not Found

The requested resource did not exist. Details

409 Conflict

Indicates that the request could not be completed due to a conflict with the current state of the target resource. Details

Hypermedia

TMS Transportation uses hypermedia links where resources include links to other resources. Responses are in Hypertext Application Language (HAL) format. These hyperlinks belong to the technical part of the resource representation and are grouped with the _links element. Users of the API should not create URIs themselves, and use hyperlinks for navigation only.

Resources

The domain model of the RESTful API consists of a couple of classes with simple datatypes and no explicit relationships between each other. One special implicit type is the Date type that defines the default date format if not otherwise requested by the consuming service.

rest model

TransportOrder

The main resource of the TMS Transportation module is the TransportOrder. A TransportOrder is used in automated warehouses to move TransportUnits between Locations. Automated warehouses means a Material Flow Controller (MFC, see Material Flow) uses TransportOrders to route and track the movements within the warehouse. In manual warehouse OpenWMS.org uses Movements to track this in a manually.

The attributes of the TransportOrder representation:

Attribute Description

persistentKey

A synthetic unique key that identifies TransportOrder. May be replaced with self-links in future.

transportUnitId

The unique identifier of the TransportUnit that is carried. May be replaced with a link in future.

priority

The priority of the TransportOrder is used to control the order of execution.

startDate

The timestamp when the TransportOrder has been started.

message

The last error message occurred according to the TransportOrder.

endDate

The timestamp when the TransportOrder has been ended.

state

The current state of the TransportOrder.

sourceLocation

The Location taken from the TransportUnit where the TransportOrder has been started.

targetLocation

The Location as destination of the TransportUnit.

targetLocationGroup

The LocationGroup as destination of the TransportUnit.

Interaction Model

Create a new TransportOrder

At least the Barcode of the TransportUnit that needs to be moved and the Target destination must be given to create a new TransportOrder. In this example we also pass the Priority of the TransportOrder in order to control the priority of execution. TransportOrders with a high priority might be started and executed before those with lower priority.

Request to move a TransportUnit to a Location

In this example we pass a Location string as Target. An unique identifier of a LocationGroup is accepted as well.

$ curl 'http://localhost:8080/v1/transport-orders' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{
  "pKey" : null,
  "barcode" : "4711",
  "priority" : "HIGHEST",
  "problem" : null,
  "state" : null,
  "targetLocation" : "ERR_/0000/0000/0000/0000",
  "targetLocationGroup" : "ERR_/0000/0000/0000/0000"
}'

If the TransportOrder has been created successfully, the server responds with http status code 201 and returns the URI of the created TransportOrder in the LOCATION header.

Response if created

HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Location: http://localhost:8080/v1/transport-orders/95899273-cc85-40e7-a64b-b8e91985d63a

The URI can be used to lookup the created TransportOrder by it’s persistent key. A GET request would look like this:

Lookup the created TransportOrder

$ curl 'http://localhost:8080/v1/transport-orders/825c58b9-0580-4544-9ac6-812595261b96' -i -X GET

and the server returns the representation of the created TransportOrder

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json;charset=UTF-8
Content-Length: 271

{
  "state" : "STARTED",
  "priority" : "HIGHEST",
  "sourceLocation" : "INIT/0000/0000/0000/0000",
  "targetLocation" : "ERR_/0000/0000/0000/0000",
  "targetLocationGroup" : null,
  "persistentKey" : "825c58b9-0580-4544-9ac6-812595261b96",
  "transportUnitBK" : "4711"
}

Fails to create a TransportOrder

The creation of a TransportOrder may fail for several reasons. At first the TransportUnit with the given Barcode may not exist. Or the Target destination is unknown. In both cases the server responds with a http status code 404 (Not Found):

HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 83

{
  "message" : "not.found",
  "messageKey" : "not.found",
  "httpStatus" : "404"
}

Changing TransportOrders

Created TransportOrders can be changed. The system allows to redirect or prioritize them under certain circumstances. For example redirection might only be possible if the TransportOrder did not already reached the final Target destination and is still active. Or prioritization is only allowed with well-known values for the Priority.

Redirect to a new Target

Existing and active TransportOrders can be redirected to a new Target. This redirection happens through an PATCH request where the API expects the partial representation of the TransportOrder as request body. Here an example request to redirect the TransportOrder with the given persistent key to a new Target.

$ curl 'http://localhost:8080/v1/transport-orders/21857c44-9a0c-4ba1-8c20-abbec081fd88' -i -X PATCH \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{
  "pKey" : "21857c44-9a0c-4ba1-8c20-abbec081fd88",
  "barcode" : "4711",
  "priority" : "HIGHEST",
  "problem" : null,
  "state" : null,
  "targetLocation" : "INIT/0000/0000/0000/0000",
  "targetLocationGroup" : "INIT/0000/0000/0000/0000"
}'

Change Priority

Changing the Priority of an TransportOrder is also requested with a PATCH request. The follow example shows a request to lower the Priority of an existing TransportOrder, identified by the given persistent key, to NORMAL. Notice that the TransportOrder does not need to be started yet.

$ curl 'http://localhost:8080/v1/transport-orders/18e2ba27-8563-4dc0-a240-ba8ef26b963e' -i -X PATCH \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{
  "pKey" : "18e2ba27-8563-4dc0-a240-ba8ef26b963e",
  "barcode" : "4711",
  "priority" : "NORMAL",
  "problem" : null,
  "state" : null,
  "targetLocation" : "ERR_/0000/0000/0000/0000",
  "targetLocationGroup" : "ERR_/0000/0000/0000/0000"
}'

If the request has been executed successfully, the server responds with a http status code 204

HTTP/1.1 204 No Content
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers

If the server does not accept the passed Priority level the response status is 400 (Bad Request),

HTTP/1.1 400 Bad Request
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 129

{
  "message" : "A priority level of UNKNOWN is not defined",
  "messageKey" : "core.invalid.parameter",
  "httpStatus" : "400"
}