API docs by Redocly

adiutaOpt (v6.0.0)

Download OpenAPI specification:Download

adiutaByte GmbH: info@adiutabyte.de URL: https://adiutabyte.de

Introduction

Welcome to the adiutaOpt API documentation!

This document specifies all endpoints and schema requirements. If you notice an error, please contact us.

The typical process of an optimization request looks as follows:

  • Obtain authentication tokens
  • Use authentication tokens to post an input data set to the optimization request endpoint. If everything is in order, a key will be returned that has to be stored
    • If the request was rejected, check authentication details and schema. The return code and data will give some hints as to what needs to be fixed.
  • Use the authentication token and the key on the solution endpoint to request the solved data.
    • If the plan is still in calculation, wait until it's done
    • If the calculation has finished, store the solution
  • Check if the calculation could be carried out or if an error was returned (see ErrorPlan as possible return data of the solution endpoint)

The overview site can be found here.

Authentication

AWS Cognito

The authentication is performed via AWS Cognito (Developer-Guide). It is recommended to use one of the SKDs provided by AWS to simplify the authentication process considerably. Examples for SDKs:

Configuration

  • Used protocol: Secure Remote Password Protocol
  • User pool data:
    • UserPoolId/ClientId is available only on PROD/DEV/EXP documentation.
  • Username/Password are provided when signing up for an account. If you don't have an account, please contact us.

Tokens

Authentication provides three tokens: the access-token, the ID-token and the refresh-token. All three are JSON Web Tokens.

  • The access-token is currently not used in the API.
  • The ID-token has to be proposed in every request in the header as follows:

Authorization: 'ID-token'

  • The ID-token contains a timestamp when the token has been authorized (auth_time) and when it will expire (exp). Currently, an ID-token expires after one hour and requests with expired ID-tokens are rejected automatically. You can get a new ID-token by using the refresh-token without having to re-enter your credentials.

Request samples 

const user = "";        // your username
const pw = "";          // your password
const userPoolID = "";  // UserPoolID, see configuration details
const clientID = "";    // ClientId, see configuration details

const AmazonCognitoIdentity = require('amazon-cognito-identity-js');

module.exports.login = () => new Promise((resolve, reject) => {

  const userPool = new AmazonCognitoIdentity.CognitoUserPool({
    UserPoolId: userPoolID,
    ClientId: clientID
  });

  const authenticationDetails = new AmazonCognitoIdentity.AuthenticationDetails({
      Username: user,
      Password: pw,
  });

  const cognitoUser = new AmazonCognitoIdentity.CognitoUser({
      Username: user,
      Pool: userPool
  });

  cognitoUser.authenticateUser(authenticationDetails, {
    onSuccess: function (result) {
        const token = result.getIdToken().getJwtToken();
        resolve(token);
    },
    onFailure: function (err) {
        reject();
    }
  });
})

Deployment Status

Deployment status data is available only on PROD/DEV/EXP documentation.

Optimization Request

Post an optimization request.

Optimization Request

Post a request to be solved.

If a new optimization request was received and was successfully processed, the endpoint will return 201 and the key with which the solution can be retrieved. This does not mean that calculating a solution will succeed, as logic errors, invalid ids and many other checks are performed later - these kinds of issues will result in an ErrorPlan, retrievable from the solution endpoint. Only schema violations are being checked in this request, they will result in the request being rejected with code 422.

If an optimization request was received but an identical request was already posted before, the endpoint will return 200 and the key with which the solution can be retrieved, which is identical to the key from the earlier request.

Request to this endpoint have a content size limit which depends on the used content-type. Requests with content-type: application/json must contain a "plain-text" json payload which must be less than 6Mb in size. For sending larger requests, you must use content-type: application/vnd.adiutabyte.adiutaopt.json+[gzip,deflate,br]. These requests must contain the json data, compressed with gzip, deflate (zlib) or brotli, the payload size limit is 4.5Mb for the compressed data.

Authorizations:
BearerAuth
header Parameters
required
"application/json" (string) or "application/vnd.adiutabyte.adiutaopt.json+gzip" (string) or "application/vnd.adiutabyte.adiutaopt.json+deflate" (string) or "application/vnd.adiutabyte.adiutaopt.json+br" (string)

The content-type of the payload. Invalid values result in status code 415.

adiutaopt-version
string

(optional) A specific version to process the request under. Valid versions can be retrieved with the /packages-list endpoint (Name).

Using a specific version is not recommended for "general" application but for testing, debugging or other developer actions. Versions represent a specific state of the application, they cannot be changed, bug-fixed or extended in any way. For that reason, support for these requests may be limited.

Request Body schema:
object (Client)

Contains information about the client which sends this request.

required
object (ShiftPlannerMeta)

Meta information about what to consider in the optimization.

required
object (ShiftPlannerOptimizationParameters)

Parameters for the optimizer.

required
Array of objects (ShiftPlannerInputTask)

Array of Tasks to be planned by the optimizer.

required
Array of objects (ShiftPlannerInputWorker)

Array of available Workers.

object (ShiftPlannerHistory)

History data.

recovery
Array of integers (IDReferences) [ items [ 0 .. 2147483647 ] ]

This is a field only used for debugging by internal developers. Content in this field may change depending on the application, input-data and version. The output values can be used as input values.

Responses

Request samples

Content type
Example

Basic blueprint for an optimization data set

{
  • "meta": {
    },
  • "parameters": {
    },
  • "tasks": [
    ],
  • "workers": [
    ]
}

Response samples

Content type
application/json
"VGVzdEtleUZvckFQSURvY3VtZW50YXRpb24uYXNk=="

Optimization Request (Preflight)

Responses

Solution

Retrieve the optimization solution for any application

Retrieving Solution

Retrieve the solution from this endpoint with the key you got when posting the request. The solution can either be a solved request or an ErrorPlan.

Authorizations:
BearerAuth
path Parameters
planID
required
string

Key returned in the 200/201 response of the POST request

header Parameters
"application/json" (string) or "application/vnd.adiutabyte.adiutaopt.json+gzip" (string) or "application/vnd.adiutabyte.adiutaopt.json+deflate" (string) or "application/vnd.adiutabyte.adiutaopt.json+br" (string)

(optional) The content-type of the response. Defaults to application/json if not set, invalid values result in status code 406.

"identity" (string) or "gzip" (string) or "deflate" (string)

(optional) The content-encode of the response. Only permitted for application/json responses.

Responses

Response Schema:
One of
requestID
string

The identifier that allows finding input/output data, logs and more. This ID will be asked for in most non-trivial support cases so it should be stored when receiving the data.

object (Client)

Contains information about the client which sends this request.

required
object (ShiftPlannerMeta)

Meta information about what to consider in the optimization.

required
object (ShiftPlannerOptimizationParameters)

Parameters for the optimizer.

required
Array of ShiftPlannerOutputTaskAssigned (object) or ShiftPlannerOutputTaskUnassigned (object) (ShiftPlannerOutputTask)

Array of assigned and unassigned tasks.

required
Array of objects (ShiftPlannerOutputWorker)

Array of available Workers.

required
object (ShiftPlannerStatistics)

Some statistics about the plan.

required
object (ShiftPlannerInfo)

Some textual information about the plan.

required
object (BackendVersion)

Used validation/ calculation version.

recovery
Array of integers (IDReferences) [ items [ 0 .. 2147483647 ] ]

This is a field only used for debugging by internal developers. Content in this field may change depending on the application, input-data and version. The output values can be used as input values.

Request samples 

curl \
  --request GET \
  --url '[see url above]/[key obtained from POST request]' \
  --header 'Authorization: Bearer [ID-Token obtained from Authentication (JWT)]'

Response samples

Content type
Example
{
  • "requestID": "string",
  • "client": {
    },
  • "meta": {
    },
  • "parameters": {
    },
  • "tasks": [
    ],
  • "workers": [
    ],
  • "statistics": {
    },
  • "info": {
    },
  • "backendVersion": {
    },
  • "recovery": [
    ]
}

Get Solution (Preflight)

path Parameters
planID
required
string

Can be anything.

Responses

Version

Retrieve currently deployed version data

Get Version

Get the currently deployed version.

Authorizations:
BearerAuth
header Parameters
adiutaopt-version
string

(optional) A specific version to process the request under. Valid versions can be retrieved with the /packages-list endpoint (Name).

Using a specific version is not recommended for "general" application but for testing, debugging or other developer actions. Versions represent a specific state of the application, they cannot be changed, bug-fixed or extended in any way. For that reason, support for these requests may be limited.

Responses

Response Schema: application/json
schema
string
version
string
meta_data
string
api_scripts
string

Request samples 

curl \
  --request GET \
  --url '[see url above]' \
  --header 'Authorization: Bearer [ID-Token obtained from Authentication (JWT)]'

Response samples

Content type
application/json
{
  • "schema": "v1.7.0",
  • "version": "2024-10-01_0",
  • "meta_data": "v19",
  • "api_scripts": "v1.6.2"
}

Get Version (Preflight)

Responses

Get List of Available Packages

Get a list of all available packages. The Name of each package can be used in a POST request in header adiutaopt-version, the algorithm will then run on the specified version.

Authorizations:
BearerAuth

Responses

Response Schema: application/json
Array
Name
required
string
LastModified
string
object (VersionInfo)
Example: "[object Object]"

Request samples 

curl \
  --request GET \
  --url '[see url above]' \
  --header 'Authorization: Bearer [ID-Token obtained from Authentication (JWT)]'

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Get List of Available Packages (Preflight)

Responses

Common Data Types

Types that are reused in different definitions.

Date

string (Date) ^[0-9]{4}-(0?[1-9]|1[0-2])-(0?[1-9]|[1-2][0-9...

A string consisting of three parts following the pattern "YYYY-MM-DD":

  • "YYYY" year AD: 0-9999
  • "MM" month: 1-12
  • "DD" day: 1-31

While the schema does not check for validity, the optimization algorithms do. Including invalid dates (e.g. 2020-02-31) leads to a validation error.

Examples:

  • "2020-04-10"
  • "2051-4-1"
  • "1953-04-10"
"2020-04-10"

Language Type

integer (Language Type) [ 0 .. 1 ]

Values are:

  • 0: German
  • 1: English
1

Time

string (Time) ^[-]?([0-9]{1,9}):([0-5][0-9]|[0-9])$

A string of either format "hh:mm" or "-hh:mm":

  • "hh": hours (24h format),
  • "mm": minutes

Times are always interpreted relative to a date in the same object as the Time field. This allows times to exceed 24h or even become negative, as the value gets "added" to midnight of the date. For example, the following times applied to the respective date (in Date format) are equivalent:

  • "2021-05-21" at "07:25"
  • "2021-05-20" at "31:25"
  • "2021-05-19" at "55:25"
  • "2021-05-22" at "-16:35"
  • "2021-05-23" at "-40:35"
"07:25"

Gender Type

integer (Gender Type) [ 0 .. 3 ]

Values are:

  • 0: not provided
  • 1: male
  • 2: female
  • 3: other
3

Weekday

integer (Weekday) [ 0 .. 6 ]

A numerical representation of a weekday. Values are:

  • 0: Sunday
  • 1: Monday
  • 2: Tuesday
  • 3: Wednesday
  • 4: Thursday
  • 5: Friday
  • 6: Saturday
6

FieldPlacerVersion

string (FieldPlacerVersion) ^[0-9]{4}-[0-9]{2}-[0-9]{2}_[0-9]+(p[0-9]+)?$...

A version consisting of the date of release [0-9]{4}-[0-9]{2}-[0-9]{2}_[0-9]+, which can have a patch suffix p[0-9]+.

"1970-01-01_0p0"

SemanticVersion

string (SemanticVersion) ^(v)?(0|([1-9][0-9]{0,4}))(\.(0|([1-9][0-9]{0...

See https://semver.org/ for a full description of semantic versioning. The regex here is a subset of allowed semantic versions.

"v1.2.3"

Error IDs

Error ID data is available only on PROD/DEV/EXP documentation.

Changelog

v6.0.0

  • In MixedPlannerMeta, ShiftPlannerMeta, FloorPlannerMeta:
    • Deprecated enablePlanSplitting

v5.2.0

  • In ShiftPlannerInputWorker:
    • Added workdayPattern.
    • Added workdayCycle.
  • In ShiftPlannerStatisticsHistoryWorkerEntry:
    • Added cycleStart

v5.1.0

  • Added new content-type options in POST requests:
    • application/vnd.adiutabyte.adiutaopt.json+gzip
    • application/vnd.adiutabyte.adiutaopt.json+deflate
    • application/vnd.adiutabyte.adiutaopt.json+br
  • Updated description for POST request, added explanations to response codes, compression and returned key
  • Added header accept-encoding in GET requests with allowed values:
    • identity
    • deflate
    • gzip
  • Added header accept in GET requests with allowed values:
    • application/json
    • application/vnd.adiutabyte.adiutaopt.json+gzip
    • application/vnd.adiutabyte.adiutaopt.json+deflate
    • application/vnd.adiutabyte.adiutaopt.json+br
  • Renamed header version to adiutaopt-version

v5.0.0

  • Restored compatibility to v3 schemata
  • In BackendVersion:
    • Changed version to be constant "v1.0.0", marked as deprecated
    • Added optVersion, has the same properties as version did in v4

v4.0.1

  • Added response codes to OPTIONS requests
  • Removed incorrect authentication details from OPTIONS requests

v4.0.0

  • Changed the version pattern to ^\d{4}-\d{2}-\d{2}_\d+(p\d+)?$.

v3.1.0

  • In MixedPlannerInputTask: Added predecessorGroup.

v3.0.0

  • In MixedPlannerTravelOverride: Removed field internal.

v2.9.0

  • Added header parameter Version to paths /[/floor-/shift-]description and /[/floor-/shift-]version
    • Updated curl/nodejs code examples to include one with the new header
  • Added path /[/floor-/shift-]packages-list

v2.8.2

  • Fixed incorrect description in ShiftPlannerWorker: shifts

v2.8.1

  • Fixed response content type for status 200, 201 for endpoint /description, /shift-description, /floor-description

v2.8.0

  • In ShiftPlannerInputWorker:
    • Added consecutiveNightShiftsForOffdays
    • Added minOffdaysAfterConsecutiveNightShifts

v2.7.0

  • In MixedPlannerInputWorker: Added minAssignableTasks.

v2.6.0

  • In MixedPlannerLocationSite: Added externalID.

v2.5.0

  • In MixedPlannerInputWorker: Added noAutomaticBreak.

v2.4.0

  • In MixedPlannerInputWorker: Added expectedWorkingMinutes.

v2.3.0

  • In MixedPlannerInputWorker: Added maxAssignableTasks.

v2.2.0

  • In MixedPlannerMeta, FloorPlannerMeta:
    • Added disableTaskTimeWindowRelaxation

v2.1.0

  • In MixedPlannerStatisticsHistoryWorker:
    • Added hasNoHistory

v2.0.0

  • Release date: 2024-07-04
  • Removed definition Number_u32, replaced all occurrences with Number_u64. Those are:
    • MixedPlannerInputTask, MixedPlannerOutputTask:
      • revenue
    • MixedPlannerInputWorker, MixedPlannerOutputWorker:
      • capacity
      • capacityInitial
      • volume
      • volumeInitial
      • weight
      • weightInitial
      • finalCapacityResetThreshold
      • finalVolumeResetThreshold
      • finalWeightResetThreshold
      • costsPerKM
      • costsPerMinute
      • costsInitial
    • ShiftPlannerInputWorker, ShiftPlannerOutputWorker :
      • costsPerMinute
      • costsInitial
  • Added Number_s64
  • Removed definition Number_s32, replaced all occurrences with Number_s64. Those are:
    • MixedPlannerInputTask, MixedPlannerOutputTask:
      • capacity
      • weight
      • volume
    • MixedPlannerOutputTaskAssigned:
      • profit
    • MixedPlannerStatistics:
      • planProfitability
    • ShiftPlannerOutputTaskAssigned:
      • profit
  • Fixed incorrect type of ShiftPlannerInputTask/ShiftPlannerOutputTask: revenue, changed it from Number_s32 to Number_u64

v1.14.0

  • Release date: 2024-07-03
  • In ErrorPlan
    • Added recovery

v1.13.0

  • Release date: 2024-07-02
  • In FloorPlannerInputPlan, FloorPlannerOutputPlan, MixedPlannerInputPlan, MixedPlannerOutputPlan, ShiftPlannerInputPlan, ShiftPlannerOutputPlan
    • Added recovery

v1.12.0

  • Release date: 2024-06-26
  • In ShiftPlannerInputWorker:
    • Added maxDailyTasks

v1.11.0

  • Release date: 2024-06-19
  • In ShiftPlannerMeta, MixedPlannerMeta, FloorPlannerMeta:
    • Added new field removeInvalidTasks

v1.10.1

  • Release date: 2024-06-19
  • Fixed tests for ShiftPlannerOutputWorker

v1.10.0

  • Release date: 2024-06-19
  • Added definition ShiftPlannerStatisticsPreferencesMatches
  • In ShiftPlannerStatistics:
    • Added preferredWorkers
    • Added unpreferredWorkers
  • In ShiftPlannerOutputWorker:
    • Added totalTaskTime

v1.9.0

  • Release date: 2024-06-19
  • In MixedPlannerInputTask, ShiftPlannerInputTask, ShiftPlannerInputWorker:
    • Added unpreferredWorkers
    • Marked antiWorkers as deprecated
  • Added some missing default values

v1.8.1

  • Release date: 2024-06-14
  • Added missing return codes 400, 413 to endpoints for posting new optimization requests

v1.8.0

  • Release date: 2024-05-30
  • In FloorPlannerInputTask:
    • Added exclusiveSetID
  • In FloorPlannerInputWorker:
    • Added preferredCategories
    • Added unpreferredCategories
    • Added desiredCategories
    • Added undesiredCategories

v1.7.3

  • Release date: 2024-05-17
  • Added missing return code 401 to all endpoints

v1.7.1

  • Release date: 2024-05-14
  • Minor (non-functional) rework of ErrorEntry, FloorPlannerInputTask, FloorPlannerInputWorker, MixedPlannerInputTask, MixedPlannerInputWorker, ShiftPlannerInputTask, ShiftPlannerInputWorker
  • Fixed unevaluated properties being allowed in:
    • ErrorPlan
    • FloorPlannerOutputTaskAssigned
    • FloorPlannerOutputTaskUnassigned
    • FloorPlannerOutputWorker
    • MixedPlannerConstructionSite
    • MixedPlannerHistoryAssignment
    • MixedPlannerHistoryTask
    • MixedPlannerHistoryWorker
    • MixedPlannerLocationSite
    • MixedPlannerOutputPlan
    • MixedPlannerStatisticsHistoryTask
    • MixedPlannerStatisticsHistoryWorker
    • MixedPlannerTravelOverrideDense
    • MixedPlannerOutputTaskAssigned
    • MixedPlannerOutputTaskUnassigned
    • MixedPlannerOutputWorker
    • ShiftPlannerOutputTaskAssigned
    • ShiftPlannerOutputTaskUnassigned
    • ShiftPlannerOutputWorker

v1.7.0

  • Release date: 2024-05-14
  • In MixedPlannerInputTask:
    • Added property durationInSeconds
    • Removed duration from required properties
  • In FloorPlannerInputTask:
    • Added property durationInSeconds
    • Removed duration from required properties
  • In MixedPlannerStatisticsHistoryTask:
    • Added property group