Copyright © 2005-2024

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 Tasks 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

owms.common.tasks.alreadyExists

The task exists unexpectedly

No further action possiblee

owms.common.tasks.notFoundByPKey

The task doesn’t exist

No further action possible

owms.common.tasks.alreadyStarted

The task is already started

No further action needed

owms.common.tasks.alreadyPaused

The task is already paused

No further action needed

owms.common.tasks.isPaused

The task is unexpected paused

Start the task again

owms.common.tasks.isNotPaused

The task is not paused

Pause the task first

owms.common.tasks.notActive

The task is not active

Start the task first

owms.common.tasks.alreadyFinished

The task has already being finished

No further action possible

Resources

A description of all used API resources.

package

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

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

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

Task

A Task is a human action that needs to be performed, it is persisted and has its own particular lifecycle.

Find a Task

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

GET /tasks/1000 HTTP/1.1
Host: localhost:8080

If the Task exists it is returned.

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

{
  "links" : [ {
    "rel" : "self",
    "href" : "http://localhost:8080/tasks/1000"
  } ],
  "ol" : 0,
  "pKey" : "1000",
  "taskId" : "T0000000001",
  "description" : "Test Task",
  "type" : "MANUAL",
  "state" : "CREATED",
  "startedAt" : "2024-09-10T22:06:08Z",
  "finishedAt" : "2024-09-10T22:06:08Z"
}
Path Type Description

links[]

Array

Hypermedia links to the resource itself and others

pKey

String

The persistent technical key of the Task

taskId

String

The unique business key

description

String

The descriptive text of the task

type

String

The task’s type must be supported by the processing engine

state

String

A lifecycle state the task resides in

startedAt

String

When the task has been started

finishedAt

String

When the task has been ended

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

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

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

Find all existing Tasks

To find all existing Tasks a client must send a HTTP GET request to the primary Task resource.

GET /tasks HTTP/1.1
Host: localhost:8080

An array of all Tasks is returned:

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

[ {
  "links" : [ {
    "rel" : "self",
    "href" : "http://localhost:8080/tasks/1000"
  } ],
  "ol" : 0,
  "pKey" : "1000",
  "taskId" : "T0000000001",
  "description" : "Test Task",
  "type" : "MANUAL",
  "state" : "CREATED",
  "startedAt" : "2024-09-10T22:06:08Z",
  "finishedAt" : "2024-09-10T22:06:08Z"
}, {
  "links" : [ {
    "rel" : "self",
    "href" : "http://localhost:8080/tasks/1001"
  } ],
  "ol" : 0,
  "pKey" : "1001",
  "taskId" : "T0000000002",
  "description" : "Simple Task",
  "type" : "MANUAL",
  "state" : "CREATED"
}, {
  "links" : [ {
    "rel" : "self",
    "href" : "http://localhost:8080/tasks/1002"
  } ],
  "ol" : 0,
  "pKey" : "1002",
  "taskId" : "T0000000003",
  "description" : "Started Task",
  "type" : "MANUAL",
  "state" : "ACTIVE",
  "startedAt" : "2024-09-10T22:06:08Z"
}, {
  "links" : [ {
    "rel" : "self",
    "href" : "http://localhost:8080/tasks/1003"
  } ],
  "ol" : 0,
  "pKey" : "1003",
  "taskId" : "T0000000004",
  "description" : "Paused Task",
  "type" : "MANUAL",
  "state" : "PAUSED",
  "startedAt" : "2024-09-10T22:06:08Z"
} ]

If no Tasks exist the response remains empty:

HTTP/1.1 204 No Content

Create a Task

To start a new Task a client must send a HTTP POST request to the primary Task resource.

POST /tasks HTTP/1.1
Content-Type: application/vnd.openwms.common.task-v1+json
Content-Length: 59
Host: localhost:8080

{
  "description" : "Get a coffee",
  "type" : "USERTASK"
}
Path Type Description

type

String

The type of task is a mandatory fields at creation

description

String

(Optional) descriptive text

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

HTTP/1.1 201 Created
Location: http://localhost:8080/tasks/e90a1802-a2dc-4004-bcd6-73a048e94b84/
Content-Type: application/vnd.openwms.common.task-v1+json
Content-Length: 296

{
  "links" : [ {
    "rel" : "self",
    "href" : "http://localhost:8080/tasks/e90a1802-a2dc-4004-bcd6-73a048e94b84"
  } ],
  "ol" : 0,
  "pKey" : "e90a1802-a2dc-4004-bcd6-73a048e94b84",
  "taskId" : "T0000000001",
  "description" : "Get a coffee",
  "type" : "USERTASK",
  "state" : "CREATED"
}
Path Type Description

type

String

The type of task is a mandatory fields at creation

description

String

(Optional) descriptive text

Modify a Task

Some fields of a Task resource can be modified after creation via the API. Therefore a client must send a HTTP PUT request with the complete Task representation in the request body.

PUT /tasks HTTP/1.1
Content-Type: application/vnd.openwms.common.task-v1+json
Content-Length: 53
Host: localhost:8080

{
  "pKey" : "1000",
  "description" : "Take a nap"
}

If the resource has been modified successfully the service responds:

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

{
  "links" : [ {
    "rel" : "self",
    "href" : "http://localhost:8080/tasks/1000"
  } ],
  "ol" : 0,
  "pKey" : "1000",
  "taskId" : "T0000000001",
  "description" : "Take a nap",
  "type" : "MANUAL",
  "state" : "CREATED",
  "startedAt" : "2024-09-10T22:06:09Z",
  "finishedAt" : "2024-09-10T22:06:09Z"
}

Start a Task

After a Task has been created it is typically started and executed at some point. To start a Task a client sends a HTTP POST request and adds the action as part of the URI:

POST /tasks/1001/start HTTP/1.1
Host: localhost:8080

If the Task has been started successfully the service responds:

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

{
  "links" : [ {
    "rel" : "self",
    "href" : "http://localhost:8080/tasks/1001"
  } ],
  "ol" : 0,
  "pKey" : "1001",
  "taskId" : "T0000000002",
  "description" : "Simple Task",
  "type" : "MANUAL",
  "state" : "ACTIVE",
  "startedAt" : "2024-09-10T22:06:08Z"
}

If the Task cannot be started, the server responds with an error and one of the defined exceptions.

Pause a Task

A started Task can also be changed to paused, to stop the execution.

POST /tasks/1002/pause HTTP/1.1
Host: localhost:8080

If the Task has been paused successfully the service responds:

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

{
  "links" : [ {
    "rel" : "self",
    "href" : "http://localhost:8080/tasks/1002"
  } ],
  "ol" : 0,
  "pKey" : "1002",
  "taskId" : "T0000000003",
  "description" : "Started Task",
  "type" : "MANUAL",
  "state" : "PAUSED",
  "startedAt" : "2024-09-10T22:06:08Z"
}

Resume a Task

Similar to start a Task a paused on can resumed again, to continue the execution.

POST /tasks/1003/resume HTTP/1.1
Host: localhost:8080

If the Task has been resumed successfully the service responds:

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

{
  "links" : [ {
    "rel" : "self",
    "href" : "http://localhost:8080/tasks/1003"
  } ],
  "ol" : 0,
  "pKey" : "1003",
  "taskId" : "T0000000004",
  "description" : "Paused Task",
  "type" : "MANUAL",
  "state" : "ACTIVE",
  "startedAt" : "2024-09-10T22:06:09Z"
}

Finish a Task

Finally a running Task can be finished

POST /tasks/1002/finish HTTP/1.1
Host: localhost:8080

If the Task has been finished successfully the service responds:

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

{
  "links" : [ {
    "rel" : "self",
    "href" : "http://localhost:8080/tasks/1002"
  } ],
  "ol" : 0,
  "pKey" : "1002",
  "taskId" : "T0000000003",
  "description" : "Started Task",
  "type" : "MANUAL",
  "state" : "FINISHED",
  "startedAt" : "2024-09-10T22:06:09Z",
  "finishedAt" : "2024-09-10T22:06:08Z"
}