swagger-backend.yaml

---
swagger: '2.0'
info:
  description: Flotta backend API for remote data storage
  title: Flotta backend API
  version: 1.0.0
  contact:
    name: Flotta flotta
    url: 'https://github.com/project-flotta'
    email: flotta@redhat.com
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
tags:
  - name: backend
    description: Edge device backend storage management
schemes:
  - https
consumes:
  - application/json
produces:
  - application/json
basePath: /api/flotta-backend/v1
definitions:
  error:
    type: object
    required:
      - message
    properties:
      message:
        type: string
        description: >-
          Exposes the error message generated at the backend when there is an
          error (example HTTP code 500).
  device-configuration-response:
    type: object
    properties:
      message:
        type: string
        description: >-
          Exposes the error message generated at the backend when there is an
          error (example HTTP code 500).
      device-configuration:
        x-go-type:
          type: DeviceConfigurationMessage
          import:
            package: github.com/project-flotta/flotta-operator/models
            alias: commonmodel
  device-registration-status-response:
    type: object
    properties:
      status:
        type: string
        description: >-
          Returns the device registration status, which can be one of the
          following {registered, unregistered, unknown}.
      namespace:
        type: string
        description: >-
          Namespace the device should be or was finally placed during registration.
      message:
        type: string
        description: >-
          Exposes the error message generated at the backend when there is an
          error (example HTTP code 500).

paths:
  '/namespaces/{namespace}/devices/{device-id}/configuration':
    get:
      description: Returns the device configuration
      operationId: GetDeviceConfiguration
      tags:
        - backend
      parameters:
        - in: path
          name: namespace
          description: Namespace where the device resides
          type: string
          required: true
        - in: path
          name: device-id
          description: Device ID
          type: string
          required: true
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/device-configuration-response'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        default:
          description: Error
          schema:
            $ref: '#/definitions/device-configuration-response'
  '/namespaces/{namespace}/devices/{device-id}/enrolment':
    post:
      description: Initiates the process of enrolling the device
      operationId: EnrolDevice
      tags:
        - backend
      parameters:
        - in: path
          name: namespace
          description: Namespace where the device resides
          type: string
          required: true
        - in: path
          name: device-id
          description: Device ID
          type: string
          required: true
        - in: body
          name: enrolment-info
          required: true
          schema:
            x-go-type:
              type: EnrolmentInfo
              import:
                package: github.com/project-flotta/flotta-operator/models
                alias: commonmodel
      responses:
        '200':
          description: OK
        '201':
          description: Created
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        default:
          description: Error
          schema:
            $ref: '#/definitions/error'
  '/namespaces/{namespace}/devices/{device-id}/registration':
    get:
      description: >-
        Returns a device registration status, which can be registered,
        unregistered or unknown.
      operationId: GetRegistrationStatus
      tags:
        - backend
      parameters:
        - in: path
          name: namespace
          description: Namespace where the device resides
          type: string
          required: true
        - in: path
          name: device-id
          description: Device ID
          type: string
          required: true
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/device-registration-status-response'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        default:
          description: Error
          schema:
            $ref: '#/definitions/device-registration-status-response'
    put:
      description: Registers the device by providing its hardware configuration
      operationId: RegisterDevice
      tags:
        - backend
      parameters:
        - in: path
          name: namespace
          description: Namespace where the device resides
          type: string
          required: true
        - in: path
          name: device-id
          description: Device ID
          type: string
          required: true
        - in: body
          name: registration-info
          required: true
          schema:
            x-go-type:
              type: RegistrationInfo
              import:
                package: github.com/project-flotta/flotta-operator/models
                alias: commonmodel
      responses:
        '200':
          description: Updated
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        default:
          description: Error
          schema:
            $ref: '#/definitions/error'
  '/namespaces/{namespace}/devices/{device-id}/heartbeat':
    put:
      description: Updates the heartbeat information of the device.
      operationId: UpdateHeartBeat
      tags:
        - backend
      parameters:
        - in: path
          name: namespace
          description: Namespace where the device resides
          type: string
          required: true
        - in: path
          name: device-id
          description: Device ID
          type: string
          required: true
        - in: body
          name: heartbeat
          required: true
          schema:
            type: object
            x-go-type:
              type: Heartbeat
              import:
                package: github.com/project-flotta/flotta-operator/models
                alias: commonmodel
      responses:
        '200':
          description: Success
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        default:
          description: Error
          schema:
            $ref: '#/definitions/error'
  '/namespaces/{namespace}/devices/{device-id}/playbookexecutions':
    get:
      description: Returns the playbook executions.
      operationId: GetPlaybookExecutions
      tags:
        - backend
      parameters:
        - in: path
          name: namespace
          description: Namespace where the device resides
          type: string
          required: true
        - in: path
          name: device-id
          description: Device ID
          type: string
          required: true
      responses:
        '200':
          description: OK
          schema:
            x-go-type:
              type: PlaybookExecutionsResponse
              import:
                package: github.com/project-flotta/flotta-operator/models
                alias: commonmodel
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        default:
          description: Error
          schema:
            $ref: '#/definitions/error'