swagger/v1/e2e-restapi.yaml

swagger: '2.0'
info:
  title: "Azure IOT End-to-End Test Wrapper Rest Api"
  description: "REST API definition for End-to-end testing of the Azure IoT SDKs.  All SDK APIs that are tested by our E2E tests need to be defined in this file.  This file takes some liberties with the API definitions.  In particular, response schemas are undefined, and error responses are also undefined."
  version: "1.0.0"
schemes:
  - https
produces:
  - application/json
tags:
  - name: "wrapper"
    description: "APIs that transcend the individual SDKs"
  - name: "module"
    description: "ModuleClient APIs"
  - name: "device"
    description: "DeviceClient APIs"
  - name: "service"
    description: "ServiceClient APIs"
  - name: "eventhub"
    description: "EventHub APIs"
  - name: "registry"
    description: "registry APIs"
paths:
  /wrapper/cleanup:
    put:
      tags: ["wrapper"]
      summary: "verify that the clients have cleaned themselves up completely"
      operationId: "Wrapper_Cleanup"
      responses:
        200:
          description: OK
  /wrapper/session:
    put:
      tags: ["wrapper"]
      summary: "Launch a wrapper, getting ready to test"
      operationId: "Wrapper_StartSession"
      responses:
        200:
          description: OK
    get:
      tags: ["wrapper"]
      summary: "Terminate a wrapper, optionally returning the log"
      operationId: "Wrapper_EndSession"
      produces:
        - "application/json"
      responses:
        200:
          description: OK
  /wrapper/message:
    put:
      tags: ["wrapper"]
      summary: "log a message to output"
      operationId: "Wrapper_LogMessage"
      consumes:
        - "application/json"
      parameters:
        - name: msg
          in: body
          required: true
          schema:
            type: object
      responses:
        200:
          description: OK
  /registry/connect:
    put:
      tags: ["registry"]
      summary: Connect to registry
      description: "Connect to the Azure IoTHub registry.  More specifically, the SDK saves the connection string that is passed in for future use."
      operationId: "Registry_Connect"
      parameters:
        - name: connectionString
          in: query
          description: Service connection string
          required: true
          type: string
      responses:
        200:
          description: OK
          schema:
            "$ref": "#/definitions/connectResponse"
  /registry/{connectionId}/disconnect/:
    put:
      tags: ["registry"]
      summary: Disconnect from the registry
      description: "Disconnects from the Azure IoTHub registry.  More specifically, closes all connections and cleans up all resources for the active connection"
      operationId: "Registry_Disconnect"
      parameters:
        - name: connectionId
          in: path
          description: Id for the connection
          required: true
          type: string
      responses:
        200:
          description: OK
  /registry/{connectionId}/moduleTwin/{deviceId}/{moduleId}:
    patch:
      tags: ["registry"]
      summary: update the module twin for the given deviceId and moduleId
      operationId: "Registry_PatchModuleTwin"
      consumes:
        - "application/json"
      parameters:
        - name: connectionId
          in: path
          description: Id for the connection
          required: true
          type: string
        - name: deviceId
          in: path
          required: true
          type: string
        - name: moduleId
          in: path
          required: true
          type: string
        - name: props
          in: body
          required: true
          schema:
            type: object
      responses:
        200:
          description: OK
    get:
      tags: ["registry"]
      summary: gets the module twin for the given deviceid and moduleid
      operationId: "Registry_GetModuleTwin"
      produces:
        - "application/json"
      parameters:
        - name: connectionId
          in: path
          description: Id for the connection
          required: true
          type: string
        - name: deviceId
          in: path
          required: true
          type: string
        - name: moduleId
          in: path
          required: true
          type: string
      responses:
        200:
          description: OK
          schema:
            type: object
  /module/connect/{transportType}:
    put:
      tags: ["module"]
      summary: Connect to the azure IoT Hub as a module
      operationId: "Module_Connect"
      consumes:
        - "application/json"
      parameters:
        - name: transportType
          in: path
          description: Transport to use
          required: true
          type: string
          enum: [amqp, amqpws, mqtt, mqttws, http]
        - name: connectionString
          in: query
          description: connection string
          required: true
          type: string
        - name: caCertificate
          in: body
          schema:
            "$ref": "#/definitions/certificate"
      responses:
        200:
          description: OK
          schema:
            "$ref": "#/definitions/connectResponse"
  /module/connectFromEnvironment/{transportType}:
    put:
      tags: ["module"]
      summary: Connect to the azure IoT Hub as a module using the environment variables
      operationId: "Module_ConnectFromEnvironment"
      parameters:
        - name: transportType
          in: path
          description: Transport to use
          required: true
          type: string
          enum: [amqp, amqpws, mqtt, mqttws, http]
      responses:
        200:
          description: OK
          schema:
            "$ref": "#/definitions/connectResponse"
  /module/{connectionId}/disconnect:
    put:
      tags: ["module"]
      summary: Disconnect the module
      description: "Disconnects from Azure IoTHub service.  More specifically, closes all connections and cleans up all resources for the active connection"
      operationId: "Module_Disconnect"
      parameters:
        - name: connectionId
          in: path
          description: Id for the connection
          required: true
          type: string
      responses:
        200:
          description: OK
  /module/{connectionId}/enableTwin:
    put:
      tags: ["module"]
      summary: Enable module twins
      operationId: "Module_EnableTwin"
      parameters:
        - name: connectionId
          in: path
          description: Id for the connection
          required: true
          type: string
      responses:
        200:
          description: OK
  /module/{connectionId}/enableMethods:
    put:
      tags: ["module"]
      summary: Enable methods
      operationId: "Module_EnableMethods"
      parameters:
        - name: connectionId
          in: path
          description: Id for the connection
          required: true
          type: string
      responses:
        200:
          description: OK
  /module/{connectionId}/enableInputMessages:
    put:
      tags: ["module"]
      summary: Enable input messages
      operationId: "Module_EnableInputMessages"
      parameters:
        - name: connectionId
          in: path
          description: Id for the connection
          required: true
          type: string
      responses:
        200:
          description: OK
  /module/{connectionId}/twin:
    get:
      tags: ["module"]
      summary: Get the device twin
      operationId: "Module_GetTwin"
      produces:
        - "application/json"
      parameters:
        - name: connectionId
          in: path
          description: Id for the connection
          required: true
          type: string
      responses:
        200:
          description: OK
          schema:
            type: object
    patch:
      tags: ["module"]
      summary: Updates the device twin
      operationId: "Module_PatchTwin"
      consumes:
        - "application/json"
      parameters:
        - name: connectionId
          in: path
          description: Id for the connection
          required: true
          type: string
        - name: props
          in: body
          required: true
          schema:
            type: object
      responses:
        200:
          description: OK
  /module/{connectionId}/twinDesiredPropPatch:
    get:
      tags: ["module"]
      summary: Wait for the next desired property patch
      operationId: "Module_WaitForDesiredPropertiesPatch"
      produces:
        - "application/json"
      parameters:
        - name: connectionId
          in: path
          description: Id for the connection
          required: true
          type: string
      responses:
        200:
          description: OK
          schema:
            type: object
  /module/{connectionId}/event:
    put:
      tags: ["module"]
      summary: Send an event
      operationId: "Module_SendEvent"
      consumes:
        - "text/json"
      parameters:
        - name: connectionId
          in: path
          description: Id for the connection
          required: true
          type: string
        - name: eventBody
          in: body
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
  /module/{connectionId}/outputEvent/{outputName}:
    put:
      tags: ["module"]
      summary: Send an event to a module output
      operationId: "Module_SendOutputEvent"
      consumes:
        - "text/json"
      parameters:
        - name: connectionId
          in: path
          description: Id for the connection
          required: true
          type: string
        - name: outputName
          in: path
          required: true
          type: string
        - name: eventBody
          in: body
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
  /module/{connectionId}/inputMessage/{inputName}:
    get:
      tags: ["module"]
      summary: Wait for a message on a module input
      operationId: "Module_WaitForInputMessage"
      produces:
        - "text/json"
      parameters:
        - name: connectionId
          in: path
          description: Id for the connection
          required: true
          type: string
        - name: inputName
          in: path
          required: true
          type: string
      responses:
        200:
          description: OK
          schema:
            type: string
  /module/{connectionId}/roundtripMethodCall/{methodName}:
    put:
      tags: ["module"]
      summary: "Wait for a method call, verify the request, and return the response."
      description: "This is a workaround to deal with SDKs that only have method call operations that are sync.  This function responds to the method with the payload of this function, and then returns the method parameters.  Real-world implemenatations would never do this, but this is the only same way to write our test code right now (because the method handlers for C, Java, and probably Python all return the method response instead of supporting an async method call)"
      operationId: "Module_RoundtripMethodCall"
      consumes:
        - "application/json"
      produces:
        - "application/json"
      parameters:
        - name: connectionId
          in: path
          description: Id for the connection
          required: true
          type: string
        - name: methodName
          in: path
          description: name of the method to handle
          required: true
          type: string
        - name: requestAndResponse
          in: body
          required: true
          schema:
            "$ref": "#/definitions/roundtripMethodCallBody"
      responses:
        200:
          description: OK
  /module/{connectionId}/moduleMethod/{deviceId}/{moduleId}:
    put:
      tags: ["module"]
      summary: call the given method on the given module
      operationId: "Module_InvokeModuleMethod"
      consumes:
        - "application/json"
      produces:
        - "application/json"
      parameters:
        - name: connectionId
          in: path
          description: Id for the connection
          required: true
          type: string
        - name: deviceId
          in: path
          required: true
          type: string
        - name: moduleId
          in: path
          required: true
          type: string
        - name: methodInvokeParameters
          in: body
          required: true
          schema:
            type: object
      responses:
        200:
          description: OK
          schema:
            type: object
  /module/{connectionId}/deviceMethod/{deviceId}:
    put:
      tags: ["module"]
      summary: call the given method on the given device
      operationId: "Module_InvokeDeviceMethod"
      consumes:
        - "application/json"
      produces:
        - "application/json"
      parameters:
        - name: connectionId
          in: path
          description: Id for the connection
          required: true
          type: string
        - name: deviceId
          in: path
          required: true
          type: string
        - name: methodInvokeParameters
          in: body
          required: true
          schema:
            type: object
      responses:
        200:
          description: OK
          schema:
            type: object
  /service/connect:
    put:
      tags: ["service"]
      summary: Connect to service
      description: "Connect to the Azure IoTHub service.  More specifically, the SDK saves the connection string that is passed in for future use."
      operationId: "Service_Connect"
      parameters:
        - name: connectionString
          in: query
          description: Service connection string
          required: true
          type: string
      responses:
        200:
          description: OK
          schema:
            "$ref": "#/definitions/connectResponse"
  /service/{connectionId}/disconnect/:
    put:
      tags: ["service"]
      summary: Disconnect from the service
      description: "Disconnects from the Azure IoTHub service.  More specifically, closes all connections and cleans up all resources for the active connection"
      operationId: "Service_Disconnect"
      parameters:
        - name: connectionId
          in: path
          description: Id for the connection
          required: true
          type: string
      responses:
        200:
          description: OK
  /service/{connectionId}/moduleMethod/{deviceId}/{moduleId}:
    put:
      tags: ["service"]
      summary: call the given method on the given module
      operationId: "Service_InvokeModuleMethod"
      consumes:
        - "application/json"
      produces:
        - "application/json"
      parameters:
        - name: connectionId
          in: path
          description: Id for the connection
          required: true
          type: string
        - name: deviceId
          in: path
          required: true
          type: string
        - name: moduleId
          in: path
          required: true
          type: string
        - name: methodInvokeParameters
          in: body
          required: true
          schema:
            type: object
      responses:
        200:
          description: OK
          schema:
            type: object
  /service/{connectionId}/deviceMethod/{deviceId}:
    put:
      tags: ["service"]
      summary: call the given method on the given device
      operationId: "Service_InvokeDeviceMethod"
      consumes:
        - "application/json"
      produces:
        - "application/json"
      parameters:
        - name: connectionId
          in: path
          description: Id for the connection
          required: true
          type: string
        - name: deviceId
          in: path
          required: true
          type: string
        - name: methodInvokeParameters
          in: body
          required: true
          schema:
            type: object
      responses:
        200:
          description: OK
          schema:
            type: object
  /eventhub/connect:
    put:
      tags: ["eventhub"]
      summary: Connect to eventhub
      description: "Connect to the Azure eventhub service."
      operationId: "EventHub_Connect"
      parameters:
        - name: connectionString
          in: query
          description: Service connection string
          required: true
          type: string
      responses:
        200:
          description: OK
          schema:
            "$ref": "#/definitions/connectResponse"
  /eventhub/{connectionId}/disconnect/:
    put:
      tags: ["eventhub"]
      summary: Disconnect from the eventhub
      description: "Disconnects from the Azure eventhub service"
      operationId: "EventHub_Disconnect"
      parameters:
        - name: connectionId
          in: path
          description: Id for the connection
          required: true
          type: string
      responses:
        200:
          description: OK
  /eventhub/{connectionId}/enableTelemetry:
    put:
      tags: ["eventhub"]
      summary: Enable telemetry
      operationId: "EventHub_EnableTelemetry"
      parameters:
        - name: connectionId
          in: path
          description: Id for the connection
          required: true
          type: string
      responses:
        200:
          description: OK
  /eventhub/{connectionId}/deviceTelemetry/{deviceId}:
    get:
      tags: ["eventhub"]
      summary: wait for telemetry sent from a specific device
      operationId: "EventHub_WaitForTelemetry"
      produces:
        - "text/json"
      parameters:
        - name: connectionId
          in: path
          description: Id for the connection
          required: true
          type: string
        - name: deviceId
          in: path
          required: true
          type: string
      responses:
        200:
          description: OK
          schema:
            type: string
  /device/connect/{transportType}:
    put:
      tags: ["device"]
      summary: Connect to the azure IoT Hub as a device
      operationId: "Device_Connect"
      consumes:
        - "application/json"
      parameters:
        - name: transportType
          in: path
          description: Transport to use
          required: true
          type: string
          enum: [amqp, amqpws, mqtt, mqttws, http]
        - name: connectionString
          in: query
          description: connection string
          required: true
          type: string
        - name: caCertificate
          in: body
          schema:
            "$ref": "#/definitions/certificate"
      responses:
        200:
          description: OK
          schema:
            "$ref": "#/definitions/connectResponse"
  /device/{connectionId}/disconnect:
    put:
      tags: ["device"]
      summary: Disconnect the device
      description: "Disconnects from Azure IoTHub service.  More specifically, closes all connections and cleans up all resources for the active connection"
      operationId: "Device_Disconnect"
      parameters:
        - name: connectionId
          in: path
          description: Id for the connection
          required: true
          type: string
      responses:
        200:
          description: OK
  /device/{connectionId}/enableMethods:
    put:
      tags: ["device"]
      summary: Enable methods
      operationId: "Device_EnableMethods"
      parameters:
        - name: connectionId
          in: path
          description: Id for the connection
          required: true
          type: string
      responses:
        200:
          description: OK
  /device/{connectionId}/roundtripMethodCall/{methodName}:
    put:
      tags: ["device"]
      summary: "Wait for a method call, verify the request, and return the response."
      description: "This is a workaround to deal with SDKs that only have method call operations that are sync.  This function responds to the method with the payload of this function, and then returns the method parameters.  Real-world implemenatations would never do this, but this is the only same way to write our test code right now (because the method handlers for C, Java, and probably Python all return the method response instead of supporting an async method call)"
      operationId: "Device_RoundtripMethodCall"
      consumes:
        - "application/json"
      produces:
        - "application/json"
      parameters:
        - name: connectionId
          in: path
          description: Id for the connection
          required: true
          type: string
        - name: methodName
          in: path
          description: name of the method to handle
          required: true
          type: string
        - name: requestAndResponse
          in: body
          required: true
          schema:
            "$ref": "#/definitions/roundtripMethodCallBody"
      responses:
        200:
          description: OK
definitions:
  connectResponse:
    description: "result of a connection to a service, device, or module client"
    type: object
    properties:
      connectionId:
        description: "unique identifier for this connection"
        type: string
  roundtripMethodCallBody:
    description: "parameters and response for a sync method call"
    type: object
    properties:
      requestPayload:
        description: "payload for the request that arrived from the service.  Used to verify that the correct request arrived."
        type: object
      responsePayload:
        description: "payload for the response to return to the service.  Used to verify that the correct request arrived."
        type: object
      statusCode:
        description: "status code to return to the service"
        type: integer
  certificate:
    description: "certificate in the body of a message"
    type: object
    properties:
      cert:
        description: "unique identifier for this connection"
        type: string