swagger.yaml

swagger: '2.0'
info:
  version: '1.0.0'
  title: "[Draft] Order API "
  description: |
    Template API conforming to adidas API Guidelines.
    This API is [documented at Apiary](http://docs.demotemplate.apiary.io)
    and [stored on GitHub](https://github.com/adidas-group/demo-orders-api).


produces:
  - application/hal+json      # Representation message format
  - application/problem+json  # Error message format

host: api.adidas.com

schemes:
  - https
  
securityDefinitions:
   "API Key":
     type: apiKey
     in: header
     name: x-api-key

security:
  - "API Key": []

paths:
  /:
    x-summary: API Root

    get:
      summary: Retrieve API Root
      description: The API Root contains the initial set of link relations.
      responses:
        200:
          description: The root of the API
          schema:
            $ref: '#/definitions/halRoot'

  /orders:
    x-summary: List of Orders

    get:
      summary: Retrieve List of Orders
      parameters:
        - name: offset
          in: query
          description: Number of results to skip from the start of the list
          required: false
          type: string
          default: '0'
          x-example: '10'
        - name: limit
          in: query
          description: The maximum number of reusults to return
          required: false
          type: string
          default: '10'
          x-example: '5'
      responses:
        200:
          description: The list of Orders
          schema:
            $ref: '#/definitions/halOrders'

    post:
      summary: Create a New Order
      consumes:
        - application/json
      parameters:
        - name: Order
          in: body
          description: Order to be created
          required: true
          schema:
            $ref: '#/definitions/order'
      responses:
        201:
          description: Newly created order
          schema:
            $ref: '#/definitions/halOrder'

  /orders/{order_id}:
    x-summary: Order
    
    parameters:
      - name: order_id
        in: path
        description: Id of the Order
        required: true
        type: string
        x-example: '1234'

    get:
      summary: Retrieve Order
      parameters:
        - name: fields
          in: query
          description: Comma-separated list of fields to include in the response
          required: false
          type: array
          items:
            type: string
          collectionFormat: csv
          x-example: 
            - orderNumber
            - status
      responses:
        200:
          description: A particular Order
          schema:
            $ref: '#/definitions/halOrder'
        404:
          description: The request Order wasn't found
          headers:
            Content-Type:
              type: string
              default: application/problem+json
          schema:
            $ref: '#/definitions/orderNotFound'

    patch:
      summary: Update Order
      consumes:
        - application/json
      parameters:
        - name: Order
          in: body
          description: Partial order update
          required: true
          schema:
            $ref: '#/definitions/orderPatch'
      responses:
        200:
          description: The Order was updated
          schema:
            $ref: '#/definitions/halOrder'

    delete:
      summary: Delete Order
      produces: []
      responses:
        204:
          description: The Order was deleted

definitions:
  #
  # API Root
  #
  halRoot:
    type: object
    allOf:
      - $ref: '#/definitions/halResource'
    example:
      _links:
        self:
          href: /
        orders:
          href: /orders

  #
  # Orders Resource
  #
  halOrders:
    type: object
    allOf:
      - $ref: '#/definitions/halResource'
    example:
      _links:
        self:
          href: /orders
          
        create:
          href: /orders
          
        next: 
          href: /orders?offset=5&limit=5
          
        first:
          href: /orders?offset=0&limit=5 
          
        last: 
          href: /orders?offset=40&limit=5          

      _embedded:
        order:
          - $ref: '#/definitions/halOrder/example'

  #
  # Order Resource
  #

  # HAL Wrapper
  halOrder:
    type: object
    allOf:
      - $ref: '#/definitions/halResource'
      - $ref: '#/definitions/order'
    example:
      _links:
        self:
          href: /orders/1234
          
        edit:
          href: /orders/1234

        delete: 
          href: /orders/1234
          
        profile:
          href: https://adidas-group.com/gdm/OMS
          
      orderNumber: 1234
      itemCount: 42
      status: pending

  # Partial Order
  orderPatch:
    type: object
    allOf:
      - $ref: '#/definitions/order'
    example:
      status: cancelled

  # Order
  order:
    type: object
    properties:
      orderNumber:
        type: number
      itemCount:
        type: number
      status:
        type: string
    required:
      - orderNumber
      - itemCount
    example:
      orderNumber: 42
      itemCount: 3
      status: pending

  # Order Not Found Error
  orderNotFound:
    type: object
    allOf:
      - $ref: '#/definitions/problemDetail'
    example:
      title: 'Not Found'
      detail: 'Cannot find the requested order'
      status: 404
      instance: '/orders/1234'

  #
  # -- DO NOT EDIT BEYOND THIS POINT --
  #

  # Media Types Definitions

  #
  # application/problem+json
  #
  problemDetail:
    type: object
    properties:
      type:
        type: string
      title:
        type: string
      status:
        type: number
      detail:
        type: string
      instance:
        type: string
    required:
      - title
      - detail

  #
  # application/hal+json defintion
  #
  halLinkObject:
    type: object
    required:
      - href
    properties:
      href:
        type: string
      templated:
        type: boolean
      #
      # WARN: Some version of OAS parser can have problem with property being called "type"
      # resulting in the error 'Schema "type" key must be a string'.
      #
      # For this reason we have commented out the "type" property of the link object.
      # See https://tools.ietf.org/html/draft-kelly-json-hal-08#section-5.3 for the definiton of 
      # HAL's link object type property.
      #
      # type:
      #  type: string
      deprecation:
        type: string
      name:
        type: string
      profile:
        type: string
      title:
        type: string
      hreflang:
        type: string

  halCuriesLink:
    title: HAL Curies Link
    allOf:
      - type: object
        properties:
          templated:
            enum:
              - true
        required:
          - templated
      - $ref: '#/definitions/halLinkObject'

  halResource:
    title: HAL Resource Object
    type: object
    properties:
      _links:
        type: object
        additionalProperties:
          # WARN: Should be "anyOf" but "anyOf" isn't supported in Swagger 2.0
          allOf:
            - $ref: '#/definitions/halLinkObject'
            - type: array
              items:
                - $ref: '#/definitions/halLinkObject'
        properties:
          curies:
            # WARN: Should be "anyOf" but "anyOf" isn't supported in Swagger 2.0
            allOf:
              - $ref: '#/definitions/halCuriesLink'
              - type: array
                items:
                  - $ref: '#/definitions/halCuriesLink'
      _embedded:
        type: object
        additionalProperties: true
        # WARN: Apiary doesn't support circular references
        # additionalProperties:
        #   anyOf:
        #     - $ref: '#/definitions/hal_resource'
        #     - type: array
        #       items:
        #         - $ref: '#/definitions/hal_resource'