openapi.yaml

openapi: "3.0.2"
info:
  version: "0.1.0"
  title: "Bottlerocket API"
  description: "The API for the Bottlerocket OS"
  license:
    name: "Apache-2.0 OR MIT"
    url: "https://github.com/bottlerocket-os/bottlerocket/blob/develop/COPYRIGHT"

servers:
- url: file:///run/api.sock
  description: The production API server

paths:
  /:
    get:
      summary: "Get current model, including settings, services, configuration files, and os info"
      operationId: "get_model"
      parameters:
        - in: query
          name: prefix
          description: "Specific key prefix to query"
          schema:
            type: string
          required: false
      responses:
        200:
          description: "Successful request"
          content:
            application/json:
              schema:
                $ref: "Model"
        500:
          description: "Server error"

  /settings:
    get:
      summary: "Get current settings"
      operationId: "get_settings"
      parameters:
        - in: query
          name: keys
          description: "Specific keys to query. Takes precedence over 'prefix' if both query parameters are supplied"
          schema:
            type: array
            items:
              type: string
          # `style: form` and `explode: false` format parameters as such:  /settings?keys=foo,bar,baz
          style: form
          explode: false
          required: false
        - in: query
          name: prefix
          description: "Specific key prefix to query. This parameter will be ignored if 'keys' is also supplied"
          schema:
            type: string
          required: false
      responses:
        200:
          description: "Successful request"
          content:
            application/json:
              schema:
                $ref: "Settings"
        500:
          description: "Server error"
    patch:
      summary: "Update settings"
      operationId: "set_settings"
      parameters:
        - in: query
          name: tx
          description: "Transaction in which to update settings; defaults to user 'default' transaction"
          schema:
            type: string
          required: false
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "Settings"
      responses:
        204:
          description: "Settings successfully staged for update"
        400:
          description: "Invalid body"
        500:
          description: "Server error"

  /tx:
    get:
      summary: "Get pending settings in a transaction"
      operationId: "get_tx"
      parameters:
        - in: query
          name: tx
          description: "Transaction for which to retrieve pending settings; defaults to user 'default' transaction"
          schema:
            type: string
          required: false
      responses:
        200:
          description: "Successful request"
          content:
            application/json:
              schema:
                $ref: "Settings"
        500:
          description: "Server error"
    delete:
      summary: "Delete transaction"
      operationId: "delete_tx"
      parameters:
        - in: query
          name: tx
          description: "Transaction to delete; defaults to user 'default' transaction"
          schema:
            type: string
          required: false
      responses:
        200:
          description: "Successful deleted pending settings - deleted keys are returned"
        500:
          description: "Server error"

  /tx/list:
    get:
      summary: "List names of pending transactions"
      operationId: "list_tx"
      responses:
        200:
          description: "Successful request"
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        500:
          description: "Server error"

  /tx/commit:
    post:
      summary: "Commit pending settings, without applying changes to config files or restarting services"
      operationId: "commit_tx"
      parameters:
        - in: query
          name: tx
          description: "Transaction to commit; defaults to user 'default' transaction"
          schema:
            type: string
          required: false
      responses:
        200:
          description: "Successfully Staged settings - changed keys are returned"
        500:
          description: "Server error"

  /tx/apply:
    post:
      summary: "Apply changes to config files and restart services"
      operationId: "apply"
      parameters:
        - in: query
          name: keys
          description: "Apply changes only if related to these keys; if not specified, applies for all known keys"
          schema:
            type: array
            items:
              type: string
          # `style: form` and `explode: false` format parameters as such:  /tx/apply?keys=settings.foo,settings.bar
          style: form
          explode: false
          required: false
      responses:
        204:
          description: "Successfully started settings applier"
        500:
          description: "Server error"

  /tx/commit_and_apply:
    post:
      summary: "Commit transaction, and apply any committed changes to relevant config files and services"
      operationId: "commit_tx_and_apply"
      parameters:
        - in: query
          name: tx
          description: "Transaction to commit; defaults to user 'default' transaction"
          schema:
            type: string
          required: false
      responses:
        200:
          description: "Successful settings update, committed keys are returned"
        500:
          description: "Server error"

  /os:
    get:
      summary: "Get OS information such as version, variant, and architecture"
      operationId: "get_os_info"
      parameters:
        - in: query
          name: prefix
          description: "Specific key prefix to query"
          schema:
            type: string
          required: false
      responses:
        200:
          description: "Successful request"
          content:
            application/json:
              # The response is a hashmap of string to string. Example:
              # { "arch": "x86_64" }
              schema:
                type: object
                additionalProperties:
                  type: string
        500:
          description: "Server error"

  /metadata/affected-services:
    get:
      summary: "Get affected services"
      operationId: "get_affected_services"
      parameters:
        - in: query
          name: keys
          description: "Specific keys to query"
          schema:
            type: array
            items:
              type: string
          # `style: form` and `explode: false` format parameters as such:  /metadata/affected-services?keys=settings.foo,settings.bar
          style: form
          explode: false
          required: true
      responses:
        200:
          description: "Successful request"
          content:
            application/json:
              # The response is a hashmap of string to array of strings. Example:
              # { "settings.foo": [ "service1", "service2" ] }
              schema:
                type: object
                additionalProperties:
                  type: array
                  items:
                    type: string
        400:
          description: "Missing required query parameter: 'keys'"
        500:
          description: "Server error"

  /metadata/setting-generators:
    get:
      summary: "Get programs needed to generate settings"
      operationId: "get_setting_generators"
      responses:
        200:
          description: "Successful request"
          content:
            application/json:
              # The response is a hashmap of string to string. Example:
              # { "settings.foobar": "/usr/bin/foobar" }
              schema:
                type: object
                additionalProperties:
                  type: string
        500:
          description: "Server error"

  /metadata/templates:
    get:
      summary: "Get template strings for dynamically generated settings"
      operationId: "get_templates"
      responses:
        200:
          description: "Successful request"
          content:
            application/json:
              # The response is a hashmap of string to string. Example:
              # { "settings.foobar": "hi {{ key }}" }
              schema:
                type: object
                additionalProperties:
                  type: string
        500:
          description: "Server error"

  /services:
    get:
      summary: "Get service data"
      operationId: "get_services"
      parameters:
        - in: query
          name: names
          description: "Specific services to query"
          schema:
            type: array
            items:
              type: string
          # `style: form` and `explode: false` format parameters as such:  /services?names=foo,bar,baz
          style: form
          explode: false
          required: false
        - in: query
          name: prefix
          description: "Specific key prefix to query. This parameter will be ignored if 'names' is also supplied"
          schema:
            type: string
          required: false
      responses:
        200:
          description: "Successful request"
          content:
            application/json:
              schema:
                $ref: "Services"
        500:
          description: "Server error"

  /configuration-files:
    get:
      summary: "Get configuration file data"
      operationId: "get_config_files"
      parameters:
        - in: query
          name: names
          description: "Specific configuration files to query"
          schema:
            type: array
            items:
              type: string
          # `style: form` and `explode: false` format parameters as such:  /configuration-files?names=file1,file2
          style: form
          explode: false
          required: false
      parameters:
        - in: query
          name: prefix
          description: "Specific key prefix to query. This parameter will be ignored if 'names' is also supplied"
          schema:
            type: string
          required: false
      responses:
        200:
          description: "Successful request"
          content:
            application/json:
              schema:
                $ref: "ConfigurationFiles"
        500:
          description: "Server error"

  /actions/reboot:
    post:
      summary: "Reboot"
      operationId: "reboot"
      responses:
        204:
          description: "Reboot requested"
        500:
          description: "Server error"

  /actions/refresh-updates:
    post:
      summary: "Query update repository and refresh list of updates"
      operationId: "refresh_update"
      responses:
        204:
          description: "Successful request"
        500:
          description: "Server error"
        423:
          description: "Update write lock held. Try again in a moment"

  /actions/prepare-update:
    post:
      summary: "Download the chosen update and write the update image to the inactive partition"
      operationId: "prepare_update"
      responses:
        204:
          description: "Successful request"
        404:
          description: "Chosen update does not exist"
        409:
          description: "Action not allowed according to current update state"
        500:
          description: "Server error"
        423:
          description: "Update write lock held. Try again in a moment"

  /actions/activate-update:
    post:
      summary: "Mark the partition with the prepared update as active so you can reboot into the chosen version"
      operationId: "activate_update"
      responses:
        204:
          description: "Successfully activated update"
        404:
          description: "No update image applied to staging partition, need to prepare-update first"
        409:
          description: "Action not allowed according to current update state"
        500:
          description: "Server error"
        423:
          description: "Update write lock held. Try again in a moment"

  /actions/deactivate-update:
    post:
      summary: "Deactivate the update by marking the running partition as active again"
      operationId: "deactivate-update"
      responses:
        204:
          description: "Successfully deactivated update"
        404:
          description: "No update image applied to staging partition, need to prepare-update first"
        409:
          description: "Action not allowed according to current update state"
        500:
          description: "Server error"
        423:
          description: "Update write lock held. Try again in a moment"

  /updates/status:
    get:
      summary: "Get update status"
      operationId: "get_update_status"
      responses:
        200:
          description: "Successful request"
          content:
            application/json:
              schema:
                $ref: "UpdateStatus"
        500:
          description: "Server error"
        423:
          description: "Update write lock held. Try again in a moment"

  /exec:
    get:
      summary: "Request exec WebSocket"
      operationId: "exec"
      responses:
        101:
          description: "Connection upgraded to WebSocket"
        500:
          description: "Server error"