ReferenceDataAPI.yaml

# Example YAML to get you started quickly.
# Be aware that YAML has indentation based scoping.
# Code completion support is available so start typing for available options.
swagger: '2.0'

# This is your document metadata
info:
  version: "0.0.1"
  title: Enterprise Reference Data Service

host: 
  au2109lp2286
# Describe your paths here
paths:
  # This is a path endpoint. Change it.
  /api/categories:
    # This is a HTTP operation
    get:
      # Describe this verb here. Note: you can use markdown
      description: |
        Gets all `Category` summary data for all reference data categories available.
      # This is array of GET operation parameters:
      parameters:
        # An example parameter that is in path and is required
        -
          name: fields
          in: query
          description: A qualifier used to define the fields to be returned in the response.
          required: false
          type: string
        #-
        #  name: limit
        #  in: query
        #  description: a qualifier used to define the maximum number of records to be returned in the response. Used for pagination.
        #  required: false
        #  type: number
        #  format: integer
        #-
        #  name: offset
        #  in: query
        #  description: a qualifier used to define the number of records to skip before returning data in the response. Used for pagination.
        #  required: false
        #  type: number
        #  format: integer
      # Expected responses for this operation:
      responses:
        # Response code
        200:
          description: Successful response
          # A schema describing your response object.
          # Use JSON Schema format
          schema:
            title: ArrayOfCategories
            type: array
            items:
              $ref: '#/definitions/CategorySummary'
        204:
          description: No data available
          # A schema describing your response object.
          # Use JSON Schema format
          schema:
            title: ArrayOfCategories
            type: array
            items:
              $ref: '#/definitions/CategorySummary'
        # Client Errors
        400:
          description: Bad Request
          schema:
            type: object          
            properties:
              status:
                type: string
                enum:
                  - fail
              data:
                $ref: '#/definitions/ErrorModel'
        # Server Errors
        500:
          description: Internal Server Error
          schema:
            type: object          
            properties:
              status:                         #error
                type: string
                enum:
                  - error
              data:
                $ref: '#/definitions/ErrorModel'
  # This is a path endpoint. Change it.
  /api/categories/{categoryName}:
    # This is a HTTP operation
    get:
      # Describe this verb here. Note: you can use markdown
      description: |
        Gets the details of all the codes that are defined within the `Category`.
        Required path params of **categoryName** and **categoryVersion** determines the record to be returned
      # This is array of GET operation parameters:
      parameters:
        # An example parameter that is in path and is required
        -
          name: categoryName
          in: path
          description: Name of enterprise reference data Category
          required: true
          type: string
          format: string
        -
          name: categoryVersion
          in: query
          description: Qualifies the major version of reference data category.
          required: false
          type: string
          format: string
        #-
        #  name: fields
        #  in: query
        #  description: A qualifier used to define the fields to be returned in the response.
        #  required: false
        #  type: string
        #-
        #  name: limit
        #  in: query
        #  description: a qualifier used to define the maximum number of records to be returned in the response. Used for pagination.
        #  required: false
        #  type: number
        #  format: integer
        #-
        #  name: offset
        #  in: query
        #  description: a qualifier used to define the number of records to skip before returning data in the response. Used for pagination.
        #  required: false
        #  type: number
        #  format: integer
      # Expected responses for this operation:
      responses:
        # Response code
        200:
          description: Successful response
          # A schema describing your response object.
          # Use JSON Schema format
          schema:
            title: ArrayOfCategories
            type: array
            items:
              $ref: '#/definitions/CategoryDetails'
        204:
          description: No data available
          # A schema describing your response object.
          # Use JSON Schema format
          schema:
            title: ArrayOfCategories
            type: array
            items:
              $ref: '#/definitions/CategoryDetails'
        # Client Errors
        400:
          description: Bad Request
          schema:
            type: object          
            properties:
              status:
                type: string
                enum:
                  - fail
              data:
                $ref: '#/definitions/ErrorModel'
        # Server Errors
        500:
          description: Internal Server Error
          schema:
            type: object          
            properties:
              status:                         #error
                type: string
                enum:
                  - error
              data:
                $ref: '#/definitions/ErrorModel'
  # This is a path endpoint. Change it.
  /api/categories/{categoryName}/codes:
    # This is a HTTP operation
    get:
      # Describe this verb here. Note: you can use markdown
      description: |
        Gets all codes of the `Category`. Use fields parameter to return specific canonical or system codes.
      # This is array of GET operation parameters:
      parameters:
        # An example parameter that is in path and is required
        -
          name: categoryName
          in: path
          description: Name of enterprise reference data Category
          required: true
          type: string
          format: string
        -
          name: categoryVersion
          in: query
          description: Qualifies the major version of reference data category.
          required: false
          type: string
          format: string
        -
          name: codeType
          in: query
          description: Qualifies if canonical or system codes are required.  For system should use Application Inventory ID of the system without '-' (hyphen). Example 'canonical' or 'CV002' for UCM
          required: false
          type: string
          format: string
        -
          name: fields
          in: query
          description: A qualifier used to define the fields to be returned in the response.
          required: false
          type: string
        #-
        #  name: limit
        #  in: query
        #  description: a qualifier used to define the maximum number of records to be returned in the response. Used for pagination.
        #  required: false
        #  type: number
        #  format: integer
        #-
        #  name: offset
        #  in: query
        #  description: a qualifier used to define the number of records to skip before returning data in the response. Used for pagination.
        #  required: false
        #  type: number
        #  format: integer
      # Expected responses for this operation:
      responses:
        # Response code
        200:
          description: Successful response
          # A schema describing your response object.
          # Use JSON Schema format
          schema:
            title: ArrayOfCategoryCodes
            type: array
            items:
              $ref: '#/definitions/Codes' 
        # Client Errors
        400:
          description: Bad Request
          schema:
            type: object          
            properties:
              status:
                type: string
                enum:
                  - fail
              data:
                $ref: '#/definitions/ErrorModel'
        # Server Errors
        500:
          description: Internal Server Error
          schema:
            type: object          
            properties:
              status:                         #error
                type: string
                enum:
                  - error
              data:
                $ref: '#/definitions/ErrorModel'
  # This is a path endpoint. Change it.
  /api/categories/{categoryName}/codes/{code}:
    # This is a HTTP operation
    get:
      # Describe this verb here. Note: you can use markdown
      description: |
        Gets the code record for the given canonical **code**. If **not** a canonical code value then the **sourceCodeTypeQualifer** query param is required as it qualifies which syste the code belongs to
      # This is array of GET operation parameters:
      parameters:
        # An example parameter that is in query and is required
        -
          name: categoryName
          in: path
          description: The name of the reference data category
          required: true
          type: number
          format: string
        -
          name: categoryVersion
          in: query
          description: Qualifies the major version of reference data category
          required: false
          type: string
          format: string
        -
          name: code
          in: path
          description: Qualifies the code value of the document
          required: true
          type: number
          format: string
        -
          name: sourceCodeTypeQualifier
          in: query
          description: Qualifies if the code is the canonical or a system code. For system should use Application Inventory ID of the system without '-' (hyphen). Example 'CV002' to qualify that the code is the UCM system code. If not provided it is assumed the code is the canonical code
          required: false
          type: number
          format: string
        -
          name: fields
          in: query
          description: A qualifier used to define the fields to be returned in the response.
          required: false
          type: string
      # Expected responses for this operation:
      responses:
        # Response code
        200:
          description: Successful response
          # A schema describing your response object.
          # Use JSON Schema format
          schema:
            title: ArrayOfCodes
            type: array
            items:
              $ref: '#/definitions/Codes'
        # Client Errors
        400:
          description: Bad Request
          schema:
            type: object          
            properties:
              status:
                type: string
                enum:
                  - fail
              data:
                $ref: '#/definitions/ErrorModel'
        # Server Errors
        500:
          description: Internal Server Error
          schema:
            type: object          
            properties:
              status:                         #error
                type: string
                enum:
                  - error
              data:
                $ref: '#/definitions/ErrorModel'
definitions:
  Codes:
    discriminator: canonicalCode
    required:
      - category
      - version # required for inheritance to work
      - canonicalCode
    properties:
      category: 
        type: string
      version:
        type: string
      canonicalCode:
        type: string
      description:
        type: string
      system1Code:
        type: string
      system2Code:
        type: string
        
  CategorySummary:
    discriminator: canonicalCode
    required:
      - category
      - version # required for inheritance to work
    properties:
      category: 
        type: string
      version:
        type: string
      description:
        type: string

  CategoryDetails:
    discriminator: canonicalCode
    required:
      - category
      - version # required for inheritance to work
    properties:
      category: 
        type: string
      version:
        type: string
      description:
        type: string
      codes:
        type: array
        items:
          $ref: '#/definitions/Codes'
  #The common error object        
  ErrorModel:
    description: Represents the error Model, returned in case of error conditions
    type: object
    properties:
      errorList:
        type: array
        items:
          $ref: '#/definitions/Error'

  # Individual Error Object
  Error:
    description:  Represent an invidual error.
    type: object
    properties:
      code:
        description:  Error Code.
        type: integer
        format: int32
      message:
        description:  Error Message
        type: string
      fields:
        description: Comma seperated list of fields, which caused the error condition.
        type: string