swagger: '2.0'

info:
  title: eHealth SSL Catalogue service
  version: 1.0.0
  termsOfService: http://ehealth.sundhed.dk/terms/
  license:
    name: Proprietary

host: ssl-catalogue.ehealth.sundhed.dk
basePath: /v1

tags:
  - name: Catalogue
    description: Operations with catalogs
  - name: CatalogueItem
    description: Operations with catalogue items
  - name: Annotation
    description: Operations with annotations
  - name: WhiteList
    description: Operations with white lists
  - name: BlackList
    description: Operations with black lists

schemes:
  - http
  - https

paths:
  /catalogue:
    post:
      operationId: createCatalogue
      summary: Create a new Catalogue.
      consumes:
        - application/json
      tags:
        - Catalogue
      parameters:
        - name: catalogue
          in: body
          required: true
          schema:
            $ref: '#/definitions/Catalogue'
        - name: matchCatalogueByIdentifier
          in: query
          required: false
          type: boolean
      responses:
        201:
          description: The Catalogue was successfully created.
          headers:
            Location:
              type: string
              format: uri
              description: The location of the newly created Catalogue.
        400:
          description: The request could not be understood
          schema:
            $ref: '#/definitions/Error'
        500:
          description: The server encountered an unexpected condition which prevented it from fulfilling the request.
          schema:
            $ref: '#/definitions/Error'
        default:
          description: 'Unexpected error'
          schema:
            $ref: '#/definitions/Error'

    put:
      summary: Update a Catalogue.
      consumes:
        - application/json
      description: id property is required.
      tags:
        - Catalogue
      operationId: updateCatalogue
      parameters:
        - name: catalogue
          in: body
          required: true
          schema:
            $ref: '#/definitions/Catalogue'
      responses:
        204:
          description: The Catalogue was successfully updated.
        400:
          description: The request could not be understood.
          schema:
            $ref: '#/definitions/Error'
        500:
          description: The server encountered an unexpected condition which prevented it from fulfilling the request.
          schema:
            $ref: '#/definitions/Error'
        default:
          description: unexpected error
          schema:
            $ref: '#/definitions/Error'

  /catalogue/{id}:
    get:
      summary: Get a Catalogue
      produces:
        - application/json
      tags:
        - Catalogue
      operationId: getCatalogue
      parameters:
        - name: id
          in: path
          required: true
          description: The id of the Catalogue to get.
          type: string
      responses:
        200:
          description: The requested Catalogue was found.
          schema:
            $ref: '#/definitions/Catalogue'
        404:
          description: Catalogue not found
          schema:
            $ref: '#/definitions/Error'
        default:
          description: unexpected error
          schema:
            $ref: '#/definitions/Error'

  /catalogues:
    get:
      operationId: listCatalogues
      summary: 'List all catalogues.'
      produces:
        - application/json
      tags:
        - Catalogue
      parameters:
        - name: seller
          in: query
          required: true
          type: string
      responses:
        200:
          description: Successfully listed all matching Catalogues.
          schema:
            type: array
            items:
              $ref: '#/definitions/Catalogue'
        400:
          description: The request could not be understood.
          schema:
            $ref: '#/definitions/Error'
        500:
          description: The server encountered an unexpected condition which prevented it from fulfilling the request.
          schema:
            $ref: '#/definitions/Error'
        default:
          description: unexpected error
          schema:
            $ref: '#/definitions/Error'

  /catalogue-item:
    post:
      operationId: createCatalogueItem
      summary: Create a new CatalogueItem.
      consumes:
        - application/json
      tags:
        - CatalogueItem
      parameters:
        - name: catalogueItem
          in: body
          required: true
          schema:
            $ref: '#/definitions/CatalogueItem'
      responses:
        201:
          description: The CatalogueItem was successfully created.
          headers:
            Location:
              type: string
              format: uri
              description: The location of the newly created CatalogueItem.
        400:
          description: The request could not be understood
          schema:
            $ref: '#/definitions/Error'
        500:
          description: The server encountered an unexpected condition which prevented it from fulfilling the request.
          schema:
            $ref: '#/definitions/Error'
        default:
          description: 'Unexpected error'
          schema:
            $ref: '#/definitions/Error'

    put:
      summary: Update a CatalogueItem.
      consumes:
        - application/json
      description: id property is required.
      tags:
        - CatalogueItem
      operationId: updateCatalogueItem
      parameters:
        - name: catalogueItem
          in: body
          required: true
          schema:
            $ref: '#/definitions/CatalogueItem'
      responses:
        204:
          description: The CatalogueItem was successfully updated.
        400:
          description: The request could not be understood.
          schema:
            $ref: '#/definitions/Error'
        404:
          description: The CatalogueItem not found
          schema:
            $ref: '#/definitions/Error'
        500:
          description: The server encountered an unexpected condition which prevented it from fulfilling the request.
          schema:
            $ref: '#/definitions/Error'
        default:
          description: unexpected error
          schema:
            $ref: '#/definitions/Error'

  /catalogue-item/{id}:
    get:
      summary: Get a CatalogueItem
      produces:
        - application/json
      tags:
        - CatalogueItem
      operationId: getCatalogueItem
      parameters:
        - name: id
          in: path
          required: true
          description: The id of the CatalogueItem to get.
          type: string
      responses:
        200:
          description: The requested CatalogueItem was found.
          schema:
            $ref: '#/definitions/CatalogueItem'
        404:
          description: CatalogueItem not found
          schema:
            $ref: '#/definitions/Error'
        default:
          description: unexpected error
          schema:
            $ref: '#/definitions/Error'

  /catalogue-items:
    post:
      operationId: createCatalogueItems
      summary: Create new CatalogueItems.
      consumes:
        - application/json
      tags:
        - CatalogueItem
      parameters:
        - name: catalogueItems
          in: body
          required: true
          schema:
            type: array
            items:
              $ref: '#/definitions/CatalogueItem'
      responses:
        201:
          description: The CatalogueItems were successfully created.
          schema:
            type: array
            items:
              $ref: '#/definitions/CatalogueItem'
        400:
          description: The request could not be understood
          schema:
            $ref: '#/definitions/Error'
        500:
          description: The server encountered an unexpected condition which prevented it from fulfilling the request.
          schema:
            $ref: '#/definitions/Error'
        default:
          description: 'Unexpected error'
          schema:
            $ref: '#/definitions/Error'

    get:
      operationId: listCatalogueItems
      summary: List all CatalogueItems.
      produces:
        - application/json
      tags:
        - CatalogueItem
      parameters:
        - name: catalogue
          in: query
          type: string
          description: List only CatalogueItems from this Catalogue
        - name: buyer
          in: query
          required: true
          type: string
          description: List matching CatalogueItems across all Catalogues available to this buyer.
        - name: patient
          in: query
          type: string
          description: Patient for which the CatalogueItems will be delivered. CatalogueItems should not be black-listed with the given stated Patient.
        - in: query
          name: annotation
          required: true
          collectionFormat: multi
          type: array
          items:
            type: string
          description: Matching CatalogueItems must be associated with all of the mentioned Annotation values. Example annotation=http\://ehealth.sundhed.dk/vs/device-measuring-quality/low
      responses:
        200:
          description: Successfully listed all matching CatalogueItems.
          schema:
            type: array
            items:
              $ref: '#/definitions/CatalogueItem'
        400:
          description: The request could not be understood.
          schema:
            $ref: '#/definitions/Error'
        500:
          description: The server encountered an unexpected condition which prevented it from fulfilling the request.
          schema:
            $ref: '#/definitions/Error'
        default:
          description: unexpected error
          schema:
            $ref: '#/definitions/Error'

  /annotation:
    post:
      operationId: createAnnotation
      summary: Create a new Annotation.
      consumes:
        - application/json
      tags:
        - Annotation
      parameters:
        - name: annotation
          in: body
          required: true
          schema:
            $ref: '#/definitions/Annotation'
      responses:
        201:
          description: The Annotation was successfully created.
          headers:
            Location:
              type: string
              format: uri
              description: The location of the newly created Annotation.
        400:
          description: 'The request could not be understood'
          schema:
            $ref: '#/definitions/Error'
        500:
          description: The server encountered an unexpected condition which prevented it from fulfilling the request.
          schema:
            $ref: '#/definitions/Error'
        default:
          description: 'Unexpected error'
          schema:
            $ref: '#/definitions/Error'

    put:
      operationId: updateAnnotation
      summary: Update an Annotation.
      consumes:
        - application/json
      description: id property is required.
      tags:
        - Annotation
      parameters:
        - name: annotation
          in: body
          required: true
          schema:
            $ref: '#/definitions/Annotation'
      responses:
        204:
          description: The Annotation was successfully updated.
        400:
          description: The request could not be understood.
          schema:
            $ref: '#/definitions/Error'
        500:
          description: The server encountered an unexpected condition which prevented it from fulfilling the request.
          schema:
            $ref: '#/definitions/Error'
        default:
          description: unexpected error
          schema:
            $ref: '#/definitions/Error'

  /annotation/{id}:
    delete:
      operationId: deleteAnnotation
      summary: Delete an Annotation
      description: Only draft Annotations can be deleted.
      tags:
        - Annotation
      parameters:
        - name: id
          in: path
          required: true
          description: The id of the Annotation to delete
          type: string
      responses:
        204:
          description: The Annotation was successfully deleted.
        400:
          description: The request could not be understood.
          schema:
            $ref: '#/definitions/Error'
        500:
          description: The server encountered an unexpected condition which prevented it from fulfilling the request.
          schema:
            $ref: '#/definitions/Error'
        default:
          description: unexpected error
          schema:
            $ref: '#/definitions/Error'

  /annotations:
    get:
      operationId: listAnnotations
      summary: List Annotations.
      produces:
        - application/json
      tags:
        - Annotation
      parameters:
        - name: buyer
          required: true
          in: query
          type: string
          description: List Annotations related to this buyer
        - name: catalogueItem
          in: query
          required: true
          description: List Annotations related to this CatalogueItem
          type: string
      responses:
        200:
          description: Successfully listed all matching Annotations.
          schema:
            type: array
            items:
              $ref: '#/definitions/Annotation'
        400:
          description: The request could not be understood.
          schema:
            $ref: '#/definitions/Error'
        500:
          description: The server encountered an unexpected condition which prevented it from fulfilling the request.
          schema:
            $ref: '#/definitions/Error'
        default:
          description: unexpected error
          schema:
            $ref: '#/definitions/Error'

  /white-list:
    post:
      tags:
        - WhiteList
      summary: Create new white list
      consumes:
        - application/json
      description: Create new white list
      operationId: createWhiteList
      parameters:
        - name: whiteList
          in: body
          description: The white list which should be created.
          required: true
          schema:
            $ref: '#/definitions/WhiteList'
      responses:
        201:
          description: The white list was successfully created
          headers:
            location:
              type: string
              format: uri
              description: The location of the newly created white list.
        400:
          description: Invalid input
          schema:
            $ref: '#/definitions/Error'
        500:
          description: The server encountered an unexpected condition which prevented it from fulfilling the request
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    get:
      tags:
        - WhiteList
      summary: Search white lists by parameters
      produces:
        - application/json
      description: Search white list by parameters
      operationId: getWhiteLists
      parameters:
        - name: buyer
          in: query
          description: Multiple buyer refernce values can be provided
          type: array
          items:
            type: string
          collectionFormat: multi
      responses:
        200:
          description: List of white lists was successfully returned
          schema:
            type: array
            items:
              $ref: '#/definitions/WhiteList'
        400:
          description: Invalid input
          schema:
            $ref: '#/definitions/Error'
        500:
          description: The server encountered an unexpected condition which prevented it from fulfilling the request
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'

  /white-list/{id}:
    get:
      tags:
        - WhiteList
      summary: Return white list by id
      produces:
        - application/json
      description: Return white list by id
      operationId: getWhiteListById
      parameters:
        - name: id
          in: path
          description: Id of white list
          required: true
          type: string
      responses:
        200:
          description: The white list was successfully returned
          schema:
            $ref: '#/definitions/WhiteList'
        400:
          description: Invalid input
          schema:
            $ref: '#/definitions/Error'
        404:
          description: The black list not found
          schema:
            $ref: '#/definitions/Error'
        500:
          description: The server encountered an unexpected condition which prevented it from fulfilling the request
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    delete:
      operationId: deleteWhiteList
      summary: Delete White List
      tags:
        - WhiteList
      parameters:
        - name: id
          in: path
          required: true
          description: The id of the white list to delete
          type: string
      responses:
        204:
          description: The white list was successfully deleted.
        400:
          description: Invalid input
          schema:
            $ref: '#/definitions/Error'
        500:
          description: The server encountered an unexpected condition which prevented it from fulfilling the request.
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'

  /black-list:
    post:
      tags:
        - BlackList
      summary: Create new black list
      consumes:
        - application/json
      description: Create new black list
      operationId: createBlackList
      parameters:
        - name: blackList
          in: body
          description: black list which should be created.
          required: true
          schema:
            $ref: '#/definitions/BlackList'
      responses:
        201:
          description: The black list was successfully created
          headers:
            location:
              type: string
              format: uri
              description: The location of the newly created black list.
        400:
          description: Invalid input
          schema:
            $ref: '#/definitions/Error'
        500:
          description: The server encountered an unexpected condition which prevented it from fulfilling the request
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    get:
      tags:
        - BlackList
      summary: Search black lists by parameters
      produces:
        - application/json
      description: Search black list by parameters
      operationId: getBlackLists
      parameters:
        - name: patient
          in: query
          description: Multiple patient in clinical domain refernce values can be provided
          type: array
          items:
            type: string
            pattern: ^(?!\s*$).+
          collectionFormat: multi
      responses:
        200:
          description: List of black lists was successfully returned
          schema:
            type: array
            items:
              $ref: '#/definitions/BlackList'
        400:
          description: Invalid input
          schema:
            $ref: '#/definitions/Error'
        500:
          description: The server encountered an unexpected condition which prevented it from fulfilling the request
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'

  /black-list/{id}:
    get:
      tags:
        - BlackList
      summary: Return black list by id
      produces:
        - application/json
      description: Return black list by id
      operationId: getBlackListById
      parameters:
        - name: id
          in: path
          description: Id of black list
          required: true
          type: string
      responses:
        200:
          description: The black list was successfully returned
          schema:
            $ref: '#/definitions/BlackList'
        400:
          description: Invalid input
          schema:
            $ref: '#/definitions/Error'
        404:
          description: The black list not found
          schema:
            $ref: '#/definitions/Error'
        500:
          description: The server encountered an unexpected condition which prevented it from fulfilling the request
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    delete:
      operationId: deleteBlackList
      summary: Delete Black List
      tags:
        - BlackList
      parameters:
        - name: id
          in: path
          required: true
          description: The id of the black list to delete
          type: string
      responses:
        204:
          description: The black list was successfully deleted.
        400:
          description: Invalid input
          schema:
            $ref: '#/definitions/Error'
        500:
          description: The server encountered an unexpected condition which prevented it from fulfilling the request.
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'

definitions:
  Catalogue:
    type: object
    properties:
      id:
        type: string
        description: Unique ID of this catalogue.
        readOnly: true
        example: 432542
      identifiers:
        type: array
        items:
          $ref: '#/definitions/Identifier'
        description: Identifiers to connect Catalogue to external content available in other frameworks or protocols.
      seller:
        type: string
        description: Reference to SellerSupplierParty who offers the items in this catalogue.
        example: https://ssl-order.ehealth.sundhed.dk/v1/party/312
      name:
        type: string
        pattern: '^(?!\s*$).+'
        description: A human readable short headline describing this catalogue.
        example: Year 2020 catalogue
      status:
        $ref: '#/definitions/CatalogueStatus'
    required:
      - name
      - status

  CatalogueItem:
    type: object
    discriminator: catalogueItemType
    properties:
      id:
        type: string
        description: Unique ID of this catalogue item.
        readOnly: true
        example: 423341
      catalogueItemType:
        type: string
        description: Type discriminator. Legal values are "DeviceModel" and "Service".
        example: 'DeviceModel'
      identifiers:
        type: array
        items:
          $ref: '#/definitions/Identifier'
        description: Identifiers to connect CatalogueItem to external content available in other frameworks or protocols.
      relatedTo:
        type: string
        description: Reference to releted catalog item. Or can be number that points to index in the list of catalogue items.
        example: https://ssl-catalogue.ehealth.sundhed.dk/v1/catalogue-item/11
      catalogue:
        type: string
        description: Reference to catalog, this item belongs to.
        example: https://ssl-catalogue.ehealth.sundhed.dk/v1/catalogue/213
      name:
        type: string
        pattern: '^(?!\s*$).+'
        description: A human readable short headline describing this catalogue item.
        example: StarTron SuperSpiro VI
      description:
        type: string
        description: A human readable detailed of this catalogue item (markdown format supported).
        example: Multipurpose spirometer for wheel chair mounting. Battery supply only. No powerbrick.
      status:
        $ref: '#/definitions/CatalogueItemStatus'
      supersededBy:
        type: string
        description: Refernce to another catalogue item which supersedes this one. Or can be number that points to index in the list of catalogue items.
        example: https://ssl-catalogue.ehealth.sundhed.dk/v1/device-model/99822
    required:
      - catalogue
      - catalogueItemType
      - name
      - status

  DeviceModel:
    allOf:
      - $ref: '#/definitions/CatalogueItem'
      - type: object
        properties:
          manufacturer:
            type: string
            description: Name of the device manufacturer.
            example: Startron
          model:
            type: string
            description: The "model" is an identifier assigned by the manufacturer to identify the product by its type.
            example: SuperSpiro VI
          version:
            type: string
            description: The version of the device, if the device has multiple releases under the same model.
            example: 2019.02

  Service:
    allOf:
      - $ref: '#/definitions/CatalogueItem'
      - type: object
        properties:
          serviceType:
            $ref: '#/definitions/Coding'

  Annotation:
    type: object
    properties:
      id:
        type: string
        description: Unique ID of this annotation.
        readOnly: true
        example: "42352"
      catalogueItem:
        type: string
        description: Reference to Catalogue item which is annotated by this resource.
        example: https://ssl-catalogue.ehealth.sundhed.dk/v1/catelogue-item/4342
      buyer:
        type: string
        description: Reference to BuyerCustomerParty for whom this annotation is relevant.
        example: https://ssl-order.ehealth.sundhed.dk/v1/party/313
      status:
        $ref: '#/definitions/AnnotationStatus'
      value:
        $ref: '#/definitions/Coding'
    required:
      - catalogueItem
      - coding

  WhiteList:
    type: object
    required:
      - buyer
    properties:
      id:
        type: string
        description: Unique ID of this white list. Assigned by server
        example: 2
      buyer:
        type: string
        #pattern: ^((http[s]?):\/)?\/?([^:\/\s]+)((\/\w+)*\/)([\w\-\.]+[^#?\s]+)(.*)?(#[\w\-]+)?$
        example: http://ssl-order.ehealth.sundhed.dk/v1/party/456
        description: A reference to the party/organization for which this white list is relavant. Pattern should be used ^((http[s]?):\/)?\/?([^:\/\s]+)((\/\w+)*\/)([\w\-\.]+[^#?\s]+)(.*)?(#[\w\-]+)?$
      item:
        type: string
        #          pattern: ^((http[s]?):\/)?\/?([^:\/\s]+)((\/\w+)*\/)([\w\-\.]+[^#?\s]+)(.*)?(#[\w\-]+)?$
        example: ['http://ssl-catalogue.ehealth.sundhed.dk/v1/device-model/458', 'http://ssl-catalogue.ehealth.sundhed.dk/v1/device-model/459']
        description: References to CatalogueItems which are available to buyer for ordering.

  BlackList:
    type: object
    required:
      - patient
    properties:
      id:
        type: string
        description: Unique ID of this black list. Assigned by server
        example: 3
      patient:
        type: string
        #        pattern: ^(?:http(s)?:\/\/)?[\w.-]+(?:\.[\w\.-]+)+[\w\-\._~:/?#[\]@!\$&'\(\)\*\+,;=.]+\/Patient/\d+$
        description: Reference to the corresponding ehealth-patient in the clinical domain. Pattern should be used ^(?:http(s)?:\/\/)?[\w.-]+(?:\.[\w\.-]+)+[\w\-\._~:/?#[\]@!\$&'\(\)\*\+,;=.]+\/Patient/\d+$
        example: https://ehealth.sundhed.dk/patient/fhir/Patient/1566241
      item:
        type: string
        #pattern: ^((http[s]?):\/)?\/?([^:\/\s]+)((\/\w+)*\/)([\w\-\.]+[^#?\s]+)(.*)?(#[\w\-]+)?$
        example: [{'item':'http://ssl-catalogue.ehealth.sundhed.dk/v1/device-model/458', 'reason':{'system':'system','code':'code'}}, {'item':'http://ssl-catalogue.ehealth.sundhed.dk/v1/device-model/459', 'reason':{'system':'system','code':'code'}}]
        description: References to catalog items which were put in black list by patient and reasons why this items are in black list. Pattern should be used ^((http[s]?):\/)?\/?([^:\/\s]+)((\/\w+)*\/)([\w\-\.]+[^#?\s]+)(.*)?(#[\w\-]+)?$

  CatalogueStatus:
    type: string
    enum:
      - DRAFT
      - ACTIVE
      - RETIRED

  CatalogueItemStatus:
    type: string
    enum:
      - AVAILABLE
      - UNAVAILABLE
      - RETIRED

  AnnotationStatus:
    type: string
    enum:
      - DRAFT
      - ACTIVE
      - RETIRED

  Coding:
    type: object
    description: Coding system from clinical domain.
    required:
      - system
      - code
    properties:
      system:
        type: string
        format: uri
        description: A URI string referring the Identity of the terminology system
        example: http://ehealth.sundhed.dk/vs/device-measuring-quality
      code:
        type: string
        pattern: '[^\s]+([\s]?[^\s]+)*'
        description: Code value taken from a set of controlled strings defined in the system
        example: MEDIUM
      display:
        type: string
        readOnly: true
        description: Human-readable value taken from a set of controlled strings defined in the system
        example: Precision < 0.5kg

  Identifier:
    type: object
    description: A numeric or alphanumeric string that is associated with a single object or entity within a given system. Typically, identifiers are used to connect content in resources to external content available in other frameworks or protocols. Identifiers are associated with objects and may be changed or retired due to human or system process and errors.
    properties:
      system:
        type: string
        description: The namespace for the identifier value
        example: urn:ietf:rfc:3986
      value:
        type: string
        description: The value that is unique
        pattern: '^(?!\s*$).+'
        example: NUC8766
      assigner:
        type: string
        description: Organization that issued id (may be just text)
        example: Danish Health Authorities

  Error:
    type: object
    description: An business process error reported by the server.
    required:
      - id
      - time
      - message
    properties:
      id:
        type: string
        format: uuid
        description: Unique ID of this error.
        example: 4cf5bf7f-bf42-48dd-81bf-02b05aaf0858
      time:
        type: string
        format: date-time
        description: Date and time this error occurred.
        example: 2020-01-01T01:00:00Z
      code:
        type: string
        format: string
        description: A protocol defined code allowing the client to understand the error and act appropriately
        example: ORD00125
      message:
        type: string
        format: string
        description: An English text describing the error in end-user terms.
        example: Some server or client error
      technicalDetails:
        type: string
        format: string
        description: An detailed technical description of an internal, non-business error
        example: <A stack trace>
