.. _warehouses-api:

Warehouses API
==============

The ``/api/warehouses`` endpoint exposes the :ref:`Warehouse Model <warehouse-model>` as a resource. Warehouses contain
bin locations, which can in turn contain stock for individual products.

.. http:get:: /api/warehouses

    Query all warehouses or a subset of warehouses according to a set of criteria.

    :query integer start: the starting offset into the result list (default: 0)
    :query integer limit: the maximum number of results (default: 1000)
    :query object filter: a search filter (see :ref:`filter_and_sort_query_parameters`), with property names prefixed
        by ``warehouse.``, for example ``warehouse.name``
    :query object sort: a sorting specification (see :ref:`filter_and_sort_query_parameters`), with property names
        prefixed by ``warehouse.``, for example ``warehouse.name``

    :>json boolean success: whether the operation was successful
    :>json integer total: the total number of warehouses which matched the query
    :>json array data: an array of warehouses, see :ref:`the single-warehouse endpoint <get-warehouse>` for a description of the resource properties

    **Example request**:

    .. http:example:: curl wget httpie

        GET /api/warehouses HTTP/1.1
        Host: localhost
        Accept: application/json

    **Example response**:

    .. code-block:: http

        HTTP/1.1 200 OK
        Content-Type: application/json

        {
            "success": true,
            "total": 1,
            "data": [
                {
                    "id": 1,
                    "code": "MW",
                    "name": "Main Warehouse",
                    "stockAvailableForSale": true,
                    "defaultWarehouse": true,
                    "defaultReturnShipmentWarehouse": true,
                    "nullBinLocationId": 12,
                    "contact": "Jane Doe",
                    "email": "jane.doe@pickware.com",
                    "phone": "+1 93283 329493",
                    "address": "3793 Blair Court, Rockville MO",
                    "comment": "A comment",
                    "binLocationFormatComponents": []
                }
            ]
        }

.. _get-warehouse:

.. http:get:: /api/warehouses/{id}

    Fetch a warehouse by its database ID.

    :param integer id: the database ID of the warehouse to fetch

    :>json boolean success: whether the operation was successful
    :>json object data: the warehouse with the given ID
    :>json integer data.id: the database ID of the warehouse
    :>json string data.code: the warehouses's shorthand code
    :>json string data.name: the warehouse's readable name
    :>json boolean data.stockAvailableForSale: whether the stock inside the warehouse should count towards the available stock of the online shop
    :>json boolean data.defaultWarehouse: whether this is the default warehouse
    :>json boolean data.defaultReturnShipmentWarehouse: whether this is the default warehouse for return shipments
    :>json string data.nullBinLocationId: database ID of the unknown bin location of this warehouse
    :>json string data.contact: the name of the person responsible for the warehouse
    :>json string data.email: the email address of the person responsible for the warehouse
    :>json string data.phone: the phone number of the person responsible for the warehouse
    :>json string data.address: the street address of the warehouse
    :>json string data.comment: an arbitrary comment for the warehouse
    :>json array data.binLocationFormatComponents: a specification of the format for bin location codes

    **Example request**:

    .. http:example:: curl wget httpie

        GET /api/warehouses/2 HTTP/1.1
        Host: localhost
        Accept: application/json

    **Example response**:

    .. code-block:: http

        HTTP/1.1 200 OK
        Content-Type: application/json

        {
            "success": true,
            "data": {
                "id": 2,
                "code": "SW",
                "name": "Secondary Warehouse",
                "stockAvailableForSale": false,
                "defaultWarehouse": false,
                "defaultReturnShipmentWarehouse": false,
                "nullBinLocationId": 23,
                "contact": "",
                "email": "",
                "phone": "",
                "address": "",
                "comment": "",
                "binLocationFormatComponents": []
            }
        }

.. http:post:: /api/warehouses

    Create a new warehouse.

    :<json string code: the warehouses's shorthand code
    :<json string name: the warehouse's readable name
    :<json boolean stockAvailableForSale: whether the stock inside the warehouse should count towards the available stock of the online shop
    :<json string contact: the name of the person responsible for the warehouse
    :<json string email: the email address of the person responsible for the warehouse
    :<json string phone: the phone number of the person responsible for the warehouse
    :<json string address: the street address of the warehouse
    :<json string comment: an arbitrary comment for the warehouse
    :<json array binLocationFormatComponents: a specification of the format for bin location codes

    **Example request**:

    .. http:example:: curl wget httpie

        POST /api/warehouses HTTP/1.1
        Content-Type: application/json
        Host: localhost

        {
            "code": "W2",
            "name": "Second Warehouse",
            "stockAvailableForSale": false,
            "contact": "Jon Doe",
            "email": "jon.doe@pickware.com",
            "phone": "+1 93283 329493",
            "address": "3793 Blair Court, Rockville MO",
            "comment": "A comment"
        }

    **Example response**:

    .. code-block:: http

        HTTP/1.1 201 Created
        Content-Type: application/json

        {
            "success": true,
            "data": [
                {
                    "id": 3,
                    "location": "https://localhost/api/warehouses/3"
                }
            ]
        }

.. http:put:: /api/warehouses/{id}

    Update the warehouse with the given database ID using the data in the request body.

    :param integer id: the database ID of the warehouse to update

    :<json string code: the warehouses's shorthand code
    :<json string name: the warehouse's readable name
    :<json boolean stockAvailableForSale: whether the stock inside the warehouse should count towards the available stock of the online shop
    :<json string contact: the name of the person responsible for the warehouse
    :<json string email: the email address of the person responsible for the warehouse
    :<json string phone: the phone number of the person responsible for the warehouse
    :<json string address: the street address of the warehouse
    :<json string comment: an arbitrary comment for the warehouse
    :<json array binLocationFormatComponents: a specification of the format for bin location codes

    **Example request**:

    .. http:example:: curl wget httpie

        PUT /api/warehouses/3 HTTP/1.1
        Content-Type: application/json
        Host: localhost

        {
            "code": "RW",
            "name": "Return warehouse"
        }

    **Example response**:

    .. code-block:: http

        HTTP/1.1 200 OK
        Content-Type: application/json

        {
            "success": true
        }

.. http:delete:: /api/warehouses/{id}

    Delete the warehouse with the given database ID.

    :param integer id: the database ID of the warehouse to delete
    :statuscode 400: if the warehouse cannot be deleted because it is the default warehouse or the default return
        shipment warehouse, it still has bin locations or there's still stock in the warehouse

    **Example request**:

    .. http:example:: curl wget httpie

        DELETE /api/warehouses/3 HTTP/1.1
        Host: localhost

    **Example response**:

    .. code-block:: http

        HTTP/1.1 200 OK
        Content-Type: application/json

        {
            "success": true
        }