swagger: '2.0'
info:
  description: |
    This API provides operations that let;

    - Tenants to manage CA certificate resources.


    ## Generic Errors

    The following generic error codes (with status codes) can occur at the operations of this API. Generic error codes are prefixed with 'mdsp.core.generic.'.

    - missingParameter (400)
    - invalidParameter (400)
    - missingRequestBody (400)
    - invalidRequestBody (400)
    - unauthorized (401)
    - forbidden (403)
    - conflict (409)
    - preconditionFailed (412)
    - unsupportedMediaType (415)
    - preconditionRequired (428)
    - tooManyRequests (429)
    - internalServerError (500)

    See the Insights Hub Developer Documentation generic errors page for more information on these errors.

  version: '3.0.0'
  x-visibility: internal
  title:  MindConnect MQTT API

basePath: /api/mindconnectmqtt/v3
schemes:
  - https
consumes:
  - application/json
produces:
  - application/json
tags:
  - name: CA Certificates
    description: CA Certificate Controller
securityDefinitions:
  certificates:
    type: oauth2
    tokenUrl: 'http://authorization.connectivity.net/oauth/token'
    flow: application
    scopes:
      mcmq.c.c: Permission to upload ca certificate
      mcmq.c.r: Permission to read ca certificate
      mcmq.c.d: Permission to delete ca certificate

paths:
  /caCertificates:
    post:
      tags:
        - CA Certificates
      summary: Upload CA certificate
      description: |
        Uploads a new CA certificate. Maximum 2 CA certificates per tenant can be uploaded.
      security:
        - certificates:
            - mcmq.c.c
      parameters:
        - in: body
          name: certificate
          description: |
            Object describing new CA certificate resource.
          required: true
          schema:
            $ref: '#/definitions/CertificateInput'
      responses:
        '201':
          description: Created
          schema:
            $ref: '#/definitions/CertificateResponse'
        '400':
          $ref: '#/responses/InvalidParameter'
        'default':
          $ref: '#/responses/Default'
    get:
      tags:
        - CA Certificates
      summary: Get CA certificates
      description: |
        Gets the CA certificates.
      security:
        - certificates:
            - mcmq.c.r
      parameters:
        - name: size
          in: query
          description: Maximum number of CA certificates to be retrieved.
          required: false
          type: integer
          default: 100
          maximum: 100
        - name: pageToken
          in: query
          description: Selects next page. Value must be taken from response body property 'page.nextToken'. If omitted, first page is returned.
          required: false
          type: string
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/CertificatesResponse'
        'default':
          $ref: '#/responses/Default'
  /caCertificates/{id}:
    get:
      tags:
        - CA Certificates
      summary: Get CA Certificate
      description: |
        Gets the CA Certificate with id.
      security:
        - certificates:
            - mcmq.c.r
      parameters:
        - name: id
          in: path
          description: Unique identifier of the ca certificate.
          required: true
          type: string
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/CertificateResponse'
        '404':
          $ref: '#/responses/CertificateNotFound'
        'default':
          $ref: '#/responses/Default'
    delete:
      tags:
        - CA Certificates
      summary: Delete CA certificate.
      description: |
        Deletes the CA certificate by id.
      security:
        - certificates:
            - mcmq.c.d
      parameters:
        - name: id
          in: path
          description: Unique identifier of the ca certificate.
          required: true
          type: string
      responses:
        '204':
          description: No Content
        '404':
          $ref: '#/responses/CertificateNotFound'
        'default':
          $ref: '#/responses/Default'
  /caCertificates/{id}/verify:
    post:
      tags:
        - CA Certificates
      summary: Verify CA certificate
      description: |
        Verify existing CA certificate.
      security:
        - certificates:
            - mcmq.c.c
      parameters:
        - name: id
          in: path
          description: Unique identifier of the ca certificate.
          required: true
          type: string
        - in: body
          name: certificate
          description: |
            Object describing new CA certificate resource.
          required: true
          schema:
            $ref: '#/definitions/VerificationCertificateInput'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/VerifiedCertificateResponse'
        '400':
          $ref: '#/responses/InvalidVerificationCert'
        '404':
          $ref: '#/responses/CertificateNotFound'
        '409':
          $ref: '#/responses/AlreadyVerified'
        'default':
          $ref: '#/responses/Default'
  /caCertificates/{id}/registrationCode:
    get:
      tags:
        - CA Certificates
      summary: Get registration code
      description: |
        Gets a CA certificate's registration code.
      security:
        - certificates:
            - mcmq.c.c
      parameters:
        - name: id
          in: path
          description: Unique identifier of the ca certificate.
          required: true
          type: string
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/RegistrationCode'
        '404':
          $ref: '#/responses/CertificateNotFound'
        '409':
          $ref: '#/responses/AlreadyVerified'
        'default':
          $ref: '#/responses/Default'
definitions:
  CertificatesResponse:
    required:
      - caCertificates
    type: object
    properties:
      caCertificates:
        type: array
        items:
          $ref: '#/definitions/CertificateResponse'
      page:
        allOf:
          - $ref: '#/definitions/Page'
  Page:
    type: object
    required:
      - nextToken
    properties:
      nextToken:
        type: string
        example: '4fad62585def4d84a4c21481b209c116'
        description: 'Opaque token to request next page'
        maxLength: 256
  RegistrationCode:
    required:
      - registrationCode
    type: object
    properties:
      registrationCode:
        type: string
        example: '61d5533b564ecd2f6066asd357f68a64f544e1a8c40d5abf72f9c9ce3fec194'
        description: 'Registration code that is to be used for generating a verification Certificate'
  CertificateResponse:
    required:
      - id
      - name
      - expiration
      - commonName
      - isVerified
    type: object
    properties:
      id:
        type: string
        example: '60c89c9cf1b56605bc315f78'
        description: 'Unique identifier of the certificate'
      name:
        type: string
        example: 'MyTenantName CA Certificate'
        description: "User defined name"
      expiration:
        type: string
        format: date-time
        example: '2021-07-21T17:32:28Z'
        description: "The time after which the certificate is not valid"
      commonName:
        type: string
        example: 'Siemens'
        description: "Common name of certificate"
      isVerified:
        type: boolean
        example: false
        description: "Verification status of CA certificate."
      idScope:
        type: string
        example: 0ne001E4ZA9
        description: '"ID Scope" parameter for using to connect to Azure DPS. See Azure DPS documentation for details.'
  VerifiedCertificateResponse:
    required:
      - id
      - name
      - expiration
      - commonName
      - isVerified
    type: object
    properties:
      id:
        type: string
        example: '60c89c9cf1b56605bc315f78'
        description: 'Unique identifier of the certificate'
      name:
        type: string
        example: 'MyTenantName CA Certificate'
        description: "User defined name"
      expiration:
        type: string
        format: date-time
        example: '2021-07-21T17:32:28Z'
        description: "The time after which the certificate is not valid"
      commonName:
        type: string
        example: 'MyTenantName MDSP CA'
        description: "Common name of the certificate."
      isVerified:
        type: boolean
        example: true
        description: "Verification status of CA certificate."
      idScope:
        type: string
        example: 0ne001E4ZA9
        description: '"ID Scope" parameter for connecting to Azure DPS. See Azure DPS documentation for details.'
  CertificateInput:
    required:
      - name
      - caCertificate
    type: object
    properties:
      name:
        type: string
        example: "MyTenantName MDSP CA Certificate"
        description: 'User defined name'
        minLength: 1
        maxLength: 128
      caCertificate:
        type: string
        description: 'Tenant CA certificate in PEM encoding.'
        example: -----BEGIN CERTIFICATE-----MIIC/jCCAeagAwIBAgIJALv7Lg7C0b1LMA0GCSqGSIb3DQEBCwUAMBQxEjAQBgNVBAMMCVRFQU02LW9yZzAeFw0yMDA0MTAxMzUzNTFaFw0yMzAxMjkxMzUzNTFaMBQxEjAQBgNVBAMMCVRFQU02LW9yZzCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAM4myW+NTlrlzdF1cxYF+3P4i+DOkE2m/u5aDRIoI+7tVCZSNRa3Y2+GzHtNBSkkoCNlCBx6MX6CMKqt3apdSqBKB9ImNjj3ayACzBpywCzLScYdqnvQN3e+LnsKb4qnKMvc11s+9obVBrt76WcCW6iqGMJErw8LcvQvKkccLq5vQ14AgkguGXsbLE+rDllV/w3w3fCjz8K4qzoyJk+BseeMMPAOvbsfOvLLJzjDd9KHKgvyMmyMuR6M9WREIprkI2wgeSxO0LtYInagR2ZCIYIUaZCbV9Q9MEJKwa9NKYgiOgKFsCkaPvo2TvPKQp2IVKXIm/dOjfhlBQ7vNkxvlIrnmdwTu/o4jpq0CTso6PBI+oGJm1SbDKuvHlv/uPxaHUhB8AaEXr4AyNc1Zh7jWbQb0hbIOhDoaG8UIgoaM=-----END CERTIFICATE-----
        minLength: 1
        maxLength: 65536
  VerificationCertificateInput:
    required:
      - verificationCertificate
    type: object
    properties:
      verificationCertificate:
        type: string
        description: 'Verification certificate in PEM encoding.'
        example: -----BEGIN CERTIFICATE-----          MIIBsjCCAVmgAwIBAgIFDg0MCwowCgYIKoZIzj0EAwIwQDEeMBwGA1UEAwwVbWlj
          cm9zb2Z0cmlvdGNvcmVyb290MREwDwYDVQQKDAhNU1JfVEVTVDELMAkGA1UEBhMC
          VVMwIBcNMTcwMTAxMDAwMDAwWhgPMzcwMTAxMzEyMzU5NTlaMFsxOTA3BgNVBAMM
          MEQzNzFGMDgyNjI5NUM3NEJFREExQjMxQ0I2RjgwQTM2QUU0NzdCMUU0MzEzNjIy
          NTERMA8GA1UECgwITVNSX1RFU1QxCzAJBgNVBAYTAlVTMFkwEwYHKoZIzj0CAQYI
          KoZIzj0DAQcDQgAEF0/WZW27JwWpVuwyDsigp06Xbjl2Yu8z4Zs6v6rnoUYO6qvl
          8/vnmVN9VNawDaXBrOJYhoOu3Kwd3pRNITiOAKMjMCEwCwYDVR0PBAQDAgIEMBIG
          A1UdEwEB/wQIMAYBAf8CAQEwCgYIKoZIzj0EAwIDRwAwRAIgZDzQSqU85iTa/50F
          +u/lwtfaX9brMLGfC/El5Iq2fLECIDfryUr5NS/4qZ84i8ZximhZEc4QytUPN9//
          qL9z/CUb
          -----END CERTIFICATE-----
        minLength: 1
        maxLength: 65536
  Errors:
    type: object
    description: Error response body model.
    properties:
      errors:
        type: array
        description: "Concrete error codes and messages are defined at operation error response descriptions in this API specification."
        items:
          type: object
          properties:
            code:
              type: string
              description: "Unique error code. Every code is bound to one (parametrized) message."
              format: "mdsp.core.template.<suffix>"
              example: "mdsp.core.mindconnectmqtt.exampleCode"
            logref:
              type: string
              description: "Logging correlation ID for debugging purposes."
              example: "0bff7e7a-cd25-4576-9908-4180ef086174"
            message:
              type: string
              description: "Human readable error message in English."
              example: "Example error message with parameter value 100"
parameters:
  Page:
    name: page
    in: query
    description: Index of page to be returned. Number of available pages is returned in response body proprety page.totalPages.
    type: number
    default: 0
    minimum: 0
responses:
  InvalidParameter:
    description: |
      Bad request. Possible errors:
      <br>
      <table>
        <colgroup>
          <col span="1" style="width: 30%;">
          <col span="1" style="width: 70%;">
        </colgroup>
        <tr>
          <th align="left">Code Suffix</th>
          <th align="left">Message (parametrized)</th>
        </tr>
        <tr>
          <td>invalidCaCertificate</td>
          <td>CA Certificate is invalid.</td>
        </tr>
        <tr>
          <td>quotaExceeded</td>
          <td>Certificate upload quota exceeded, limit is <10>.</td>
        </tr>
      </table>
    schema:
      $ref: '#/definitions/Errors'
  InvalidVerificationCert:
    description: |
      Bad request. Possible errors:
      <br>
      <table>
        <colgroup>
          <col span="1" style="width: 30%;">
          <col span="1" style="width: 70%;">
        </colgroup>
        <tr>
          <th align="left">Code Suffix</th>
          <th align="left">Message (parametrized)</th>
        </tr>
        <tr>
          <td>invalidVerificationCertificate</td>
          <td>Verification certificate is invalid.</td>
        </tr>
      </table>
    schema:
      $ref: '#/definitions/Errors'
  AlreadyVerified:
    description: |
      Bad request. Possible errors:
      <br>
      <table>
        <colgroup>
          <col span="1" style="width: 30%;">
          <col span="1" style="width: 70%;">
        </colgroup>
        <tr>
          <th align="left">Code Suffix</th>
          <th align="left">Message (parametrized)</th>
        </tr>
        <tr>
          <td>alreadyVerified</td>
          <td>Certificate with id: {id} is already verified.</td>
        </tr>
      </table>
    schema:
      $ref: '#/definitions/Errors'
  CertificateNotFound:
    description: |
      Not found. Possible errors:
      <br>
      <table>
        <colgroup>
          <col span="1" style="width: 30%;">
          <col span="1" style="width: 70%;">
          <col span="1" style="width: 70%;">
        </colgroup>
        <tr>
          <th align="left">Code Suffix</th>
          <th align="left">Message (parametrized)</th>
        </tr>
        <tr>
          <td>certificateNotFound</td>
          <td>Certificate with id: {id} is not found!</td>
        </tr>
      </table>
    schema:
      $ref: '#/definitions/Errors'
  Default:
    description: "Other error with any status code and response body format."
