{
  "openapi": "3.0.3",
  "info": {
    "title": "Over-the-air orchestrator REST",
    "version": "v1",
    "description": ""
  },
  "servers": [
    {
      "url": "https://cloud.kaaiot.com/otao/api/v1",
      "description": "API Server"
    }
  ],
  "paths": {
    "/applications/{appName}/software": {
      "get": {
        "description": "Returns software by application name.\n",
        "responses": {
          "200": {
            "description": "List of objects with software details.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SoftwareResponseArray"
                }
              }
            }
          }
        },
        "security": [
          {
            "oauth_2_0": [
              "application:software:read"
            ]
          }
        ]
      }
    },
    "/applications/{appName}/software/{softwareVersion}": {
      "parameters": [
        {
          "name": "appName",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          },
          "description": "Application name that software is attributed to.",
          "example": "smart-kettle"
        },
        {
          "name": "softwareVersion",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          },
          "description": "Software <a href=\"https://semver.org/\">semantic version</a>. Unique in an application scope. Is used for software priority regulation.",
          "example": "1.0.2"
        }
      ],
      "get": {
        "description": "Returns software by application name and software version.",
        "responses": {
          "200": {
            "description": "Software response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SoftwareRequest"
                }
              }
            }
          }
        },
        "security": [
          {
            "oauth_2_0": [
              "application:software:read"
            ]
          }
        ]
      },
      "put": {
        "description": "Updates software.",
        "responses": {
          "204": {
            "description": "Software updated successfully."
          }
        },
        "security": [
          {
            "oauth_2_0": [
              "application:software:update"
            ]
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SoftwareUpdateRequest"
              }
            }
          }
        }
      },
      "post": {
        "description": "Creates software.",
        "responses": {
          "201": {
            "description": "Software created successfully.",
            "headers": {
              "Location": {
                "description": "Location of newly created software.",
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        },
        "security": [
          {
            "oauth_2_0": [
              "application:software:update"
            ]
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        }
      },
      "delete": {
        "description": "Deletes software if it is not used by any endpoint.",
        "responses": {
          "204": {
            "description": "Software deleted successfully."
          }
        },
        "security": [
          {
            "oauth_2_0": [
              "application:software:delete"
            ]
          }
        ]
      }
    },
    "/applications/{appName}/software/{softwareVersion}/files": {
      "parameters": [
        {
          "name": "appName",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          },
          "description": "Application name that software is attributed to.",
          "example": "smart-kettle"
        },
        {
          "name": "softwareVersion",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          },
          "description": "Software <a href=\"https://semver.org/\">semantic version</a>. Unique in an application scope. Is used for software priority regulation.",
          "example": "1.0.2"
        }
      ],
      "put": {
        "description": "Uploads software file.\nLink to the uploaded file will be attached to the software specification when sending to the endpoint that is eligible for upgrading to that software version.\nFile name must be non-empty, contain only `a-z0-9-._` symbols, and have length from 1 to 30 symbols.\n",
        "responses": {
          "204": {
            "description": "Software file is successfully uploaded."
          }
        },
        "security": [
          {
            "oauth_2_0": [
              "application:software:update"
            ]
          }
        ],
        "requestBody": {
          "content": {}
        }
      }
    },
    "/applications/{appName}/software/{softwareVersion}/files/{fileName}": {
      "parameters": [
        {
          "name": "appName",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          },
          "description": "Application name that software is attributed to.",
          "example": "smart-kettle"
        },
        {
          "name": "softwareVersion",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          },
          "description": "Software <a href=\"https://semver.org/\">semantic version</a>. Unique in an application scope. Is used for software priority regulation.",
          "example": "1.0.2"
        },
        {
          "name": "fileName",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          },
          "description": "Software file name.",
          "example": "app.bin"
        }
      ],
      "delete": {
        "description": "Deletes software file.",
        "responses": {
          "204": {
            "description": "Software file deleted successfully."
          }
        },
        "security": [
          {
            "oauth_2_0": [
              "application:software:delete"
            ]
          }
        ]
      }
    },
    "/applications/{appName}/software/{softwareVersion}/files/{fileName}/links": {
      "parameters": [
        {
          "name": "appName",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          },
          "description": "Application name that software is attributed to.",
          "example": "smart-kettle"
        },
        {
          "name": "softwareVersion",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          },
          "description": "Software <a href=\"https://semver.org/\">semantic version</a>. Unique in an application scope. Is used for software priority regulation.",
          "example": "1.0.2"
        },
        {
          "name": "fileName",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          },
          "description": "Software file name.",
          "example": "app.bin"
        }
      ],
      "get": {
        "description": "Generates and returns software file donwload link with expiration time specified in the service configuration.",
        "responses": {
          "200": {
            "description": "Software file download link is sucessfully generated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SoftwareFileDownloadLinkResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "oauth_2_0": [
              "application:software:read"
            ]
          }
        ]
      }
    },
    "/endpoints/{endpointId}/software/current": {
      "parameters": [
        {
          "name": "endpointId",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          },
          "description": "Unique endpoint identifier",
          "example": "7d5dda9b-c9f6-427d-91ea-9891a4f62cbb"
        }
      ],
      "get": {
        "description": "Returns current software of a specified endpoint.\n",
        "responses": {
          "200": {
            "description": "Software response.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "security": [
          {
            "oauth_2_0": [
              "endpoint:read"
            ]
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "oauth_2_0": {
        "type": "oauth2",
        "description": "OTAO supports OAuth 2.0 for authenticating all API requests.\n",
        "flows": {
          "implicit": {
            "authorizationUrl": "https://auth.example.com/oauth/authorize",
            "scopes": {}
          }
        }
      }
    },
    "schemas": {
      "SoftwareResponseArray": {
        "description": "Array of software objects."
      },
      "SoftwareRequest": {
        "type": "object",
        "properties": {
          "specification": {
            "description": "Software specification that is sent to endpoint. Could be of any valid JSON type.\n"
          },
          "metadata": {
            "description": "Software metadata. Could be of any valid JSON type.\n"
          },
          "upgradableFrom": {
            "type": "array",
            "description": "The list of software versions that can be upgraded to this one.\n"
          },
          "rolloutStrategy": {
            "type": "string",
            "description": "Specifies the software rollout strategy.\n  <ul>\n    <li>`suspended` - the rollout is disabled, no endpoints receive the software.</li>\n    <li>`targeted` - the rollout is performed based on the software compatibility graph and endpoint filters.</li>\n    <li>`general` - the rollout is performed based on the software compatibility graph alone, no recipient endpoint filtering occurs.</li>\n  </ul>\n",
            "enum": [
              "suspended",
              "targeted",
              "general"
            ]
          },
          "filters": {
            "type": "array",
            "description": "The list of endpoint filters used by the `targeted` rollout strategy.\nOnly the endpoints that match at least one of the specified filters and filter's rollout date was overdue\nare eligible for receiving the software update.\n"
          },
          "skipDispatchingToEndpoint": {
            "type": "boolean",
            "description": "Specifies that software has a file.\nIf `true`, software definition will be published to endpoint only when a corresponding to this software version file is uploaded.\n"
          }
        },
        "required": [
          "rolloutStrategy"
        ]
      },
      "SoftwareUpdateRequest": {
        "type": "object",
        "properties": {
          "metadata": {
            "description": "Software metadata. Could be of any valid JSON type.\n"
          },
          "upgradableFrom": {
            "type": "array",
            "description": "The list of software versions that can be upgraded to this one.\n"
          },
          "rolloutStrategy": {
            "type": "string",
            "description": "Specifies the software rollout strategy.\n  <ul>\n    <li>`suspended` - the rollout is disabled, no endpoints receive the software.</li>\n    <li>`targeted` - the rollout is performed based on the software compatibility graph and endpoint filters.</li>\n    <li>`general` - the rollout is performed based on the software compatibility graph alone, no recipient endpoint filtering occurs.</li>\n  </ul>\n",
            "enum": [
              "suspended",
              "targeted",
              "general"
            ]
          },
          "filters": {
            "type": "array",
            "description": "The list of endpoint filters used by the `targeted` rollout strategy.\nOnly the endpoints that match at least one of the specified filters and filter's rollout date was overdue\nare eligible for receiving the software update.\n"
          },
          "skipDispatchingToEndpoint": {
            "type": "boolean",
            "description": "Specifies that software update should be dispatched to endpoint without publishing it.\nIf `true`, software definition will be published to endpoint only when a corresponding to this software version file is uploaded.\n"
          }
        },
        "required": [
          "rolloutStrategy"
        ]
      },
      "SoftwareFileDownloadLinkResponse": {
        "type": "object",
        "properties": {
          "link": {
            "type": "string",
            "description": "Software file download link."
          }
        },
        "required": [
          "link"
        ]
      },
      "ClientErrorResponse": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "description": "Detailed error description."
          }
        },
        "required": [
          "message"
        ]
      },
      "Filter": {
        "type": "object",
        "properties": {
          "filterId": {
            "type": "string",
            "description": "filter identifier."
          },
          "rolloutDate": {
            "type": "string",
            "format": "date-time",
            "description": "Filter activation date. Must be in the following ISO 8601 format: `yyyy-MM-dd'T'HH:mm:ss'Z'`."
          }
        }
      }
    }
  }
}