wms_to_mfm_openapi_spec.yaml

openapi: 3.0.2
info:
  description: This document details the OpenAPI specification for the Magazino Fleet Manager (MFM).
  title: MFM REST API
  version: 1.0.0
components:
  schemas:
    Container:
        description: Any place that can contain items (can be a pick-up or drop-off station).
        properties:
          name:
            title: Name
            type: string
            example: HandoverStation-1-1-1
          station_name:
            title: Station Name
            type: string
            example: HandoverStation-1
          length:
            description: Length in meter (m). Has to be greater than width.
            minimum: 0.3
            title: Length
            type: number
          width:
            description: Width in meter (m). Has to be smaller than length.
            minimum: 0.2
            title: Width
            type: number
          height:
            description: Height in meter (m).
            minimum: 0.08
            title: Height
            type: number
        required:
        - name
        title: Container
        type: object
    CustomFields:
      description: >-
        A key value storage for additional parameters (e.g. is_announced to announce orders).
        Keys must be strings. Values can be strings, numbers, booleans or nested Custom Fields.
      title: Custom Fields
      type: object
    FailureResponse:
      description: Sent when the full Request fails.
      properties:
        error:
          description: Description of the failure cause or error key.
          title: Error
          type: string
        id:
          description: Identifier of the resource related to the failure (request_id,
            order_id).
          title: Id
          type: string
      required:
      - id
      - error
      title: FailureResponse
      type: object
    Item:
      description: 'Item to be moved by an AGV.'
      properties:
        item_id:
          description: Unique identifier of the item (can be the barcode).
          title: Item Id
          type: string
        length:
          description: Length in meter (m). Has to be greater than width.
          minimum: 0.3
          title: Length
          type: number
        width:
          description: Width in meter (m). Has to be smaller than length.
          minimum: 0.2
          title: Width
          type: number
        height:
          description: Height in meter (m). Omitted means height is unknown.
          minimum: 0.08
          title: Height
          type: number
      required:
      - item_id
      - length
      - width
      title: Item
      type: object
    Order:
      type: object
      description: >-
        An Order is composed of a list of `Requests` and a priority.
        All Requests in an Order are part of the same process (e.g.: Delivery, Return).
        Process types are used to distinguish diffent parts of a warehouse process.
        E.g: Delivery denotes material delivery to a workstation, while return denotes the return of
        an empty box to a central storage.
        This is a concept definition from Magazino, it can differ from that of the client''s WMS.
      properties:
        order_id:
          title: Order id
          type: string
          description: Unique identifier of the order
          example: ORDER_01
        priority:
          title: Priority
          type: integer
          minimum: 1
          description: Priority for the order to be batched. Lower numbers mean higher priority.
          example: 2
        requests:
          type: array
          items:
            $ref: '#/components/schemas/Request'
          minItems: 1
        custom_fields:
            $ref: '#/components/schemas/CustomFields'
        process_type:
          title: Process Type
          type: string
          description: >-
            Process type for all Requests in the Order (delivery, return).
            Process types are used to distinguish diffent parts of a warehouse process.
            E.g: Delivery denotes material delivery to a workstation, while return denotes the return of
            empty boxes to a central storage.
          example: delivery
      required:
        - order_id
        - priority
        - requests
        - process_type
      additionalProperties: false
    Request:
      description: >-
        Describes the movement of an item from a source to a target. Source and targets are
        containers in the handover stations. This schema allows to add extra fields inside `custom_fields`,
        which will be accessible in the RequestStatus.'
      properties:
        custom_fields:
            $ref: '#/components/schemas/CustomFields'
        item:
          allOf:
          - $ref: '#/components/schemas/Item'
          description: Item to move from source to target.
          title: Item
          example: KLT-001
        request_id:
          description: Unique identifier of a Request.
          title: Request Id
          type: string
          example: REQUEST_01
        source:
          allOf:
          - $ref: '#/components/schemas/Container'
          description: Container where an AGV can find the item to move.
          title: Source
        target:
          allOf:
          - $ref: '#/components/schemas/Container'
          description: Container where an AGV has to place the item picked from source.
          title: Target
        sequence_nb:
          title: Sequence number
          description: Describes in which sequence the robot has to pick the items of that order.
          type: integer
          example: 1
      required:
      - request_id
      - item
      - source
      - target
      title: Request
      type: object

paths:
  /api/v1/wms/orders:
    post:
      description: |-
        Create a new order to be dispatched by MFM.
        An order is composed of:

        - an order_id
        - a priority
        - a list of Requests
        - a process_type

        Responses:
        - 201: the order was created
        - 400: the order is invalid. All requests are rejected
      operationId: mfm_rest_api_wms_api_order_create_order
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Order'
            examples:
              Order Creation Example 1:
                description: This order contains a basic request to transport an item from a source to a target.
                value:
                  order_id: "ORDER_01"
                  priority: 2
                  process_type: "delivery"
                  requests:
                    - request_id: "REQUEST_01"
                      item:
                        item_id: "KLT-001"
                        length: 0.6
                        width: 0.3
                        height: 0.2
                      source:
                        name: "HandoverStation-1-1-1"
                      target:
                        name: "HandoverStation-2-1-2"
              Order Creation Example 2 (Sequence specified):
                description: |-
                  This order contains two items that need to be picked in a specific sequence.
                  KLT-001 will be picked before KLT-005.
                value:
                  order_id: "ORDER_02"
                  priority: 2
                  process_type: "return"
                  custom_fields:
                    properties:
                      is_announced: "true"
                  requests:
                    - request_id: "REQUEST_01"
                      item:
                        item_id: "KLT-005"
                        length: 0.4
                        width: 0.3
                        height: 0.15
                      source:
                        name: "HandoverStation-1-1-1"
                        station_name: "HandoverStation-1"
                      target:
                        name: "HandoverStation-3-2-1"
                        station_name: "HandoverStation-3"
                      sequence_nb: 2
                    - request_id: "REQUEST_02"
                      item:
                        item_id: "KLT-001"
                        length: 0.6
                        width: 0.3
                        height: 0.2
                      source:
                        name: "HandoverStation-1-1-1"
                        station_name: "HandoverStation-1"
                      target:
                        name: "HandoverStation-2-1-2"
                        station_name: "HandoverStation-2"
                      sequence_nb: 1


        required: true
      responses:
        201:
          description: OK
        400:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailureResponse'
              examples:
                Order id already exists:
                  value:
                    error: "Order with order_id ORDER_01 already exists"
                    id: "example_error_id"
          description: Error

      summary: Create an Order. (Required)
      tags:
      - Orders
  /api/v1/wms/orders/{order_id}/requests/{request_id}/cancel:
    put:
      description: |-
        Cancel a Request of an order that has not been started yet.

        Responses:
        - 200: Request was canceled
        - 400: Request was not canceled (Order already terminated, assigned to a robot...)
        - 404: unknown order_id and/or request_id
      operationId: mfm_rest_api_wms_api_request_cancel_request
      parameters:
      - in: path
        name: order_id
        required: true
        schema:
          title: Order Id
          type: string
      - in: path
        name: request_id
        required: true
        schema:
          title: Request Id
          type: string
      responses:
        200:
          description: OK
        400:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailureResponse'
              examples:
                Request started:
                  value:
                    error: "Request has already been started."
                    id: "example_error_id"
          description: Error

        404:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailureResponse'
              examples:
                Order not found:
                  value:
                    error: "Failed to cancel request of order ORDER_03 because its id is unknown."
                    id: "example_error_id"
          description: Error, request not found
      summary: Cancel a Request
      tags:
      - Orders
  /api/v1/wms/orders/{order_id}:
    put:
      description: |-
        Update an order by passing the order_id and the updated order. Updates must not contain the full order,
        only updated parts must be sent. If a request that was not part of the original order is sent, it gets
        appended to the orignal order. Examples for valid updates are provided below.


        - 200: Order was updated
        - 400: Order was not updated (already terminated, requests assigned to a robot...)
        - 404: unknown order_id
      operationId: mfm_rest_api_wms_api_request_update_order
      parameters:
      - in: path
        name: order_id
        required: true
        schema:
          title: Order Id
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Order'
            examples:
              Order Update Example 1 (Request Update):
                description: >-
                  This order update changes the target for REQUEST_01 of ORDER_01 as defined in the examples
                  for the create-order endpoint.
                value:
                  order_id: "ORDER_01"
                  priority: 2
                  process_type: "delivery"
                  custom_fields:
                    properties:
                      is_announced: "true"
                  requests:
                    - request_id: "REQUEST_01"
                      item:
                        item_id: "KLT-001"
                        length: 0.6
                        width: 0.3
                        height: 0.2
                      source:
                        name: "HandoverStation-1-1-1"
                        station_name: "HandoverStation-1"
                      target:
                        name: "HandoverStation-3-3-3"
                        station_name: "HandoverStation-3"
              Order Update Example 2 (Order Parameters):
                description: >-
                  This order update changes the order parameters for ORDER_01 as defined in the examples
                  for the create-order endpoint. The request remains unchanged.
                value:
                  order_id: "ORDER_01"
                  priority: 1
                  process_type: "delivery"
                  custom_fields:
                    properties:
                      is_announced: "true"
                      added_example_property: "example"
                  requests:
                    - request_id: "REQUEST_01"
                      item:
                        item_id: "KLT-001"
                        length: 0.6
                        width: 0.3
                        height: 0.2
                      source:
                        name: "HandoverStation-1-1-1"
                        station_name: "HandoverStation-1"
                      target:
                        name: "HandoverStation-2-1-2"
                        station_name: "HandoverStation-2"
              Order Update Example 3 (Request Extension):
                description: >-
                  This order update adds a request to ORDER_01 as defined in the examples for the
                  create-order endpoint. REQUEST_01 ofthe order is not part of the order in this example.
                  It will remain unchanged as part of ORDER_01. This is equivalent to passing REQUEST_01
                  unchanged in the order update.
                value:
                  order_id: "ORDER_01"
                  priority: 2
                  process_type: "delivery"
                  custom_fields:
                    properties:
                      is_announced: "true"
                  requests:
                    - request_id: "REQUEST_02"
                      item:
                        item_id: "KLT-003"
                        length: 0.6
                        width: 0.3
                        height: 0.2
                      source:
                        name: "HandoverStation-2-2-2"
                        station_name: "HandoverStation-2"
                      target:
                        name: "HandoverStation-3-3-2"
                        station_name: "HandoverStation-3"
                      sequence_nb: 1
      responses:
        200:
          description: OK
        400:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailureResponse'
              examples:
                Illegal order priority value:
                  value:
                    error: "Failed to update order ORDER_03. Reason 'priority' must be greater than 0"
                    id: "example_error_id"
          description: Error

        404:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailureResponse'
              examples:
                Order not found:
                  value:
                    error: "Failed to update non-existing order ORDER_03. New orders must be created via the POST endpoint"
                    id: "example_error_id"
          description: Error
      summary: Update an Order
      tags:
      - Orders
  /api/v1/wms/orders/{order_id}/cancel:
    put:
      description: |-
        Update the requests of an order by passing an updated order.
        Only requests which are not started or terminated yet will be updated.

        - 200: Order was canceled
        - 400: Order was not canceled (already terminated, assigned to a robot...)
        - 404: unknown order_id
      operationId: mfm_rest_api_wms_api_request_cancel_order
      parameters:
      - in: path
        name: order_id
        required: true
        schema:
          title: Order Id
          type: string
      responses:
        200:
          description: OK
        400:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailureResponse'
              examples:
                Order already terminated:
                  value:
                    error: "Order ORDER_01 has already been started."
                    id: "example_error_id"
          description: Error
        404:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailureResponse'
              examples:
                Order not found:
                  value:
                    error: "Failed to cancel order ORDER_03 because its id is unknown."
                    id: "example_error_id"
          description: Error
      summary: Cancel an Order
      tags:
      - Orders
  /api/v1/world/compartments:
    get:
      description: |-
        Get the compartments in the current environments.

        - 200: Valid request, return compartments
        - 400: Bad request
      operationId: mfm_rest_api_wms_api_request_world_compartments
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Container'
        400:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailureResponse'
          description: Error
      summary: Get the compartments in the current environment
      tags:
      - Environment