order.raml

#%RAML 1.0
title: Orders
baseUri: https://github.com/folio-org/mod-orders
version: v8.1
protocols: [ HTTP, HTTPS ]

documentation:
  - title: Orders Business Logic API
    content: <b>API for managing purchase orders</b>

types:
  composite-purchase-order: !include acq-models/mod-orders/schemas/composite_purchase_order.json
  purchase-order-collection: !include acq-models/mod-orders-storage/schemas/purchase_order_collection.json
  purchase_order: !include acq-models/mod-orders-storage/schemas/purchase_order.json
  errors: !include raml-util/schemas/errors.schema

  UUID:
    type: string
    pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$

traits:
  pageable: !include raml-util/traits/pageable.raml
  searchable: !include raml-util/traits/searchable.raml
  language: !include raml-util/traits/language.raml
  validate: !include raml-util/traits/validation.raml

resourceTypes:
  collection: !include rtypes/collection-with-json-response.raml
  collection-item: !include rtypes/item-collection-with-json-response.raml
  post-empty-body: !include raml-util/rtypes/post-empty-body.raml


/orders/composite-orders:
    displayName: Orders
    type:
      collection:
        exampleCollection: !include acq-models/mod-orders-storage/examples/purchase_order_collection.sample
        exampleItem: !include acq-models/mod-orders/examples/composite_purchase_order.sample
        schemaCollection: purchase-order-collection
        schemaItem: composite-purchase-order
    is: [validate]
    get:
      is: [pageable, searchable: {description: "using CQL (indexes for purchase orders)", example: "workflow_status==\"Pending\""} ]
    post:
      description: Post a purchase order (PO) and a number of PO lines; record fund transactions corresponding to the order. Only in case an acquisition unit has to be assigned to the Order it is required that user should have extra permission orders.acquisitions-units-assignments.item.post to create an purchase order.
    /{id}:
      uriParameters:
        id:
          description: The UUID of a purchase order
          type: UUID
      type:
        collection-item:
          exampleItem: !include acq-models/mod-orders/examples/composite_purchase_order.sample
          schema: composite-purchase-order
      is: [validate]
      get:
        description: Return a purchase order with given {id}
      put:
        description: |
          Update a purchase order with given {id}
          - if request does not include po_lines or includes "po_lines": [] or "po_lines": null - update just purchase order summary
          - if request includes array of "po_lines" - update PO lines as per request
      delete:
        description: Delete a purchase order with given {id}
      /re-encumber:
        is: [language]
        post:
          responses:
            204:
              description: "Re-encumber completed successfully"
            400:
              description: "Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response."
              body:
                application/json:
                  example:
                    strict: false
                    value: !include raml-util/examples/errors.sample
                text/plain:
                  example: |
                    "unable to add <<resourcePathName|!singularize>> -- malformed JSON at 13:3"
            404:
              description: "Item with a given ID not found"
              body:
                application/json:
                  example:
                    strict: false
                    value: !include raml-util/examples/errors.sample
                text/plain:
                  example: |
                    "<<resourcePathName|!singularize>> not found"
            500:
              description: "Internal server error, e.g. due to misconfiguration"
              body:
                application/json:
                  example:
                    strict: false
                    value: !include raml-util/examples/errors.sample
                text/plain:
                  example: "Internal server error, contact administrator"