PUZZLE REST interface (2.4.0-SNAPSHOT)

1. Release notes

  • In this version PUZZLE ignores the attribute heightOverhang in loading devices. A client can set a value and it is stored in the internal representation of a job, but PUZZLE does not evaluate this attribute in the computation of solutions
  • The version tag in the URLs has remained to v1 for version 2.0.x, due to the URLs of the endpoints has not changed. You can retrieve the installed version of the REST API through the /info endpoint

Changelog

Component Category Description
PUZZLE REST API 2.4.0-SNAPSHOT Dependency PUZZLE core version 50.0.0-SNAPSHOT.
Improvement Add new optional attribute OrderLine#loadingOrder.
PUZZLE Reporter Plugin New Plugin First release of the reporter plugin is available. The reporter plugin allows a client to request PUZZLE to compute a report for a solution.
PUZZLE REST API 2.3.0 Dependency PUZZLE core version 50.0.0-SNAPSHOT.
Dependency PUZZLE REST container version 4.4.0-SNAPSHOT
Documentation Fix error in documentation: Values provided in the attribute Solution#Position#orientation ranges from 1 to 12, not 0 to 11. Update resolution table.
Bug Now, PUZZLE does not add undocumented parameters. Now, PUZZLE will return exactly the parameter provided by the client.
Bug The validation allows value 0 for the maxLoadWeight of a loading device. Fixed: Validation fails if maxLoadWeight is set to 0.
Bug PUZZLE has accepted JSON objects that contains multiple attributes with the same name. Fixed: PUZZLE will not accept such JSON objects any longer and will stop processing with an error
Documentation Added description of the item orientation in positions of a solution.
Documentation Add missing value range annotations in the structure of the response of POST /jobs.
Documentation Add and fix description of the attributes orientation and immutable of a position of a solution in the response of GET /jobs/{jobId}.
Documentation Added default units to data object documentation.
Improvement PUZZLE now logs any received HTTP request body, if the log level is set to debug.
Documentation Document parameter Search.ExpirationTime.
PUZZLE REST API 2.1.0 Bug PUZZLE adds undocumented parameters to the attribute parameters of the JSON representation of a job, after PUZZLE has computed solutions for this job. Resolved: PUZZLE now omit most of them.
Dependency PUZZLE core version 48.0.0.
Dependency PUZZLE REST container version 4.1.0
PUZZLE REST API 2.0.0 Improvement Rename attributes in representation of solutions: renamed attributes loadingDevice to loadingDeviceNumber and orderLine to orderLineNumber. [Breaking Change]
Bug If an error occurs while PUZZLE is computing the solutions of a job, PUZZLE will never change the state of the job from SUBMITTED to DONE. New behavior: In case of such an error PUZZLE changes the state to DONE and adds the error message to the the metadata of the job.
Improvement Add new endpoint to provide the memory usage of this PUZZLE instance. PUZZLE provides the used memory, the free memory and the maximum possible used heap memory as well as the number of jobs stored by this PUZZLE instance.
Improvement Add new attributes to metadata, to provide the messages of errors that occurred while PUZZLE computes solutions.
Bug The summaries for a job has returned an error, if PUZZLE has created a solution with loadingDeviceNumber set to null. For such a solution, PUZZLE now sets the loadingDeviceNumber to the empty string and does not return an error.
Improvement The picklists now contains the attribute loadingDeviceNumber which contains the loadingDeviceNumber of the used solution.
PUZZLE REST API 1.0.0-beta Improvement Semantic and representation of loading devices has changed: length, width and height of a loading device always describe the available load space, NOT the dimensions of the loading device itself. [Breaking Change]
Improvement The type of the loading device is now determined from the attribute type only, not from the combination of the attributes type and loadingDeviceType. Attribute type now contains the specific type of the loading device (in previous version, the attribute loadingDeviceType has contained the specific type). [Breaking Change]
Improvement Client can specify a carton by outer dimensions. If both, (inner) dimensions and outer dimensions are given, the (inner) dimensions always overrides the outer dimensions. For the conversion of inner and outer dimensions, a client must have set the attribute materialThickness. The client must therefore always specify the attribute materialThickness for a box.
Improvement Attribute carrierHeight represents the height of the pallet itself.
Improvement Attributes lengthOverhang and widthOverhang are optional attributes. If not provided by a client, PUZZLE initializes them with 0.
Improvement Client can provide more than one loading device in a job. PUZZLE considers only the first loading device, all further loading devices are ignored yet.
Improvement The client can now also request the validation of a job in state VALID.
Improvement The Metadata contains the duration until expiration of the job in seconds in the attribute timeIntervalUntilExpiration.
Improvement Summaries contains the number of the loading device used for a solution in the attribute loadingDeviceNumber.
Improvement PUZZLE now always returns error messages as JSON objects with the attributes errorMessage, errorClass and additionalInformation.
Improvement PUZZLE response with information about the running PUZZLE instance for a GET request to /info
Improvement PUZZLE can send CORS header. This feature must be activated by setting Rest.useCorsHeader=true in the configuration file puzzle.parameter. PUZZLE reads the value of the Access-Control-Allow-Origin HTTP header from the parameter Rest.allowOrigin from the same file.
Bug PUZZLE returns JSON parsing error messages with HTTP status code 400, not HTTP status code 422.
Bug Attribute maximumLoadWeight is renamed to maxLoadWeight. [Breaking Change]
Bug If attribute type of a loading device has value box, PUZZLE has returned an error.
Bug POST /jobs returns a JSON object with attribute jobId instead of directly returning the value of jobId.
Removed Support for container postponed, hence loading device types "TWENTY_FEET" ,"FOURTY_FEET","FOURTY_FIVE_HC", "FOURTY_FIVE_PW" and "FIFTY_THREE_HC" are removed.
Dependency PUZZLE core version 47.0.0.
Dependency PUZZLE REST container version 4.0.4.
Documentation Added two examples for jobs, one for a job using a pallet, one for a job using a carton.
Documentation New structure of documentation. Description of HTTP Endpoints consolidated in section HTTP Requests and new sections describing the data objects, the interaction with PUZZLE, the error handling and release notes are added. General description renamed to Introduction
Documentation Description of plugins is structured in a table
Documentation Figures of state machines are updated
Documentation Description of parameters is added
Documentation Description of HTTP Requests now contains response samples for HTTP status codes 400, 404 and 500 and a description of preconditions
Documentation Description of extension keys is added
Documentation pallet shows how to add a customerId` to a job
Documentation Keys and values of parameters must always be strings. This concerns the endpoints POST /jobs and PUT /jobs/{jobId}
Documentation Example for POST /jobs/{jobId}/validation with HTTP status code 200 is fixed and example for carton example is added

2. Introduction

The PUZZLE REST interface offers an API for the PUZZLE optimization program in form of HTTP Requests. PUZZLE performs a 3D load optimization for packing or palletization tasks or jobs. A client describes a task by providing and posting a JSON representation of a job. After data validation and upon request, PUZZLE computes solutions from the given order, the available loading devices and the parameters within the job. Computed solutions include the chosen loading device and a series of positions referring to orderlines of the given order. After computation, a client can retrieve solutions in multiple representations and level of detail:

  • a detailed JSON representation including coordinates for all positions,
  • a summary with basic data for every computed unit load or
  • a pick list with item quantities for every load.

Plug-Ins are available for additional, graphical representations of solutions.

3. Data Objects

The following explanations contain a description of the JSON objects that are used to transfer data between a client and PUZZLE.

Job

The data object required for a load optimization is called a job. A job contains any data PUZZLE needs to know to perform computations. A job encloses data of a single order including its order lines and the corresponding item master data, data for loading devices such as cartons or pallets and parameter values used to influence the way PUZZLE optimizes. Once a job is computed by PUZZLE, it will "contain" the results from the optimization. These results are called solutions.

Order

A job contains exactly one order. The order describes a set of physical items and their quantities that PUZZLE shall place in (or upon) loading devices. An order has an orderNumber and contains a set of orderLines with at least one entry.

Orderlines

An order contains one or more orderLines. Each entry in the list of orderlines has a unique orderLineNumber, a maximum quantity and the master data describing the ordered item or stock keeping unit (SKU). During optimization, PUZZLE will not exceed the given quantity for any entry in the list of orderlines.

The attribute loadingPriority denotes the sequence (order) in which PUZZLE consider order lines. PUZZLE divides the Orderlines into groups, each containing all Orderlines with the same value for the attribute 'loadingPriority'. PUZZLE considers these groups in ascending order of their values for the 'Order' attribute. OrderLines with the value null for the attribute loadingPriority can be set at any time PUZZLE may omit the attribute loadingPriority in JSON representations of a Job. It will always be present if the value of loadingPriority is not null.

Order Item

An order item describes the physical properties of a SKU for PUZZLE. An order item is of cubic shape. A client must provide an identifier, outer dimensions and a gross weight value for it. With default settings, PUZZLE will place items only with their height vertical upon the base of the loading device. In case other orientations are permitted, these permissions must be given from the client side by setting optional attributes explicitly.

Attribute Value Format Description Default Unit
number string Client chosen alphanumeric identifier for an item or a SKU.
name string Item name, this is a free text description.
group string Optional group identifier of the item. Several items may belong to the same group.
length integer Item length. milimeter
width integer Item width. milimeter
height integer Item height. milimeter
grossWeight integer Total weight of the item or SKU including packaging. gram
maxWeightOnTop integer Maximum cumulated weight on top of the item. gram
lengthVerticalPermitted boolean If true, the item may be placed with its length perpendicular to the base of the loading device. false
widthVerticalPermitted boolean If true, the item may be placed with its width perpendicular to the base of the loading device. false
heightVerticalPermitted boolean If true, the item may be placed with its height perpendicular to the base of the loading device. true

An order may contain the same orderItem data more than once.

Loading Devices

A Loading device primarily describes the available space and the permitted maximum load weight for the optimization. PUZZLE supports a variety of loading devices such as different pallet and carton types. Dimensions of any loading device are not fixed and can be initialized with required values. A job may contain one or more loading devices from which PUZZLE can choose. A loading device is the abstraction of a real loading aid and allows a client to describe all supported cartons or pallets in a similar manner. Loading devices have the following attributes in common:

Attribute Value Format Description Unit
type string See below for a detailed explanation and permitted type values
number string A unique loading device identifier within a job. PUZZLE will use the given number as a reference in solutions.
name string A free text name of the loading device
length integer Length of the available load space. For cartons this is the inner length, for a pallet this is the pallet length. milimeter
width integer Width of the available load space. For cartons this is the inner width, for a pallet this is the pallet width. milimeter
height integer Height of the available load space. For cartons this is the inner height, for a pallet this is the maximum stacking height on top of the pallet. milimeter
lengthOverhang integer Optional overhang along the length. A negative value will lead to a load underhang. milimeter
widthOverhang integer Optional overhang along the width. A negative value will lead to a load underhang. milimeter
maxLoadWeight integer The maximum permitted load weight. gram
emptyWeight integer The empty or tare weight of the loading device itself without any load. gram

Loading Device Type

Each loading device must have a particular type value. PUZZLE will use the supplied value to identify if the given loading device is a pallet or carton. The type also specifies the graphics PUZZLE will provide in a HTML, PNG or PDF. Multiple loading devices of a job may have the same type attribute value.

The type value must be one of the following:

Type Value Description
carton type carton description
FEFCO0200 FEFCO 0200 slotted type box without lid.
FEFCO0201 FEFCO 0201 regular slotted box.
FEFCO0420 FEFCO 0420 folder type box.
FEFCO0426 FEFCO 0426 folder type box.
FEFCO0427 FEFCO 0427 folder type box.
FEFCO0470 FEFCO 0470 folder type box.
pallet type pallet description Default length x width x carrier height in [mm]
AUS1_PAL Australian standard pallet. 1165 x 1165 x 160
AUS2_PAL Australian standard pallet. 940 x 940 x 160
BLOCK_PAL A simple block pallet 1200 x 800 x 144
CHEP_AUTO_PAL CHEP-style automotive pallet. 1200 x 1000 x 144,
CHEP_48X40_PAL CHEP-style 48 x 40 inch pallet. 1219 x 1016 x 124
CHEP_48X40_STRINGER_PAL CHEP-style 48 x 40 inch stringer pallet. 1219 x 1016 x 123
CHEP_48X42_PAL CHEP-style 48 x 42 inch pallet. 1219 x 1067 x 127
CHEPA_PAL CHEP-style automotive 4-way half pallet. 1000 x 600 x 144
CP1_PAL CP 1 pallet for the chemical industry. 1200 x 1000 x 138
CP2_PAL CP 2 pallet for the chemical industry. 1200 x 800 x 138
CP3_PAL CP 3 pallet for the chemical industry. 1140 x 1140 x 138
CP4_PAL CP 4 pallet for the chemical industry. 1300 x 1100 x 138
CP5_PAL CP 5 pallet for the chemical industry. 1140 x 760 x 138
CP6_PAL CP 6 pallet for the chemical industry. 1000 x 1200 x 156
CP7_PAL CP 7 pallet for the chemical industry. 1100 x 1300 x 156
CP8_PAL CP 8 pallet for the chemical industry. 1140 x 1140 x 156
CP9_PAL CP 9 pallet for the chemical industry. 1140 x 1140 x 156
CUSTOM_PAL A custom pallet. It will be drawn like a EURO_PAL.
DUSS1_PAL EUR 6 Euro norm pallet. A small 4-way window pallet. 800 x 600 x 144
DUSS2_PAL Düsseldorfer pallet. 800 x 600 x 160
DUSS3_PAL Düsseldorfer half pallet. 600 x 800 x 166
EURO_PAL EUR 1 Euro norm pallet. 1200 x 800 x 144
EURO2_PAL EUR 2 Euro norm (industry) pallet. 1200 x 1000 x 144
US_42X42_PAL US 42 x 42 inch pallet. 1067 x 1067 x 139
US_48X40_D8_PAL US 48 x 40 inch GMA-type pallet with 8 deck boards. 1219 x 1016 x 152
US_48X40_PAL US 48 x 40 inch GMA-type pallet with 7 deck boards. 1219 x 1016 x 152
US_48X48_WNG_PAL US 48 x 48 inch winged pallet. 1219 x 1219 x 133

Cartons

Material Thickness

Any carton has a mandatory materialThickness value. The value specifies the cardboard thickness (or strength) and PUZZLE uses the materialThickness for the conversion between inner and outer dimensions.

Outer Dimensions

Whenever inner dimensions for length, width and height are supplied, PUZZLE will use them together with the type (and the associated cardboard folding) and the given material thickness value to compute the outer dimensions. Specifying a carton using inner dimensions is the recommended way. Nevertheless, a client can specify the outer dimensions outerLength, outerWidth and outerHeight for a carton, omit the inner dimensions and let PUZZLE compute inner dimensions using the given carton type and the material thickness.

Load Underhang

A carton cannot have a load overhang. However, space can be left empty by supplying negative values for overhangLength and or overhangWidth. Such load underhang is always symmetrical and counts individually for each affected side. For example, if a client specifies a length overhang of -10 (mm), PUZZLE does not place any order item closer than 10 mm to the left and 10 mm to the right to the carton sides. The same semantic holds for width overhang. A positive overhang value is not permitted for cartons.

Carton Attribute Interrelations

The following figures display the interrelations between the properties of a carton.

Carton definition using inner dimensions.
The blue dashed lines indicate the given inner dimensions.
Carton definition using outer dimensions.
The blue dashed lines indicate the computed inner dimensions.

Pallets

Carrier Height

For any pallet, the client must provide a value for the height of the pallet itself. This is the carrierHeight value.

Outer Dimensions

The load space above the pallet cannot be specified using outer dimensions. Given width and length attributes define the width and length of the pallet. The height value defines the maximum permitted stacking height upon the pallet.

Load Overhang

A client can provide optional values for permitted load over- or underhang along the length or the width of the pallet by supplying positive (overhang) or negative (underhang) values for lengthOverhang and or widthOverhang.

Pallet Attribute Interrelations

The following figure displays the interrelations between the properties of a pallet.

Pallet definition using inner dimensions.
The blue dashed lines indicate the given inner dimensions.
The grey dashed lines indicate the effect of supplied overhang values.

Parameters

Parameters are used to influence the PUZZLE load optimization. Parameters are key-value pairs (both strings) stored in the parameters attribute of the job. PUZZLE uses default values for each parameter. A client can override any default value by explicitly setting a parameter value. Only the following parameters are designed to be set explicitly by a client. Setting undocumented parameters may result in undefined behavior.

PUZZLE returns exactly the parameters that are explicitly set by the customer in the representation of the job data.

Parameter Name Description Default Value
Search.SolutionCount The maximum amount of solutions that PUZZLE shall compute for a job. Note that this is a maximum value and PUZZLE may provide fewer solutions. 1
Search.MaxIterations Upper limit for the iteration counter of the PUZZLE optimizer. 10000
SpaceModel.WeightDistributionTest Toggles the weight distribution test on or off. If switched on, PUZZLE will verify that no position will exceed the maxWeightOnTop payload capability of any item below. PUZZLE uses an approximation algorithm for weight distribution. true
SpaceModel.MinimumStability A percentage value that controls the required stability value for any position of an order item. The higher the value, the more support and overlap with other items is required for a position. 70
Optimizer.UseProxyItems If set to true, the client PUZZLE allows the internal grouping of elements with similar dimensions. PUZZLE will resolve this internal grouping before returning solutions. This parameter is not related to the "group" attribute of an order item. false
Search.ExpirationTime Limits the number of virtual seconds that PUZZLE can optimize a job. PUZZLE uses a virtual notion of time to be platform-independent. The duration of a virtual second corresponds approximately to a real second. The value must be a positive integer or 0. If this attribute is set to 0, PUZZLE can optimize the job for an unlimited time. 0

Solutions

A solution contains the following data.

Attribute Value Format Description
id integer A job unique solution identifier generated by PUZZLE.
positions Object Array An array of position objects including type, orderline, x, y, z coordinate and item orientation.
remainder Object Array An array of remainder orderlines including orderlineNumber and remaining quantity.

For every job, PUZZLE will provide at least one solution. If no order items of a job fit in a loading device, the positions array of the solution is an empty array and the remainder is equal to the order lines provided by the client.

Every solution is a variant to pack item(s) of an order onto a loading device. Different variants may have different sets of packed items, but each solution uses the same loading device.

Item Orientation

The orientation attribute of a position is a bit-coded integer value that encodes:

  • which dimension PUZZLE has placed vertical to the pallet or the bottom of the carton
  • and the degree of counterclockwise rotation about this vertical dimension

The following table shows the resolution of the possible values of the orientation attribute:

value Which dimension is vertical to the pallet or the bottom of the carton Degree of counterclockwise rotation about the vertical dimension
1 height 0
2 height 90
3 height 180
4 height 270
5 width 0
6 width 90
7 width 180
8 width 270
9 length 0
10 length 90
11 length 180
12 length 270

Extension

The optional extension provides a flexible way to pass and retrieve additional data to and from PUZZLE. Extensions are key value maps. Keys and values are of type string. The following data objects offer an optional extension:

  • order
  • orderItem
  • each entry in the orderLines
  • each entry in loadingDevices
  • each solution entry
  • each position entry within a solution

PUZZLE itself uses this mechanism to transfer additional data between different components. To prevent extension data overrides, a client should use a client specific prefix to avoid key name conflicts when using extensions. Key "myCompanyName.customerId" with value "myCustomerId" is an example for a client side extension entry in an order.

Extension keys for client usage

The following extension keys are reserved to set color values for order items and loading devices.

Extension Data Object Key Name Description Format Sample Value
orderItem Renderer.OrderItem.itemColorFront Individual item front color. string with format "#rrggbb" "#00ff00" for green.
orderItem Renderer.OrderItem.itemColorSide Individual item side color. string with format "#rrggbb" "#ffff00" for yellow.
orderItem Renderer.OrderItem.itemColorTop Individual item top color. string with format "#rrggbb" "#0000ff" for blue.
orderItem Renderer.OrderItem.color Color value of an item. string with format "#rrggbb" "#ff0000" for red.
loadingDevice Renderer.LoadingDevice.loadingDeviceColor Color value of a loading device. string with format "#rrggbb"

The given color values will be recognized by PUZZLE plug-ins when rendering graphics or creating reports. PUZZLE evaluates extensions independently of the aggregation relationships between parts of the job. An extension entry within the order will not be written to the orderLine extension automatically.

4. The Job State Machine

The objective of this section is to provide an understanding of the interaction between a client and PUZZLE. Section "HTTP Requests" describes the technical details of the interaction steps.

Basic Interaction

From the client's point of view, the following state machine shows the basic interaction between a client and PUZZLE.

State machine of the basic interaction between a client and PUZZLE

Create

As first step, a client creates a job by sending a JSON representation of a job to PUZZLE. PUZZLE creates a new job with the data from the JSON and returns a unique ID for the newly created job, referred to as the jobId. The state of every newly created job is CREATED.

A client must provide the jobId in all subsequent steps of interaction with PUZZLE to specify the job.

PUZZLE does not store jobs permanently. Therefore, a client must resend jobs after restarting PUZZLE and PUZZLE can return a different jobId for the same JSON representation.

The successful creation of a job does not include validation of the semantic constraints for the data in the job.

Validate

As a second step, a client requests such a validation of semantic constraints. You can do this by request PUZZLE to validate the job.

PUZZLE then verifies predefined semantic constraints about the data in the job. If the job's data does not violate any of the semantic constraints, PUZZLE changes the state of the job to VALID.

If the data of the job violates constraints, PUZZLE keeps the state of the job on CREATED.

Compute

For a valid job, a client requests PUZZLE to compute solutions for a job. PUZZLE indicates acceptance of the request by changing the state of the job to SUBMITTED.

PUZZLE internally manages a queue of jobs for which it should compute solutions, and processes this queue in an unpredictable order, depending on available resources and licensed number of PUZZLE cores.

Wait for state DONE

After PUZZLE has computed solutions for a job, PUZZLE changes the state of this job to DONE. To detect this change in the state of the job, a client must periodically requests the job's metadata.

Retrieve Solutions

If the state is DONE, a client can retrieve representations of a job's solutions.

PUZZLE creates the representations on a per-request basis. PUZZLE provides overview statistics for all solutions of a job and picklists for all solutions of a job. Further representations are available via plugins.

Additional Interaction

Three steps are available to the client for additional interaction with PUZZLE: Abort computation, replace a job as a whole and delete a job. The following state chart adds two optional steps to the basic interaction: Abort computation and replace a job as a whole.

The steps abort the computation and replace a job extends the state machine of the basic interaction.

Replace a job

A client can replace a job as a whole in any state except SUBMITTED. After replacing a job, the state of the job is always CREATED. You can replace the data of a job to resolve violations of constraints.

Abort computation

A client can revoke the request to compute solutions, by aborting the computation of a job. Then PUZZLE reset the job to state VALID and deletes all computed data for the job.

Delete

Further, a client can explicitly delete a job in any state. If a client deletes a job in the state SUBMITTED, PUZZLE does automatically abort the computation of the job and then continue with the deletion of the job.

Automatic cleanup of unused jobs

PUZZLE automatically removes jobs that are no longer used. Therefore, PUZZLE manages an expirationTimestamp for each job, which is the earliest point in time at which PUZZLE automatically deletes the job. PUZZLE automatically deletes jobs in any state except state SUBMITTED.

If a job is not used before its expirationTimestamp expires, PUZZLE irrevocably deletes the job automatically at any time after the expirationTimestamp expires. The expirationTimestamp is available in the job's metadata.

Every HTTP Request, with the exception of retrieving the job's metadata, prolong the expirationTimestamp of a job. PUZZLE prolongs the expirationTimestamp after it has computed solutions for that job. A client can explicitly prolong the expirationTimestamp of a job.

5. Plugins

Plugins extends the functionality of PUZZLE. Currently, there are two types of plugins: additional representations and importer. You must license plugins separately. The following table lists all available plugins.

Name Description Documentation
Overview Image Plugin Create an image of all the solutions in a job. Documentation
HTML Export Plugin Create an interactive HTML 5 document of all the solutions in a job. Documentation
KPI Plugin Compute key performance indices for a job. Documentation
Excel Import Plugin Import jobs from a Microsoft Excel workbook. Documentation
Best-Fit Plugin This plugin provides the Best-Fit optimization mode and provides an own REST API for a clients. Documentation
Reporter Plugin Generate reports for solutions. Documentation

6. Errors

If an error occurred, PUZZLE responses to a client with a HTTP status code and a JSON object as the response body that contains information about the error. The body consists of a JSON object with three attributes: errorMessage contains a description of the error and errorClass contains the full-qualified name of the error (java exception). The attribute additionalInformation contains more information about the error in some cases.

If a defined error of the HTTP protocol occurs, PUZZLE returns the HTTP status code as defined in the HTTP protocol.

For other errors, the following rules applies.

Description HTTP status code
Client sent malformed JSON and PUZZLE cannot extract job data from the JSON 400
Client request an non-existing job and Client provide job id in the correct format 404
Any other error 500

Error defined in the HTTP Protocol

There are many defined errors in the HTTP, for example, a client requests a non-existent URL. If an error defined in the HTTP protocol occurs, PUZZLE converts the error to the structure described above. PUZZLE responses with the HTTP status code as defined in the HTTP protocol.

For example, if you request an URL that does not exists, such as a jobId in an incorrect format (/puzzle/api/v1/jobs/2ab), PUZZLE responses with HTTP status code 404 and the following body:

    {
      "errorMessage": "HTTP 404 Not Found",
      "additionalInformation": "",
      "errorClass": "javax.ws.rs.NotFoundException"
    }

For the url /info PUZZLE only supports the GET HTTP method. When you request for an POST to the url /info, PUZZLE responses with HTTP status code 405 and the following body

    {
      "errorMessage": "HTTP 405 Method Not Allowed",
      "additionalInformation": "",
      "errorClass": "javax.ws.rs.NotAllowedException"
    }

Unexpected error occurred

If an unhandled error occurred in PUZZLE, PUZZLE responses with HTTP status code 500, the attribute errorMessage contains the message of the error, the attribute additionalInformation contains the stack trace of the error and the attribute errorClass contains the full-qualified name of the unhandled java exception. In this case, please contact the PUZZLE team.

If a client request violates a precondition, PUZZLE also responses with HTTP status code 500. Examples of this case are given in section 7.

Error occurred while PUZZLE computes solutions

PUZZLE computes solutions for a job asynchronous. Therefore, if an error occurred while computing solutions, PUZZLE cannot return the error message directly to the client. In this case, PUZZLE stores the error message in the attribute errorMessage in the metadata and sets the attribute errorOccurred to true. If no error occurred, errorOccurred is set to false and errorMessage is the empty string.

Enable more detailed logging

If you encounter an unexpected error, you can restart your PUZZLE instance with a more detailed logging.

To achieve this, you must set the log level to debug. To do this, change the file conf/log4j.properties in the installation path of your PUZZLE instance so that it contains the following line:

  log4j.category.de.fraunhofer.iml.puzzle=DEBUG

For the new settings to take effect, you must restart your PUZZLE instance.

7. HTTP Requests

This section describes all available HTTP endpoints of the PUZZLE REST API. For each endpoint, this documentation contains an interactive representation of the structure of the request body schema and the response schema below the endpoint description. In addition, the right column contains request and response samples for these structures.

In order to facilitate understanding, the following two scenarios are included as examples.

Pallet example

In this scenario, PUZZLE will compute three solutions how to place an item 8 times on a euro pallet. PUZZLE may exceed the left and right sides of the pallet by approx. 1 cm and the front and rear sides by approx. 2 cm. In addition, the client annotates the job with a customer id by inserting the attribute companyName.customerId to the extension of the job and PUZZLE does not change this attribute.

Images of solutions should show the left and right side of the item should in red (html color code 'FF0000').

Carton example

In this example, PUZZLE will compute two variants how to place an electronic device twice into a FEFCO 0201 carton. In addition, PUZZLE leave five centimeters of free space on each carton sidewall to facilitate the removal of an item from the carton by a human operator. Therefore, the attributes lengthOverhang and widthOverhang of the loading device entry are set to -50.

/jobs

Returns the list of all available jobs.

Responses

200

PUZZLE returns the the list of available jobs

Response Schema: application/json
Array
500

An unexpected error (an unhandled exception) occurred in PUZZLE.

get /jobs
PUZZLE instance at host hostname port 8888
http://hostname:8888/puzzle/api/v1/jobs
PUZZLE instance at localhost port 8888
http://localhost:8888/puzzle/api/v1/jobs

Response samples

application/json
Copy
Expand all Collapse all
[
  • { }
]

/jobs

Precondition: None.

Creates a job with the data from the JSON object in the request body. PUZZLE parses the JSON, assigns the data to an internal structure of a job, and sets the state of the created job to CREATED.

PUZZLE then returns a JSON object with the jobId attribute that contains a unique ID for the newly created job. The jobId is a long integer indicating the number of jobs since the last start of PUZZLE. When PUZZLE is restarted, it starts counting from one again.

A client must provide the jobId in subsequent interactions with PUZZLE in order to specify the job. You can check that the status of the job is CREATED by retrieving its metadata.

If PUZZLE cannot parse a JSON representation, it returns with HTTP status code 400 and a JSON object as response body that encodes a parsing error (see Section error and response samples with HTTP status code 400). In this case, PUZZLE creates neither a job nor a jobId.

Request Body schema: application/json
job
required
object

Responses

201

Job is successful created.

Response Headers
Location
string <uri>

The uri of the newly created job.

Response Schema: application/json
jobId
required
integer <int64> >= 1

Identifier created by PUZZLE for a job. PUZZLE always creates a positive integer.

400

PUZZLE cannot parse the JSON in the request body.

500

An unexpected error (an unhandled exception) occurred in PUZZLE.

post /jobs
PUZZLE instance at host hostname port 8888
http://hostname:8888/puzzle/api/v1/jobs
PUZZLE instance at localhost port 8888
http://localhost:8888/puzzle/api/v1/jobs

Request samples

application/json
Copy
Expand all Collapse all
{
  • "job":
    {
    }
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "jobId": 1
}

/jobs/{jobId}/metadata

Precondition: Job has been created.

Returns the metadata of the job with the specified jobId.

PUZZLE does not update the lastUseTimestamp attribute when a client requests the metadata. Section Cleanup a job describes the interactions that update the lastUseTimestamp attribute.

If you specify an unknown jobId, PUZZLE returns HTTP status code 404 (see 404 response samples).

path Parameters
jobId
required
integer <int64> >= 1

The id of the job.

Responses

200

PUZZLE returns the metadata

Response Schema: application/json
jobId
required
integer <int64> >= 1

Identifier created by PUZZLE for a job. PUZZLE always creates a positive integer.

state
required
string
Enum:"CREATED" "VALID" "SUBMITTED" "DONE" "DELETED"
lastUseTimestamp
required
string

Timestamp of the last access to the job. Format is YYYY-MM-DDTHH:MM:SSZ (according to RFC 3339)

expirationTimestamp
required
string

String containing the time at which PUZZLE automatically deletes this job if the job is not used before the expirationTimestamp. Format is YYYY-MM-DDTHH:MM:SSZ (according to RFC 3339). PUZZLE does not automatically delete a job in state SUBMITTED. If a job has state SUBMITTED, its expirationTimestamp is set to the empty string ("").

timeIntervalUntilExpiration
integer <int64>

Time interval between the current time and the expiration timestamp time in seconds.

orderNumber
required
string

Order number of the job as specified by the client.

errorOccurred
boolean

Flag indicating whether an error occurred during the computation of solutions by PUZZLE (during the transition from state SUBMITTED to DONE). PUZZLE sets the flag to false if no error occurred, otherwise to false.

errorMessage
string

The message of the error occurred during the computation of solutions by PUZZLE If no error occurred, this attribute is set to the empty string.

404

There does not exist a job with the given jobId.

500

An unexpected error (an unhandled exception) occurred in PUZZLE.

get /jobs/{jobId}/metadata
PUZZLE instance at host hostname port 8888
http://hostname:8888/puzzle/api/v1/jobs/{jobId}/metadata
PUZZLE instance at localhost port 8888
http://localhost:8888/puzzle/api/v1/jobs/{jobId}/metadata

Response samples

application/json
Copy
Expand all Collapse all
{
  • "jobId": 1,
  • "state": "DONE",
  • "lastUseTimestamp": "2019-04-10T14:07:34+0200",
  • "expirationTimestamp": "2019-04-10T19:07:34+0200",
  • "timeIntervalUntilExpiration": 17990,
  • "orderNumber": "order_23117",
  • "errorOccurred": false,
  • "errorMessage": ""
}

/jobs/{jobId}/validation

Precondition: the state of the job is CREATED or VALID.

PUZZLE verifies whether the data in the job violates predefined semantic constraints. These constraints ensures that PUZZLE can compute results for the job.

If the data of the job does not violates any constraints, the job is valid and PUZZLE set the state of the job to VALID. Then PUZZLE returns a JSON object where the attribute isValid is set to true and validationMessage is an empty array. The HTTP status code is 200 (see response sample "No violation" for complete response).

In all other cases, PUZZLE does not change the state of the job. You can check the state of the job by retrieving its metadata.

If the job's data violates at least one constraint, PUZZLE sets the isValid attribute to false and the HTTP status code is 200. In this case, PUZZLE inserts messages into the validationMessages array describing which restrictions are violated. For example, the response sample "First loading device has negative length and width" shows the response when the first loading device in the job has negative values for the attributes length and width.

If you specify an unknown jobId, PUZZLE returns HTTP status code 404 (see 404 response samples).

If the job does not have the states expected in the precondition, PUZZLE returns an error and HTTP status code 500 (see response samples for 500).

path Parameters
jobId
required
integer <int64> >= 1

The id of the job.

query Parameters
language
string
Example: "en"

The language of the validation messages. A client can specify the language with IETF language tags. If not specified, the system setting language is used.

Currently supported languages are German (de) and English (en).

Responses

201

no error.

Response Schema: application/json
isValid
required
boolean

Flag that indicates if the job is valid. PUZZLE sets the flag to true if a job is valid, otherwise to false.

validationMessages
Array of string

Array of constraints violation messages. If a job is valid, this array is empty.

404

There does not exist a job with the given jobId.

500

An error occurred.

post /jobs/{jobId}/validation
PUZZLE instance at host hostname port 8888
http://hostname:8888/puzzle/api/v1/jobs/{jobId}/validation
PUZZLE instance at localhost port 8888
http://localhost:8888/puzzle/api/v1/jobs/{jobId}/validation

Response samples

application/json
Copy
Expand all Collapse all
{
  • "isValid": true,
  • "validationMessages": [ ]
}

/jobs/{jobId}/computation

Precondition: the state of the job is VALID.

A client requests PUZZLE to compute solutions. PUZZLE uses the first loading device in a job and PUZZLE ignores additional loading devices.

PUZZLE indicates that a client has requested solutions by changing the state of the job to SUBMITTED and returning an empty body with HTTP status code 201.

You can check that the status of the job is SUBMITTED by retrieving its metadata.

PUZZLE computes solutions asynchronously. After PUZZLE completes the computation of solutions, PUZZLE sets the job's state to DONE. To determine if PUZZLE has computed solutions for a job, a client must periodically poll the metadata of the job.

If you specify an unknown jobId, PUZZLE returns an error with HTTP status code 404 (see response samples for 404).

If the job does not have the states expected in the precondition, PUZZLE returns an error with HTTP status code 500 (see response samples for 500).

path Parameters
jobId
required
integer <int64> >= 1

The id of the job.

Responses

201

PUZZLE has successfully accepted the request for computation.

404

There does not exist a job with the given jobId.

500

An error occurred.

post /jobs/{jobId}/computation
PUZZLE instance at host hostname port 8888
http://hostname:8888/puzzle/api/v1/jobs/{jobId}/computation
PUZZLE instance at localhost port 8888
http://localhost:8888/puzzle/api/v1/jobs/{jobId}/computation

Response samples

application/json
Copy
Expand all Collapse all
{
  • "errorMessage": "PUZZLE cannot find job with id 123",
  • "additionalInformation": "",
  • "errorClass": "de.fraunhofer.iml.puzzle.adapter.execution.Exceptions.Rest.PuzzleJobNotFoundException"
}

/jobs/{jobId}/computation

Precondition: the state of the job is SUBMITTED.

A client aborts the request to compute solutions for the job. Therefore, PUZZLE aborts all current computations for the job and deletes all computed solutions for this job. PUZZLE indicates the revocation by resetting the state of the job to VALID. PUZZLE returns with HTTP status code 204 and an empty body.

You can check whether the state of the job is VALID again by retrieving its metadata.

If you specify an unknown jobId, PUZZLE returns an error with HTTP status code 404 (see response samples for 404).

If the job does not have the state expected in the precondition, PUZZLE returns an error with HTTP status code 500 (see response samples for 500).

path Parameters
jobId
required
integer <int64> >= 1

The id of the job.

Responses

204

Successfully aborted computation.

404

There does not exist a job with the given jobId.

500

An error occurred.

delete /jobs/{jobId}/computation
PUZZLE instance at host hostname port 8888
http://hostname:8888/puzzle/api/v1/jobs/{jobId}/computation
PUZZLE instance at localhost port 8888
http://localhost:8888/puzzle/api/v1/jobs/{jobId}/computation

Response samples

application/json
Copy
Expand all Collapse all
{
  • "errorMessage": "PUZZLE cannot find job with id 123",
  • "additionalInformation": "",
  • "errorClass": "de.fraunhofer.iml.puzzle.adapter.execution.Exceptions.Rest.PuzzleJobNotFoundException"
}

/jobs/{jobId}/summaries

Precondition: the state of the job is DONE.

Returns a summary of the solutions of the job. The response consists of an array with one object per solution containing the summary of that solution and the HTTP status code 200.

If PUZZLE has not computed a solution for the job, the returned array is empty.

If you specify an unknown jobId, PUZZLE returns an error with HTTP status code 404 (see response samples for 404).

If the job does not have the state expected in the precondition, PUZZLE returns an error with HTTP status code 500 (see response samples for 500).

path Parameters
jobId
required
integer <int64> >= 1

The id of the job.

Responses

200

Successfully created summaries for all solutions of the job.

Response Schema: application/json
Array
solutionId
integer

Unique identifier of the Solution. Generated by PUZZLE. A positive integer.

length
integer >= 0

Length of the bounding box that encloses all positioned order items in millimeters.

width
integer >= 0

Width of the bounding box that encloses all positioned order items in millimeters.

height
integer >= 0

Height of the bounding box that encloses all positioned order items in millimeters.

weight
integer >= 0

Sum of the weight of all positioned order items in grams.

volume
integer <int64> >= 0

Sum of the volume of all positioned order items in cubic millimeters (mm^3).

numberOfPositionedItems
integer >= 0

Number of order items that are placed on the loading device. Not number of distinct order items in the solution.

weightUtilization
integer [ 0 .. 100 ]

The ratio of the sum of weights of positioned order items (equal to the weight field) to the maximum possible weight of the loading device, in percent (integer in range [0,100]).

volumeUtilization
integer [ 0 .. 100 ]

The ratio of the sum of volumes of positioned order items (equal to the volume field) to the maximum possible volume of the loading device, in percent (integer in range [0,100]).

packDensity
integer [ 0 .. 100 ]

The ratio of the sum of volumes of positioned order items (equal to the volume field) to the volume of the bounding box that encloses all positioned order items, in percent (integer in the range [0,100]).

loadingDeviceNumber
string

The number of the loading device used in this solution. If PUZZLE has not assigned a loadingDevice to a solution, this attribute is set to the empty string.

404

There does not exist a job with the given jobId.

500

An error occurred.

get /jobs/{jobId}/summaries
PUZZLE instance at host hostname port 8888
http://hostname:8888/puzzle/api/v1/jobs/{jobId}/summaries
PUZZLE instance at localhost port 8888
http://localhost:8888/puzzle/api/v1/jobs/{jobId}/summaries

Response samples

application/json
Copy
Expand all Collapse all
[
  • {
    },
  • {
    },
  • {
    }
]

/jobs/{jobId}/picklists

Precondition: the state of the job is DONE.

Returns picklists for solutions of the job. The response consists of an array with one object per solution containing the picklist of that solution and the HTTP status code 200. The picklist of a solution is the table of the frequencies of orderItems in this solution.

If PUZZLE has not computed a solution for the job, the returned array is empty.

If you specify an unknown jobId, PUZZLE returns an error with HTTP status code 404 (see response samples for 404).

If the job does not have the state expected in the precondition, PUZZLE returns an error with HTTP status code 500 (see response samples for 500).

path Parameters
jobId
required
integer <int64> >= 1

The id of the job.

Responses

200

Successfully created picklists for all solutions of the job.

Response Schema: application/json
Array
solutionId
integer

Unique identifier of the Solution. Generated by PUZZLE. A positive integer.

loadingDeviceNumber
string

The number of the loading device used in this solution. If PUZZLE has not assigned a loadingDevice to a solution, this attribute is set to the empty string.

picklist
Array of object
404

There does not exist a job with the given jobId.

500

An error in PUZZLE occurred. This includes error messages containing the wrong state of the job.

get /jobs/{jobId}/picklists
PUZZLE instance at host hostname port 8888
http://hostname:8888/puzzle/api/v1/jobs/{jobId}/picklists
PUZZLE instance at localhost port 8888
http://localhost:8888/puzzle/api/v1/jobs/{jobId}/picklists

Response samples

application/json
Copy
Expand all Collapse all
[
  • {
    },
  • {
    },
  • {
    }
]

/jobs/{jobId}

Precondition: Job has been created.

Returns a JSON representation of all data of the job with HTTP status code 200. If PUZZLE has computed solutions for the job, the JSON representation contains these solutions in the solutions attribute.

If you specify an unknown jobId, PUZZLE returns an error with HTTP status code 404 (see response samples for 404).

path Parameters
jobId
required
integer <int64> >= 1

The id of the job.

Responses

200

Successful creation of the JSON representation of the job

Response Schema: application/json
parameters
required
object

Hash map of the parameters used by PUZZLE. PUZZLE uses default values for each parameter. A client can override any default value by explicitly setting a parameter value. Setting undocumented parameters may result in undefined behavior. See the main documentation for a detailed description of the parameters.

order
required
object

Order that is to be palletized on a pallet or packed in a box.

loadingDevices
required
Array of object

The loading devices on which PUZZLE is to palletize or pack the order.

extension
object

Extension provides a hash map for additional data for the client and PUZZLE. Keys and values must be strings. PUZZLE uses extension itself, so it is highly recommended to use a client specific prefix for extension keys.

solutions
Array of object
404

There does not exist a job with the given jobId.

500

An error in PUZZLE occurred. This includes error messages containing the wrong state of the job.

get /jobs/{jobId}
PUZZLE instance at host hostname port 8888
http://hostname:8888/puzzle/api/v1/jobs/{jobId}
PUZZLE instance at localhost port 8888
http://localhost:8888/puzzle/api/v1/jobs/{jobId}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "parameters":
    {
    },
  • "order":
    {
    },
  • "loadingDevices":
    [
    ],
  • "extension":
    {
    },
  • "solutions":
    [