Copyright © 2005-2022
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
Resources
Representation Formats
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 |
---|---|---|
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 |
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: 231
{
"_links" : {
"shipping-order-index" : {
"href" : "http://localhost:8080/v1/shipping-orders/index"
},
"shipping-order-ui-index" : {
"href" : "http://localhost:8080/v1/ui/shipping-orders/index"
}
}
}
A client application only needs to know about the agreed link names and follow the corresponding href
link to navigate to further
resources.
ShippingOrder
A ShippingOrder
with its ShippingOrderPositions
represents a customer order that is received from an ERP system. Each order usually
consists of one or more positions where each position determines what Product
is ordered how many times. So the ShippingOrderPosition
is
the record that has the reference to ordered Product
and holds the qtyOrdered
(ordered quantity) information.
ShippingOrder Index
The index with all possible operations on a ShippingOrder
can be retrieved with a GET request:
GET /v1/shipping-orders/index HTTP/1.1
Host: localhost:8080
The response lists all the operations possible on ShippingOrders
with a name and the corresponding href link:
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 838
{
"_links" : {
"shipping-order-create" : {
"href" : "http://localhost:8080/v1/shipping-orders"
},
"shipping-order-findbypkey" : {
"href" : "http://localhost:8080/v1/shipping-orders/fd54ae26-a75a-4531-ae6f-f5012288b725"
},
"shipping-order-findbyorderid" : {
"href" : "http://localhost:8080/v1/shipping-orders?orderId=SO4712"
},
"shipping-order-findbypositionpkey" : {
"href" : "http://localhost:8080/v1/shipping-order-positions/fd54ae26-a75a-4531-ae6f-f5012288b726"
},
"shipping-order-updateorderpartially" : {
"href" : "http://localhost:8080/v1/shipping-orders/fd54ae26-a75a-4531-ae6f-f5012288b727"
},
"shipping-order-updatepositionpartially" : {
"href" : "http://localhost:8080/v1/shipping-order-positions/fd54ae26-a75a-4531-ae6f-f5012288b728"
}
}
}
Create a ShippingOrder
To create a ShippingOrder
a caller must simply do a HTTP POST
request to the API with the minimal information needed in the body of
the request:
POST /v1/shipping-orders HTTP/1.1
Content-Type: application/json
Content-Length: 838
Host: localhost:8080
{
"orderId" : "4712",
"customerNo" : "WALMART_EASTUS",
"startMode" : "AUTOMATIC",
"shippingType" : "FedEx",
"priority" : 5,
"latestDueDate" : "2024-02-16T22:05:36.096066867Z",
"startDate" : "2024-02-15T22:05:36.096018667Z",
"positions" : [ {
"pos" : "1",
"priority" : 5,
"product" : {
"sku" : "C000009"
},
"qtyOrdered" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1
},
"qtyCrossdock" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1
},
"details" : {
"IDOC_ID" : "0000B92F178"
},
"targetName" : "STOCK"
} ],
"details" : {
"ERP_ORDER_NO" : "SX0002039144"
}
}
Path | Type | Description |
---|---|---|
|
|
An unique identifier of the ShippingOrder to create |
|
|
A customer number or name |
|
|
Could be used to store the type of shipping or the delivery company |
|
|
How to start the ShippingOrder: MANUAL or AUTOMATIC |
|
|
The priority of the order to process |
|
|
The order must be finished not later then this point in time |
|
|
The earliest start or processing date of the order |
|
|
Some arbitrary details stored along the ShippingOrder |
|
|
An array of positions, must not be empty |
|
|
Unique identifier of the ShippingOrderPosition within the ShippingOrder |
|
|
The priority of the position to fulfill |
|
|
The expected Product |
|
|
The SKU of the expected Product |
|
|
The ordered quantity of the Product |
|
|
The quantity taken from cross docking |
|
|
Some arbitrary details stored along the position |
|
|
The target of the position |
If the request is correct and has been processed successfully the server returns a 200-OK
with the LOCATION
header to the placed
ShippingOrder
:
HTTP/1.1 201 Created
Location: http://localhost:8080/v1/shipping-orders/e374d35c-fb0f-4603-a1a8-a4e643755cc2/
Find ShippingOrders by State
The API offers to search for ShippingOrders
in particular order states. Therefor a client can pass multiple states as request parameters
to a GET
request to find all ShippingOrders
in one of these states. A client can also project and slice the returned representation.
Without any further ACCEPT
header, a full representation of a ShippingOrder
is returned, with ShippingOrderPositions
and Details
.
GET /v1/ui/shipping-orders?states=created%2CPROCESSED%2Cunknown HTTP/1.1
Host: localhost:8080
Parameter | Description |
---|---|
|
A list of states to search orders for. Supported states are: CREATED, AVAILABLE, PROCESSING, PROCESSED, COMMISSIONING, ON_TRUCK, FAILURE_WMS, FAILURE_TMS, COMPLETED |
If ShippingOrders
have been found that met the condition the server responds with 200-OK
:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 985
[ {
"pKey" : "ce8a9ca3-2fed-438f-bcc2-ed1e1966a8d4",
"orderId" : "4713",
"customerNo" : "WALMART_EASTUS",
"state" : "CREATED",
"startMode" : "AUTOMATIC",
"shippingType" : "FedEx",
"priority" : 5,
"latestDueDate" : "2024-02-16T22:05:37.152189Z",
"startDate" : "2024-02-15T22:05:37.152167Z",
"positions" : [ {
"orderPKey" : "ce8a9ca3-2fed-438f-bcc2-ed1e1966a8d4",
"orderId" : "4713",
"pKey" : "559c19ea-eef4-4117-8482-c5649f2e4458",
"pos" : "1",
"orderPositionState" : "PROCESSING",
"priority" : 5,
"product" : {
"sku" : "C000009",
"ol" : 0,
"pKey" : "c34fbfc7-5346-4f83-97a3-7c0a8f9e99cb"
},
"qtyOrdered" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1
},
"details" : {
"IDOC_ID" : "0000B92F178"
},
"targetName" : "HIGHBAY"
} ],
"details" : {
"ERP_ORDER_NO" : "SX0002039144"
}
} ]
By sending the ACCEPT
header application/vnd.openwms.shipping-order-v1-minimum+json
the server returns a ShippingOrder
representation
without ShippingOrderPositions
:
HTTP/1.1 200 OK
Content-Type: application/vnd.openwms.shipping-order-v1-minimum+json
Content-Length: 310
[ {
"pKey" : "ce8a9ca3-2fed-438f-bcc2-ed1e1966a8d4",
"orderId" : "4713",
"customerNo" : "WALMART_EASTUS",
"state" : "CREATED",
"startMode" : "AUTOMATIC",
"shippingType" : "FedEx",
"priority" : 5,
"latestDueDate" : "2024-02-16T22:05:37.152189Z",
"startDate" : "2024-02-15T22:05:37.152167Z"
} ]
Find a ShippingOrder by Persistent Key
A client may have the unique persistent ID of a ShippingOrder
on hand and want to retrieve the full representation of the ShippingOrder
including all ShippingOrderPositions
. Therefore a GET
request with the unique ID as path variable is sent to the server:
GET /v1/shipping-orders/cf235627-6a40-4589-999c-15c8eb92f959 HTTP/1.1
Host: localhost:8080
The server returns the representation of the ShippingOrder
or returns a 404-NOT_FOUND
in case the order does not exist.
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 981
{
"pKey" : "cf235627-6a40-4589-999c-15c8eb92f959",
"orderId" : "4714",
"customerNo" : "WALMART_EASTUS",
"state" : "CREATED",
"startMode" : "AUTOMATIC",
"shippingType" : "FedEx",
"priority" : 5,
"latestDueDate" : "2024-02-16T22:05:37.321276Z",
"startDate" : "2024-02-15T22:05:37.321258Z",
"positions" : [ {
"orderPKey" : "cf235627-6a40-4589-999c-15c8eb92f959",
"orderId" : "4714",
"pKey" : "e32da3e5-c971-4c7c-ab85-a42201441f7e",
"pos" : "1",
"orderPositionState" : "PROCESSING",
"priority" : 5,
"product" : {
"sku" : "C000009",
"ol" : 0,
"pKey" : "c41a4144-6ece-4839-ade7-6ccf8ea7420e"
},
"qtyOrdered" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1
},
"details" : {
"IDOC_ID" : "0000B92F178"
},
"targetName" : "HIGHBAY"
} ],
"details" : {
"ERP_ORDER_NO" : "SX0002039144"
}
}
Find a ShippingOrder by OrderId
A client may have the unique business key, the orderId
of a ShippingOrder
on hand and want to retrieve the full representation of the
ShippingOrder
including all ShippingOrderPositions
. Therefore a GET
request with the unique orderId
as path variable is sent to the
server:
GET /v1/shipping-orders?orderId=4714 HTTP/1.1
Host: localhost:8080
The server returns the representation of the ShippingOrder
or returns a 404-NOT_FOUND
in case the order does not exist.
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 981
{
"pKey" : "cac6179d-396d-4f62-9a08-f2801799af44",
"orderId" : "4714",
"customerNo" : "WALMART_EASTUS",
"state" : "CREATED",
"startMode" : "AUTOMATIC",
"shippingType" : "FedEx",
"priority" : 5,
"latestDueDate" : "2024-02-16T22:05:36.839255Z",
"startDate" : "2024-02-15T22:05:36.839233Z",
"positions" : [ {
"orderPKey" : "cac6179d-396d-4f62-9a08-f2801799af44",
"orderId" : "4714",
"pKey" : "cbf9ef1e-df74-4a1e-91ec-1ca306a6ea04",
"pos" : "1",
"orderPositionState" : "PROCESSING",
"priority" : 5,
"product" : {
"sku" : "C000009",
"ol" : 0,
"pKey" : "fd3b0f89-b519-44be-b099-8dab53dc3aea"
},
"qtyOrdered" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1
},
"details" : {
"IDOC_ID" : "0000B92F178"
},
"targetName" : "HIGHBAY"
} ],
"details" : {
"ERP_ORDER_NO" : "SX0002039144"
}
}