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 TMS Routing 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.

Resources

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

These 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

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": "COMMON.LOCATION_GROUP_NOT_FOUND",
    "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

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
not.found	The requested resource has not been found	The resource does not exist anymore or has never existed. The resource identifier must be verified

Message Key

Description

Action

not.found

The requested resource has not been found

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

Route

Create a Route

Create a new Route resource with a HTTP POST request to the primary routes resource:

POST /v1/api/routes HTTP/1.1
Content-Type: application/json
Content-Length: 196
Host: localhost:8080

{
  "name" : "SRC_TRG_NEW",
  "description" : "Source -> Target",
  "sourceLocationGroupName" : "SOURCE GROUP",
  "targetLocationGroupName" : "TARGET GROUP",
  "key" : "NEW",
  "enabled" : false
}

If the resource has been created successfully, the server responds with:

HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Access-Control-Expose-Headers: Location
Location: http://localhost:8080/v1/api/routes/NEW

If a Route with the name already exists, the server signals a conflict:

HTTP/1.1 409 Conflict
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Access-Control-Expose-Headers: Location
Content-Type: application/hal+json
Content-Length: 119

{
  "message" : "Route with name [SRC_TRG] already exists",
  "messageKey" : "already.exists",
  "httpStatus" : "409"
}

Find a Route by PKey

An existing Route can be looked up with an HTTP GET request to the primary resource with the persistent identifier as path variable:

GET /v1/api/routes/709957655206 HTTP/1.1
Host: localhost:8080

If the Route exists the server responds with:

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/hal+json
Content-Length: 330

{
  "name" : "SRC_TRG",
  "description" : "Source -> Target",
  "sourceLocationName" : "STCK/0001/0001/0000/0000",
  "targetLocationName" : "STCK/0001/0002/0000/0000",
  "key" : "709957655206",
  "enabled" : true,
  "ol" : 0,
  "createDt" : "2025-03-19T06:35:43.275421000Z",
  "lastModifiedDt" : "2025-03-19T06:35:43.275421000Z"
}

otherwise an HTTP 404 NOT_FOUND is returned.

Find all Routes

To find all existing Routes a client sends an HTTP GET request to the primary routes resource without any other parameters.

GET /v1/api/routes HTTP/1.1
Host: localhost:8080

The response looks like:

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 3166

[ {
  "name" : "SRC_TRG",
  "description" : "Source -> Target",
  "sourceLocationName" : "STCK/0001/0001/0000/0000",
  "targetLocationName" : "STCK/0001/0002/0000/0000",
  "key" : "709957655206",
  "enabled" : true,
  "ol" : 0,
  "createDt" : "2025-03-19T06:35:43.018894000Z",
  "lastModifiedDt" : "2025-03-19T06:35:43.018894000Z"
}, {
  "name" : "REC_CONV",
  "description" : "Cartons coming from outside to the stock.",
  "sourceLocationName" : "STCK/0001/0001/0000/0000",
  "sourceLocationGroupName" : "REC_CONV",
  "targetLocationName" : "STCK/0001/0001/0000/0000",
  "targetLocationGroupName" : "FGRECEIVING",
  "key" : "709957655207",
  "enabled" : true,
  "ol" : 0,
  "createDt" : "2025-03-19T06:35:43.018894000Z",
  "lastModifiedDt" : "2025-03-19T06:35:43.018894000Z"
}, {
  "name" : "CONVCONV",
  "description" : "Cartons that should stay on the conveyor",
  "sourceLocationName" : "STCK/0001/0001/0000/0000",
  "sourceLocationGroupName" : "REC_CONV",
  "targetLocationName" : "STCK/0001/0001/0000/0000",
  "targetLocationGroupName" : "FGCONVEYOR",
  "key" : "889085346017",
  "enabled" : true,
  "ol" : 0,
  "createDt" : "2025-03-19T06:35:43.018894000Z",
  "lastModifiedDt" : "2025-03-19T06:35:43.018894000Z"
}, {
  "name" : "SHIPERR_",
  "description" : "Cartons from shipping to conveyor ",
  "sourceLocationGroupName" : "FGSHIPPING",
  "targetLocationName" : "STCK/0001/0002/0000/0000",
  "key" : "920761607535",
  "enabled" : true,
  "ol" : 0,
  "createDt" : "2025-03-19T06:35:43.018894000Z",
  "lastModifiedDt" : "2025-03-19T06:35:43.018894000Z"
}, {
  "name" : "CS1_OUT_",
  "description" : "Cartons of aisle 1 to out position",
  "sourceLocationGroupName" : "FGAISLE1",
  "targetLocationName" : "STCK/0001/0002/0000/0000",
  "key" : "11168458889",
  "enabled" : true,
  "ol" : 0,
  "createDt" : "2025-03-19T06:35:43.018894000Z",
  "lastModifiedDt" : "2025-03-19T06:35:43.018894000Z"
}, {
  "name" : "CS2_OUT_",
  "description" : "Cartons of aisle 2 to out position",
  "sourceLocationGroupName" : "FGAISLE2",
  "targetLocationName" : "STCK/0001/0002/0000/0000",
  "key" : "32391655610",
  "enabled" : true,
  "ol" : 0,
  "createDt" : "2025-03-19T06:35:43.018894000Z",
  "lastModifiedDt" : "2025-03-19T06:35:43.018894000Z"
}, {
  "name" : "FG__ERR_",
  "description" : "Cartons from anywhere in the flatgood area to the error location",
  "sourceLocationGroupName" : "FLATGOOD_AREA",
  "targetLocationName" : "STCK/0001/0002/0000/0000",
  "key" : "613429031593",
  "enabled" : true,
  "ol" : 1000,
  "createDt" : "2025-03-19T06:35:43.018894000Z",
  "lastModifiedDt" : "2025-03-19T06:35:43.018894000Z"
}, {
  "name" : "_NO_ROUTE",
  "description" : "No Route",
  "sourceLocationName" : "STCK/0001/0001/0000/0000",
  "key" : "956033651143",
  "enabled" : true,
  "ol" : 0,
  "createDt" : "2025-03-19T06:35:43.018894000Z",
  "lastModifiedDt" : "2025-03-19T06:35:43.018894000Z"
}, {
  "name" : "_DEFAULT",
  "description" : "Route All",
  "sourceLocationName" : "STCK/0001/0001/0000/0000",
  "key" : "222590552091",
  "enabled" : true,
  "ol" : 0,
  "createDt" : "2025-03-19T06:35:43.018894000Z",
  "lastModifiedDt" : "2025-03-19T06:35:43.018894000Z"
} ]

Update a Route

To change values on an existing Route, a client must send an HTTP PUT request to the identified resource with the updated Route representation in the request body:

PUT /v1/api/routes HTTP/1.1
Content-Type: application/json
Content-Length: 219
Host: localhost:8080

{
  "name" : "SRC_TRG_UPDATED",
  "description" : "Source -> Target (Updated)",
  "sourceLocationGroupName" : "SOURCE GROUP",
  "targetLocationGroupName" : "TARGET GROUP",
  "key" : "709957655206",
  "enabled" : false
}

If the server has updated the Route, the response contains the updated Route in the body:

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/hal+json
Content-Length: 335

{
  "name" : "SRC_TRG_UPDATED",
  "description" : "Source -> Target (Updated)",
  "sourceLocationGroupName" : "SOURCE GROUP",
  "targetLocationGroupName" : "TARGET GROUP",
  "key" : "709957655206",
  "enabled" : false,
  "ol" : 0,
  "createDt" : "2025-03-19T06:35:43.085555000Z",
  "lastModifiedDt" : "2025-03-19T06:35:43.085555000Z"
}

OpenWMS.org TMS: RESTful API (TMS Routing)