Copyright © 2005-2021
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
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": "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 |
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 |
COMMON.BARCODE_NOT_FOUND |
The TransportUnit does not exist |
Verify the identifying attribute passed to the API |
COMMON.LOCATION_NOT_FOUND |
The requested Location does not exist |
Verify the identifying attribute passed to the API |
COMMON.LOCATION_GROUP_NOT_FOUND |
The requested LocationGroup does not exist |
Verify the identifying attribute passed to the API |
COMMON.TRANSPORT_UNIT_TYPE_NOT_FOUND |
The requested TransportUnitType does not exist |
Verify the identifying attribute passed to the API |
Resources
A overview of all used API resources with a description of their attributes. More information about the resource itself and the exposed functionality is mentioned in the chapters below.

Attribute | Description |
---|---|
pKey |
Unique identifier of the Product |
sku |
The Product’s SKU |
label |
Could be an identifying barcode label or RFID tag |
baseUnit |
The default UOM the Product is managed, i.e. |
description |
A descriptive text |
classification |
An arbitrary information to classify the Product, i.e. a hazardous product |
group |
An attribute to group products |
stockZone |
Where this Product should be stored in stock |
units |
Alternative UOMs this Product can be packaged, i.e. |
Attribute | Description |
---|---|
product |
The Product the PackagingUnit belongs to |
quantity |
The quantity of the Product this PackagingUnit contains |
length |
Current length of the PackagingUnit |
width |
Current width of the PackagingUnit |
height |
Current height of the PackagingUnit |
weight |
Current weight of the PackagingUnit |
message |
Some informational text stored with the PackagingUnit |
loadUnitDistribution |
Describes how many of this kind of PackagingUnits fit into the current LoadUnit |
Attribute | Description |
---|---|
piecesPerLoadUnitLayer |
How many PackagingUnits fit into one layer in a LoadUnit |
numberOfLoadUnitLayers |
How many layers of the PackagingUnit fit into a LoadUnit |
Attribute | Description |
---|---|
amount |
The actual amount of the unit of measure (UOM) |
unit |
The unit of the UOM |
Attribute | Description |
---|---|
messageNo |
An identifying number of the Message that can be used for translation |
messageText |
A descriptive message text |
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: 303
{
"_links" : {
"product-index" : {
"href" : "http://localhost:8080/v1/products/index"
},
"load-unit-index" : {
"href" : "http://localhost:8080/v1/load-units/index"
},
"packaging-unit-index" : {
"href" : "http://localhost:8080/v1/packaging-units/index"
}
}
}
A client application only needs to know about the agreed link names and follow the corresponding href
link to navigate to further
resources.
LoadUnit
A LoadUnit
is the thing that actually carries an amount of Products
. Mostly this is done with the abstraction of PackagingUnits
so
that a LoadUnit
carries multiple PackagingUnits
where each of those contains an amount of a Product
. A LoadUnit
can either be only
a virtual separation of a TransportUnit
or even a physical box or separated area on top of the TransportUnit
.
LoadUnit Index (load-unit-index)
The index with all possible operations on LoadUnits
can be retrieved with an GET
request:
GET /v1/load-units/index HTTP/1.1
Host: localhost:8080
The response lists all the operations with a name and the corresponding href link:
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 293
{
"_links" : {
"lu-divide" : {
"href" : "http://localhost:8080/v1/transport-unit?transportUnitBK=transportUnitBK&loadUnitType=loadUnitType&parts=4"
},
"lu-put-product" : {
"href" : "http://localhost:8080/v1/load-units/b65a7658-c53c-4a81-8abb-75ab67783f47"
}
}
}
Divide a TransportUnit into multiple LoadUnits (load-units-divide)
An existing TransportUnit
can be split or divided into multiple LoadUnits
in the simplest way by just giving the number of LoadUnits
to create on top of the TransportUnit
and the type of LoadUnit
.
POST /v1/transport-unit HTTP/1.1
Host: localhost:8080
Content-Type: application/x-www-form-urlencoded
transportUnitBK=4712&loadUnitType=EURO&parts=2
If the server has fulfilled the operation successfully the response is:
HTTP/1.1 201 Created
If the server could not process the request successfully because the TransportUnit
is already divided into multiple LoadUnits
the
response states this:
HTTP/1.1 409 Conflict
Content-Type: application/hal+json
Content-Length: 175
{
"message" : "The TransportUnit with the Barcode [4711] is already divided, try to add other LoadUnits instead",
"messageKey" : "already.exists",
"httpStatus" : "409"
}
Reserve a LoadUnit for a Product (lu-put-product)
LoadUnits
may contain different types of Products
or are limited to carry only one type of Product
- this is a matter of
configuration. To assign or reserve a LoadUnit
to a specific type of Product
a client can send a POST
request to request this
assignment. If the system is configured in the way that only same Products
are allowed on LoadUnits
, the server may reject the request
in case the LoadUnit
is already assigned or carries PackagingUnits
of a different type.
A client request to ask for a Product
assignment could look like this:
PUT /v1/load-units/1000 HTTP/1.1
Content-Type: application/json
Content-Length: 202
Host: localhost:8080
{
"links" : [ ],
"sku" : "ZS0002029",
"baseUnit" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1
}
}
If the server has successfully assigned the Product
to the LoadUnit
the response looks like:
HTTP/1.1 200 OK
If the request could not been processed successfully because the server denied the assignment, the response looks like:
HTTP/1.1 502 Bad Gateway
Content-Type: application/hal+json
Content-Length: 142
{
"message" : "The LoadUnit [1001] has already a Product [ZS0002029] assigned and cannot be loaded a second time.",
"httpStatus" : "502"
}
PackagingUnit
A PackagingUnit
represents an amount of a Product
. This is a physical pack of some amount of an article, like a pack of 100 screws or 1
gallon of motor oil. Using PackagingUnits
in warehouses is a benefit, even there is this extra resource that needs to be managed. A simple
warehouse could also be designed only with LoadUnits
on TransportUnits
without PackagingUnits
but in most projects it makes sense to
have an amount of PackagingUnits
within a LoadUnit
and perhaps multiple LoadUnits
on top of a TransportUnit
.
PackagingUnit Index (packaging-unit-index)
The index with all possible operations on PackagingUnits
can be retrieved with an GET
request to the root resource:
GET /v1/packaging-units/index HTTP/1.1
Host: localhost:8080
The response lists all the operations with a name and the corresponding href link:
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 645
{
"_links" : {
"packaging-units-create" : {
"href" : "http://localhost:8080/v1/transport-units/transportUnitBK/load-units/luPos/packaging-units?loadUnitType=loadUnitType"
},
"packaging-units-findontu" : {
"href" : "http://localhost:8080/v1/transport-units/transportUnitBK/load-units/packaging-units"
},
"packaging-units-findforproduct" : {
"href" : "http://localhost:8080/v1/packaging-units?sku=sku&amount=amount&sort=sort"
},
"packaging-units-findforproductinlg" : {
"href" : "http://localhost:8080/v1/packaging-units?productPKey=productPKey&locationGroupName=locationGroupName"
}
}
}
Create a new PackagingUnit (packaging-units-create)
A PackagingUnit
can be created and directly put into a LoadUnit
of a TransportUnit
. Therefor a client sends a POST
request with the
identifying information for the LoadUnit
and the required PackagingUnit
data to the server:
POST /v1/transport-units/4711/load-units/1/packaging-units?loadUnitType=EURO HTTP/1.1
Content-Type: application/json
Content-Length: 243
Host: localhost:8080
{
"product" : {
"links" : [ ],
"sku" : "ZS0002029"
},
"quantity" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1
},
"links" : [ ]
}
If the server has created and attached the PackagingUnit
successfully a 201-CREATED
is returned with a LOCATION
header to the
new resource:
HTTP/1.1 201 Created
Location: http://localhost:8080/v1/transport-units/4711/load-units/1/packaging-units/41cedebb-a28b-4d40-8841-68a0f31c3b61/
Find all PackagingUnits on a TransportUnit (packaging-units-findontu)
To find all PackagingUnits
in all LoadUnits
that are currently assigned to a particular TransportUnit
a client needs to query for the
secondary resources of the TransportUnit
→ LoadUnit
→ PackagingUnit
.
GET /v1/transport-units/4711/load-units/packaging-units HTTP/1.1
Host: localhost:8080
If the server has created and attached the PackagingUnit
successfully a 201-CREATED
is returned with a LOCATION
header to the
new resource:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1342
[ {
"product" : {
"links" : [ ],
"pKey" : "2",
"sku" : "ZS0002030",
"baseUnit" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1
},
"stockZone" : "A"
},
"quantity" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1000
},
"links" : [ ],
"length" : 15,
"width" : 12,
"height" : 10,
"weight" : {
"@class" : "org.openwms.core.units.api.Weight",
"unitType" : [ "org.openwms.core.units.api.WeightUnit", "G" ],
"magnitude" : 400
}
}, {
"product" : {
"links" : [ ],
"pKey" : "2",
"sku" : "ZS0002030",
"baseUnit" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1
},
"stockZone" : "A"
},
"quantity" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1000
},
"links" : [ ],
"length" : 15,
"width" : 12,
"height" : 10,
"weight" : {
"@class" : "org.openwms.core.units.api.Weight",
"unitType" : [ "org.openwms.core.units.api.WeightUnit", "G" ],
"magnitude" : 400
}
} ]
Find available PackagingUnits on a TransportUnit (packaging-units-findforproduct)
A client might want to find PackagingUnits
on a TransportUnit
that are available and not allocated by any other orders or tasks in order
to reserve them for allocation. Therefore the client sends a GET
request with the TransportUnit’s
identifier and the Product SKU
to
search for. The client may also limit the number of returned values by giving an amount
parameter and a sort
direction.
The request to the server may look like this:
GET /v1/transport-units/4711/load-units/packaging-units?sku=ZS0002029&amount=10&sort=DESC HTTP/1.1
Host: localhost:8080
The server responds with a list of entities currently not blocked in allocation:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1342
[ {
"product" : {
"links" : [ ],
"pKey" : "2",
"sku" : "ZS0002030",
"baseUnit" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1
},
"stockZone" : "A"
},
"quantity" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1000
},
"links" : [ ],
"length" : 15,
"width" : 12,
"height" : 10,
"weight" : {
"@class" : "org.openwms.core.units.api.Weight",
"unitType" : [ "org.openwms.core.units.api.WeightUnit", "G" ],
"magnitude" : 400
}
}, {
"product" : {
"links" : [ ],
"pKey" : "2",
"sku" : "ZS0002030",
"baseUnit" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1
},
"stockZone" : "A"
},
"quantity" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1000
},
"links" : [ ],
"length" : 15,
"width" : 12,
"height" : 10,
"weight" : {
"@class" : "org.openwms.core.units.api.Weight",
"unitType" : [ "org.openwms.core.units.api.WeightUnit", "G" ],
"magnitude" : 400
}
} ]
Find available PackagingUnits in a LocationGroup (packaging-units-findforproductinlg)
To search for PackagingUnits
of a given Product within a particular LocationGroup
a client could send a GET
request to the PackagingUnits
resource with the product to search for and the name of the LocationGroup
as request parameter. This is often useful to search for
available material in a warehouse.
The request to the server may look like this:
GET /v1/packaging-units?productPKey=2&locationGroupName=AISLE1 HTTP/1.1
Accept: application/vnd.openwms.packaging-unit-v1+json
Host: localhost:8080
Parameter | Description |
---|---|
|
The persistent identifier of the Product |
|
The unique name of the LocationGroup |
The server responds with a list of entities currently available for allocation and transportation:
HTTP/1.1 200 OK
Content-Type: application/vnd.openwms.packaging-unit-v1+json
Content-Length: 2012
[ {
"product" : {
"links" : [ ],
"pKey" : "2",
"sku" : "ZS0002030",
"baseUnit" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1
},
"stockZone" : "A"
},
"quantity" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1000
},
"links" : [ ],
"length" : 15,
"width" : 12,
"height" : 10,
"weight" : {
"@class" : "org.openwms.core.units.api.Weight",
"unitType" : [ "org.openwms.core.units.api.WeightUnit", "G" ],
"magnitude" : 400
}
}, {
"product" : {
"links" : [ ],
"pKey" : "2",
"sku" : "ZS0002030",
"baseUnit" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1
},
"stockZone" : "A"
},
"quantity" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1000
},
"links" : [ ],
"length" : 15,
"width" : 12,
"height" : 10,
"weight" : {
"@class" : "org.openwms.core.units.api.Weight",
"unitType" : [ "org.openwms.core.units.api.WeightUnit", "G" ],
"magnitude" : 400
}
}, {
"product" : {
"links" : [ ],
"pKey" : "2",
"sku" : "ZS0002030",
"baseUnit" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1
},
"stockZone" : "A"
},
"quantity" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1000
},
"links" : [ ],
"length" : 15,
"width" : 12,
"height" : 10,
"weight" : {
"@class" : "org.openwms.core.units.api.Weight",
"unitType" : [ "org.openwms.core.units.api.WeightUnit", "G" ],
"magnitude" : 400
}
} ]
The response contains links to comprising LoadUnits
and TransportUnits
, because the requested resource was of type application/vnd.openwms.packaging-unit-v1+json
.
If the Accept
header with the requested resource representation is omitted the server responds with a simple form without any links:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 2012
[ {
"product" : {
"links" : [ ],
"pKey" : "2",
"sku" : "ZS0002030",
"baseUnit" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1
},
"stockZone" : "A"
},
"quantity" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1000
},
"links" : [ ],
"length" : 15,
"width" : 12,
"height" : 10,
"weight" : {
"@class" : "org.openwms.core.units.api.Weight",
"unitType" : [ "org.openwms.core.units.api.WeightUnit", "G" ],
"magnitude" : 400
}
}, {
"product" : {
"links" : [ ],
"pKey" : "2",
"sku" : "ZS0002030",
"baseUnit" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1
},
"stockZone" : "A"
},
"quantity" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1000
},
"links" : [ ],
"length" : 15,
"width" : 12,
"height" : 10,
"weight" : {
"@class" : "org.openwms.core.units.api.Weight",
"unitType" : [ "org.openwms.core.units.api.WeightUnit", "G" ],
"magnitude" : 400
}
}, {
"product" : {
"links" : [ ],
"pKey" : "2",
"sku" : "ZS0002030",
"baseUnit" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1
},
"stockZone" : "A"
},
"quantity" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1000
},
"links" : [ ],
"length" : 15,
"width" : 12,
"height" : 10,
"weight" : {
"@class" : "org.openwms.core.units.api.Weight",
"unitType" : [ "org.openwms.core.units.api.WeightUnit", "G" ],
"magnitude" : 400
}
} ]
Product
The Product
is a representation of an article known and shipped within a warehouse. A Product
is just a definition but not the physical
article. In the real world a Product
exists in a number of items, dimensions, liters or other units. Hence a Product
is physically
always tied to an amount, see PackagingUnits
for more information.
Product Index (product-index)
The index with all possible operations can be retrieved with an GET
request:
GET /v1/products/index HTTP/1.1
Host: localhost:8080
The response lists all the operations with a name and the corresponding href link:
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 405
{
"_links" : {
"products-create" : {
"href" : "http://localhost:8080/v1/products"
},
"products-findall" : {
"href" : "http://localhost:8080/v1/products"
},
"products-findbysku" : {
"href" : "http://localhost:8080/v1/products?sku=ZS0002029"
},
"products-findbyskuanduom" : {
"href" : "http://localhost:8080/v1/products?sku=ZS0002029&uom=PC"
}
}
}
Find all Products (products-findall)
To retrieve a list of all existing Products
a client must send a GET
request to the server:
GET /v1/products HTTP/1.1
Host: localhost:8080
The response contains all existing Products
:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 517
[ {
"links" : [ ],
"pKey" : "1",
"sku" : "ZS0002029",
"baseUnit" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1
},
"stockZone" : "A",
"units" : [ "1 PC", "1 DOZ" ]
}, {
"links" : [ ],
"pKey" : "2",
"sku" : "ZS0002030",
"baseUnit" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1
},
"stockZone" : "A"
} ]
Find a Product by SKU (products-findbysku)
To find and return a Product
identified by its SKU a client needs to query the
resource by sku
as query parameter in a GET
request:
GET /v1/products?sku=ZS0002029 HTTP/1.1
Host: localhost:8080
The response contains either the Product
if it exists:
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 255
{
"pKey" : "1",
"sku" : "ZS0002029",
"baseUnit" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1
},
"stockZone" : "A",
"units" : [ "1 PC", "1 DOZ" ]
}
or returns with a 404-NOT FOUND
error response in case no Product
with the given SKU
exists:
HTTP/1.1 404 Not Found
Content-Type: application/hal+json
Content-Length: 115
{
"message" : "Product with SKU [UNKNOWN] does not exist",
"messageKey" : "not.found",
"httpStatus" : "404"
}
Find a Product by SKU and UOM (products-findbyskuanduom)
A Product
may exist in different measurement flavors. One Product
with one SKU
but packed in different packaging types.
For example, car tires with the SKU
= ZS0002029
may exist in packages of always one piece and additionally in packages with 3x4 pieces
(a Dozen). A client could be interested in finding the correct Product
by SKU
and UOM
by sending a GET
request with both as
request parameters:
GET /v1/products?sku=ZS0002029&uom=1+DOZ HTTP/1.1
Host: localhost:8080
If this Product
with such an UOM
exists, the server returns a 200-OK
with the Product
and all existing UOM
relations.
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 255
{
"pKey" : "1",
"sku" : "ZS0002029",
"baseUnit" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1
},
"stockZone" : "A",
"units" : [ "1 PC", "1 DOZ" ]
}
If the given UOM
is not a valid one, like in this example Camels
, the server responds with 404-NOT FOUND
:
HTTP/1.1 404 Not Found
Create one or more Products (products-create)
New Products
can be added to the catalog of existing Products
by sending a POST
request to the server with the details of each
Product
. Products
are often created by the ERP system, indirectly through the appropriate ERP Hostconnector, and it is not unusual that
this happens in a bulk operation with thousands of records at a time.
A request could look like this:
POST /v1/products HTTP/1.1
Content-Type: application/json
Content-Length: 241
Host: localhost:8080
[ {
"links" : [ ],
"sku" : "NEW_PRODUCT",
"baseUnit" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1
},
"units" : [ "8 PC", "1 DOZ" ]
} ]
If the server has successfully created the demanded Product
the response looks like:
HTTP/1.1 201 Created
Location: http://localhost:8080/v1/products/925fbcbc-0b20-4cb0-b6a5-4ca93f62215f/
Notice that the server sends back the LOCATION
header to the created Product
resource in case only one new Product
has been requested.
If multiple Products
have been created, the LOCATION
header is kept empty.
If the request could not been processed because of missing or invalid request data the server responds with:
HTTP/1.1 400 Bad Request
Content-Type: application/hal+json
Content-Length: 116
{
"message" : "Error on validation [baseUnit]",
"messageKey" : "core.validation.error",
"httpStatus" : "400"
}
Allocate Products
A demanded amount of a Product
can be reserved or allocated for picking or goods out. To do so, a client must call the allocation API to
get back an array of objects that contain the TransportUnit
, the LoadUnit
and available quantity of the Product
.
POST /allocation/transport-units HTTP/1.1
Content-Type: application/json
Content-Length: 183
Host: localhost:8080
{
"sku" : "ZS0002030",
"qty" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1000
}
}
The server responds with an array:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 270
[ {
"transportUnitBK" : "00000000000000004711",
"loadUnitPosition" : "1",
"sku" : "ZS0002030",
"qtyAllocated" : {
"@class" : "org.openwms.core.units.api.Piece",
"unitType" : [ "org.openwms.core.units.api.PieceUnit", "PC" ],
"magnitude" : 1000
}
} ]