edgelet/api/workloadVersion_2018_06_28.yaml

swagger: '2.0'
schemes:
  - http
info:
  title: IoT Edge Module Workload API
  version: '2018-06-28'
tags:
  - name: Workload
    x-displayName: Workload
    description: |

paths:
  /modules:
    get:
      tags:
        - Module
      summary: List modules.
      produces:
        - application/json
      description: |
        This returns the list of currently running modules and their statuses.
      operationId: ListModules
      parameters:
        - $ref: '#/parameters/api-version'
      responses:
        '200':
          description: Ok
          schema:
            $ref: '#/definitions/ModuleList'
        default:
          description: Error
          schema:
            $ref: '#/definitions/ErrorResponse'
  '/modules/{name}/genid/{genid}/sign':
    post:
      tags:
        - Workload
      summary: ''
      operationId: Sign
      parameters:
        - $ref: '#/parameters/api-version'
        - in: path
          name: name
          description: The name of the module on whose behalf the payload will be signed. (urlencoded)
          required: true
          type: string
        - in: path
          name: genid
          description: The generation identifier for the module as generated by IoT Hub.
          required: true
          type: string
        - in: body
          name: payload
          description: The data to be signed.
          required: true
          schema:
            $ref: '#/definitions/SignRequest'
      responses:
        '200':
          description: Ok
          schema:
            $ref: '#/definitions/SignResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        default:
          description: Error
          schema:
            $ref: '#/definitions/ErrorResponse'
  '/modules/{name}/genid/{genid}/encrypt':
    post:
      tags:
        - Workload
      summary: ''
      operationId: Encrypt
      parameters:
        - $ref: '#/parameters/api-version'
        - in: path
          name: name
          description: The name of the module on whose behalf the plaintext will be encrypted. (urlencoded)
          required: true
          type: string
        - in: path
          name: genid
          description: The generation identifier for the module as generated by IoT Hub.
          required: true
          type: string
        - in: body
          name: payload
          description: The data to be encrypted.
          required: true
          schema:
            $ref: '#/definitions/EncryptRequest'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/EncryptResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        default:
          description: Error
          schema:
            $ref: '#/definitions/ErrorResponse'
  '/modules/{name}/genid/{genid}/decrypt':
    post:
      tags:
        - Workload
      summary: ''
      operationId: Decrypt
      parameters:
        - $ref: '#/parameters/api-version'
        - in: path
          name: name
          description: The name of the module on whose behalf the ciphertext will be decrypted. (urlencoded)
          required: true
          type: string
        - in: path
          name: genid
          description: The generation identifier for the module as generated by IoT Hub.
          required: true
          type: string
        - in: body
          name: payload
          description: The data to be decrypted.
          required: true
          schema:
            $ref: '#/definitions/DecryptRequest'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/DecryptResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        default:
          description: Error
          schema:
            $ref: '#/definitions/ErrorResponse'
  '/modules/{name}/certificate/identity':
    post:
      tags:
        - Workload
      summary: ''
      operationId: CreateIdentityCertificate
      parameters:
        - $ref: '#/parameters/api-version'
        - in: path
          name: name
          description: The name of the module needed to obtain the certificate. (urlencoded)
          required: true
          type: string
        - in: body
          name: request
          description: Parameters for certificate creation.
          required: true
          schema:
            $ref: '#/definitions/IdentityCertificateRequest'
      responses:
        '201':
          description: Ok
          schema:
            $ref: '#/definitions/CertificateResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        default:
          description: Error
          schema:
            $ref: '#/definitions/ErrorResponse'
  '/modules/{name}/genid/{genid}/certificate/server':
    post:
      tags:
        - Workload
      summary: ''
      operationId: CreateServerCertificate
      parameters:
        - $ref: '#/parameters/api-version'
        - in: path
          name: name
          description: The name of the module to get certificate. (urlencoded)
          required: true
          type: string
        - in: path
          name: genid
          description: The generation identifier for the module as generated by IoT Hub.
          required: true
          type: string
        - in: body
          name: request
          description: Parameters for certificate creation.
          required: true
          schema:
            $ref: '#/definitions/ServerCertificateRequest'
      responses:
        '201':
          description: Ok
          schema:
            $ref: '#/definitions/CertificateResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        default:
          description: Error
          schema:
            $ref: '#/definitions/ErrorResponse'
  '/trust-bundle':
    get:
      tags:
        - Workload
      summary: ''
      operationId: TrustBundle
      parameters:
        - $ref: '#/parameters/api-version'
      responses:
        '200':
          description: Ok
          schema:
            $ref: '#/definitions/TrustBundleResponse'
        default:
          description: Error
          schema:
            $ref: '#/definitions/ErrorResponse'

definitions:
  ModuleList:
    type: object
    properties:
      modules:
        type: array
        items:
          $ref: '#/definitions/ModuleDetails'
    required:
      - modules
  ModuleDetails:
    type: object
    properties:
      id:
        type: string
        description: System generated unique identitier.
        example: happy_hawking
      name:
        type: string
        description: The name of the module.
        example: edgeHub
      type:
        type: string
        description: The type of a module.
        example: docker
      config:
        $ref: '#/definitions/Config'
      status:
        $ref: '#/definitions/Status'
    required:
      - id
      - name
      - type
      - config
      - status
  Config:
    type: object
    properties:
      settings:
        type: object
        example:
          image: 'microsoft/azureiotedge-hub:1.0'
          createOptions:
            HostConfig:
              PortBindings:
                '22/tcp':
                  - HostPort: '11022'
      env:
        type: array
        items:
          $ref: '#/definitions/EnvVar'
    required:
      - settings
  Status:
    type: object
    properties:
      startTime:
        type: string
        format: date-time
      exitStatus:
        $ref: '#/definitions/ExitStatus'
      runtimeStatus:
        $ref: '#/definitions/RuntimeStatus'
    required:
      - runtimeStatus
  EnvVar:
    type: object
    properties:
      key:
        type: string
        example: the_key
      value:
        type: string
        example: the_value
    required:
      - key
      - value
  ExitStatus:
    type: object
    properties:
      exitTime:
        type: string
        format: date-time
      statusCode:
        type: string
    required:
      - exitTime
      - statusCode
    example:
      exitTime: '2018-04-03T09:31:00.000Z'
      statusCode: '101'
  RuntimeStatus:
    type: object
    properties:
      status:
        type: string
      description:
        type: string
    required:
      - status
    example:
      status: the status
      description: the description
  SignRequest:
    type: object
    properties:
      keyId:
        type: string
        description: Name of key to perform sign operation.
        example: device_key
      algo:
        type: string
        description: Sign algorithm to be used.
        enum:
          - HMACSHA256
      data:
        type: string
        format: byte
        description: Data to be signed.
    required:
      - keyId
      - algo
      - data
  SignResponse:
    type: object
    properties:
      digest:
        type: string
        format: byte
        description: Signature of the data.
    required:
      - digest
  EncryptRequest:
    type: object
    properties:
      plaintext:
        type: string
        format: byte
        description: The data to be encrypted.
      initializationVector:
        type: string
        format: byte
        description: An initialization vector used to encrypt the data.
    required:
      - plaintext
      - initializationVector
  EncryptResponse:
    type: object
    properties:
      ciphertext:
        type: string
        format: byte
        description: The encrypted form of the data encoded in base 64.
    required:
      - ciphertext
  DecryptRequest:
    type: object
    properties:
      ciphertext:
        type: string
        format: byte
        description: The data to be decrypted.
      initializationVector:
        type: string
        format: byte
        description: An initialization vector used to decrypt the data.
    required:
      - ciphertext
      - initializationVector
  DecryptResponse:
    type: object
    properties:
      plaintext:
        type: string
        format: byte
        description: The decrypted form of the data encoded in base 64.
    required:
      - plaintext
  ServerCertificateRequest:
    type: object
    properties:
      commonName:
        type: string
        description: Subject common name
      expiration:
        type: string
        format: date-time
        description: Certificate expiration date-time (ISO 8601)
    required:
      - commonName
      - expiration
  IdentityCertificateRequest:
    type: object
    properties:
      expiration:
        type: string
        format: date-time
        description: Certificate expiration date-time (ISO 8601)
  CertificateResponse:
    type: object
    properties:
      privateKey:
        $ref: '#/definitions/PrivateKey'
      certificate:
        type: string
        format: bytes
        description: Base64 encoded PEM formatted byte array containing the certificate and its chain.
      expiration:
        type: string
        format: date-time
        description: Certificate expiration date-time (ISO 8601)
    required:
      - privateKey
      - certificate
      - expiration
  TrustBundleResponse:
    type: object
    properties:
      certificate:
        type: string
        format: bytes
        description: Base64 encoded PEM formatted byte array containing the trusted certificates.
    required:
      - certificate

  PrivateKey:
    type: object
    properties:
      type:
        type: string
        description: Indicates format of the key (present in PEM formatted bytes or a reference)
        enum:
          - ref
          - key
      ref:
        type: string
        description: Reference to private key.
      bytes:
        type: string
        format: bytes
        description: Base64 encoded PEM formatted byte array
    required:
      - type

  ErrorResponse:
    type: object
    properties:
      message:
        type: string
    required:
      - message

parameters:
  api-version:
    name: api-version
    in: query
    description: The version of the API.
    required: true
    type: string
    default: '2018-06-28'