#%RAML 0.8
title: Product Inventory
version: "1.0.0"
baseUri: "https://openlmis.org:443/api"
schemas: 
    - 
        StockEvent: '{"type":"object","$schema":"http://json-schema.org/draft-03/schema#","description":"Similar to v2 stock management, this needs some additional details.  Preferred to move to event-oriented architecture for listening for events which influence stock (e.g. reserve stock, issue, receive, adjust)","title":"StockEvent","properties":{"uuid":{"type":"string","required":false,"title":"uuid"},"quantity":{"type":"integer","required":true,"title":"quantity"},"globalProductUUID":{"type":"string","required":true,"title":"globalProductUUID"},"logisticsLocation":{"type":"string","required":true,"title":"logisticsLocation"},"occurred":{"type":"string","required":true,"title":"occurred"},"lotUUID":{"type":"string","required":false,"title":"lotUUID"},"itemUUID":{"type":"string","required":true,"title":"itemUUID"}}}'
    - 
        GlobalProductInventory: '{"type":"object","$schema":"http://json-schema.org/draft-03/schema#","description":"An inventory by Global Product","title":"GlobalProductInventory","properties":{"UUID":{"type":"string","required":true,"title":"UUID"},"shortName":{"type":"string","required":true,"title":"shortName"},"longName":{"type":"string","required":true,"title":"longName"},"balance":{"type":"object","$ref":"#/schemas/StockBalance","required":false,"title":"balance"}}}'
    - 
        StockBalance: |
                {"type":"object","$schema":"http://json-schema.org/draft-03/schema#","description":"Quantities of stock, in the product's dispensing units.","title":"StockBalance","properties":{"onHand":{"type":"integer","required":true,"title":"onHand"},"available":{"type":"integer","required":true,"title":"available"}}}
    - 
        TradeItemInventory: '{"type":"object","$schema":"http://json-schema.org/draft-03/schema#","description":"An inventory of a trade item","title":"TradeItemInventory","properties":{"uuid":{"type":"string","required":true,"title":"uuid"},"balance":{"type":"object","$ref":"#/schemas/StockBalance","required":true,"title":"balance"},"lots":{"type":"array","required":false,"title":"lots","items":{"type":"object","$ref":"#/schemas/LotInventory"},"uniqueItems":false},"totalBalance":{"type":"integer","required":false,"title":"totalBalance"}}}'
    - 
        LotInventory: |
                {"type":"object","$schema":"http://json-schema.org/draft-03/schema#","description":"An accounting of a manufacturer's lot","title":"LotInventory","properties":{"lot":{"type":"string","required":true,"title":"lot"},"balance":{"type":"object","$ref":"#/schemas/StockBalance","required":true,"title":"balance"}}}
/stockEvent: 
    displayName: Record changes to stock levels
    description: A stock event captures changes to stocking levels.  This may be due to a stock movement (issue or receipt), usage, waste, etc.  Single stock events may result in more than one stocking location's stock being updated. This is mostly functionality from v2, and I believe we should investigate event-oriented architecture here rather than specifying a single representation - which was problematic in v2.
    post: 
        body: 
            application/json: 
                schema: StockEvent
                example: '[{"uuid":"sample uuid","quantity":1,"globalProductUUID":"sample globalProductUUID","logisticsLocation":"sample logisticsLocation","occurred":null,"lotUUID":"sample lotUUID","supplierProductUUID":"sample supplierProductUUID"}]'
        responses: 
            "202": 
                description: StockEvents have been accepted for processing
            "400": 
                description: One or more Stock Event's are malformed
            "401": 
                description: Your permission levels are not allowed to post one or more stock events
/logisticsLocations/{logisticsLocation}/globalProducts/{globalProduct}: 
    displayName: Global Product Inventory at a Logistics Location
    uriParameters: 
        globalProduct: 
            displayName: globalProduct
            description: UUID of given Logistic Location
            type: string
            required: false
            repeat: false
        logisticsLocation: 
            displayName: logisticsLocation
            description: UUID of Logistic Location
            type: string
            required: false
            repeat: false
    get: 
        responses: 
            "200": 
                description: The request has succeeded
                body: 
                    application/json: 
                        schema: GlobalProductInventory
                        example: '{"UUID":"sample UUID","shortName":"sample shortName","longName":"sample longName","balance":null}'
            "401": 
                description: Permission's are insufficient to access inventory for stocking location
            "404": 
                description: Global Product not found
/logisticsLocations/{logisticsLocation}/tradeItems/{tradeItem}: 
    displayName: Inventory of a trade item
    description: Inventory of a trade item.  aka Supplier Catalog Item in the Logical Model.
    uriParameters: 
        logisticsLocation: 
            displayName: logisticsLocation
            type: string
            required: false
            repeat: false
        tradeItem: 
            displayName: tradeItem
            description: The UUID of a given trade item
            type: string
            required: false
            repeat: false
    get: 
        responses: 
            "200": 
                description: The request has succeeded
                body: 
                    application/json: 
                        schema: TradeItemInventory
                        example: '[{"uuid":"sample uuid","balance":null,"lots":[],"totalBalance":1}]'