Zededa PatchEnvelopeConfiguration API

openapi: 3.2.0
info:
  title: ZEDEDA App Profiles Service AppProfileService Patch Envelope Configuration API
  description: The ZEDEDA App Profiles Service is part of ZEDEDA Edge Orchestration Platform. This service enables customers to define their app profiles on ZEDEDA platform and to manage them remotely.
  termsOfService: https://www.zededa.com/terms
  version: '1.0'
  contact:
    name: ZEDEDA API Support
    url: https://www.zededa.com/support
    email: support@zededa.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: /api
security:
- BearerToken: []
tags:
- name: PatchEnvelopeConfiguration
paths:
  /v1/patch-envelope:
    get:
      summary: Get all the patch envelopes
      description: Get the list of patch envelope details.
      operationId: PatchEnvelopeConfiguration_GetPatchEnvelope
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatchEnvelopeList'
        '401':
          description: Unauthorized. The API gateway did not process the request because it lacks valid authentication credentials for the target resource. The request header has either no authorization details or an authorization that has been refused.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZsrvResponse'
        '403':
          description: Forbidden. The API gateway did not process the request because the requestor does not have application level access permission for the operation or does not have access scope to the project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZsrvResponse'
        '500':
          description: Internal Server Error. The API gateway experienced an unexpected condition. Specific error condition is indicated in error codes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZsrvResponse'
        '504':
          description: Gateway Timeout. The API gateway did not receive a timely response from an upstream microservice it needed to communicate with in order to complete the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZsrvResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googlerpcStatus'
      parameters:
      - name: projectNamePattern
        description: project name pattern
        in: query
        required: false
        schema:
          type: string
      - name: namePattern
        description: patch envelope name pattern
        in: query
        required: false
        schema:
          type: string
      - name: next.pageToken
        description: Page Token
        in: query
        required: false
        schema:
          type: string
      - name: next.orderBy
        description: OrderBy helps in sorting the list response
        in: query
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: next.pageNum
        description: Page Number
        in: query
        required: false
        schema:
          type: number
          format: int64
      - name: next.pageSize
        description: Defines the page size
        in: query
        required: false
        schema:
          type: number
          format: int64
      - name: next.totalPages
        description: Total number of pages to be fetched.
        in: query
        required: false
        schema:
          type: number
          format: int64
      - name: summary
        description: Only summary of the records required
        in: query
        required: false
        schema:
          type: boolean
      - name: X-Request-Id
        in: header
        required: false
        description: User-Agent specified id to track a request
        schema:
          type: string
      tags:
      - PatchEnvelopeConfiguration
    post:
      summary: Create patch envelope
      description: Create a patch envelope record.
      operationId: PatchEnvelopeConfiguration_CreatePatchEnvelope
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZsrvResponse'
        '401':
          description: Unauthorized. The API gateway did not process the request because it lacks valid authentication credentials for the target resource. The request header has either no authorization details or an authorization that has been refused.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZsrvResponse'
        '403':
          description: Forbidden. The API gateway did not process the request because the requestor does not have application level access permission for the operation or does not have access scope to the project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZsrvResponse'
        '500':
          description: Internal Server Error. The API gateway experienced an unexpected condition. Specific error condition is indicated in error codes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZsrvResponse'
        '504':
          description: Gateway Timeout. The API gateway did not receive a timely response from an upstream microservice it needed to communicate with in order to complete the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZsrvResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googlerpcStatus'
      parameters:
      - name: X-Request-Id
        in: header
        required: false
        description: User-Agent specified id to track a request
        schema:
          type: string
      tags:
      - PatchEnvelopeConfiguration
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchEnvelope'
        required: true
  /v1/patch-envelope/id/{id}:
    get:
      summary: Get patch envelope by id
      description: Get patch envelope detail by patch envelope id.
      operationId: PatchEnvelopeConfiguration_GetPatchEnvelopeById
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatchEnvelope'
        '401':
          description: Unauthorized. The API gateway did not process the request because it lacks valid authentication credentials for the target resource. The request header has either no authorization details or an authorization that has been refused.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZsrvResponse'
        '403':
          description: Forbidden. The API gateway did not process the request because the requestor does not have application level access permission for the operation or does not have access scope to the project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZsrvResponse'
        '404':
          description: Not Found. The API gateway did not process the request because the requested resource could not be found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZsrvResponse'
        '500':
          description: Internal Server Error. The API gateway experienced an unexpected condition. Specific error condition is indicated in error codes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZsrvResponse'
        '504':
          description: Gateway Timeout. The API gateway did not receive a timely response from an upstream microservice it needed to communicate with in order to complete the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZsrvResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googlerpcStatus'
      parameters:
      - name: id
        description: System defined universally unique Id of the patch envelope
        in: path
        required: true
        schema:
          type: string
      - name: X-Request-Id
        in: header
        required: false
        description: User-Agent specified id to track a request
        schema:
          type: string
      tags:
      - PatchEnvelopeConfiguration
    delete:
      summary: Delete patch envelope
      description: Deletes patch envelope with specified id
      operationId: PatchEnvelopeConfiguration_DeleteAppInstanceSnapshot
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZsrvResponse'
        '401':
          description: Unauthorized. The API gateway did not process the request because it lacks valid authentication credentials for the target resource. The request header has either no authorization details or an authorization that has been refused.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZsrvResponse'
        '403':
          description: Forbidden. The API gateway did not process the request because the requestor does not have application level access permission for the operation or does not have access scope to the project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZsrvResponse'
        '404':
          description: Not Found. The API gateway did not process the request because the requested resource could not be found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZsrvResponse'
        '500':
          description: Internal Server Error. The API gateway experienced an unexpected condition. Specific error condition is indicated in error codes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZsrvResponse'
        '504':
          description: Gateway Timeout. The API gateway did not receive a timely response from an upstream microservice it needed to communicate with in order to complete the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZsrvResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googlerpcStatus'
      parameters:
      - name: id
        description: System defined universally unique Id of the patch envelope
        in: path
        required: true
        schema:
          type: string
      - name: X-Request-Id
        in: header
        required: false
        description: User-Agent specified id to track a request
        schema:
          type: string
      tags:
      - PatchEnvelopeConfiguration
    put:
      summary: Update patch envelope
      description: Update apatch envelope record. The usual pattern to update a patch envelope bundle record is to retrieve the record and update with the modified values in a new body.
      operationId: PatchEnvelopeConfiguration_UpdatePatchEnvelope
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZsrvResponse'
        '401':
          description: Unauthorized. The API gateway did not process the request because it lacks valid authentication credentials for the target resource. The request header has either no authorization details or an authorization that has been refused.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZsrvResponse'
        '403':
          description: Forbidden. The API gateway did not process the request because the requestor does not have application level access permission for the operation or does not have access scope to the project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZsrvResponse'
        '404':
          description: Not Found. The API gateway did not process the request because the requested resource could not be found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZsrvResponse'
        '500':
          description: Internal Server Error. The API gateway experienced an unexpected condition. Specific error condition is indicated in error codes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZsrvResponse'
        '504':
          description: Gateway Timeout. The API gateway did not receive a timely response from an upstream microservice it needed to communicate with in order to complete the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZsrvResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googlerpcStatus'
      parameters:
      - name: id
        description: System defined universally unique Id of the patch envelope.
        in: path
        required: true
        schema:
          type: string
      - name: X-Request-Id
        in: header
        required: false
        description: User-Agent specified id to track a request
        schema:
          type: string
      tags:
      - PatchEnvelopeConfiguration
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: User defined name of the patch envelope, unique across the enterprise. Once patch envelope is created, name can’t be changed.
                  maxLength: 256
                  minLength: 3
                  pattern: '[a-zA-Z0-9][a-zA-Z0-9_.-]+'
                  uniqueItems: true
                title:
                  type: string
                  description: User defined title of the patch envelope. Title can be changed at any time.
                  maxLength: 256
                  minLength: 3
                  pattern: '[a-zA-Z0-9]+[a-zA-Z0-9!-~ ]+'
                description:
                  type: string
                  description: Detailed description of the patch envelope.
                  maxLength: 256
                revision:
                  $ref: '#/components/schemas/ObjectRevision'
                  description: system defined info
                  readOnly: true
                userDefinedVersion:
                  type: string
                  description: User defined version for the given patch envelope
                  title: optional - arbitrary version string if any by user
                action:
                  $ref: '#/components/schemas/PatchEnvelopeAction'
                  description: Flag to represent whether device needs to present it to app instance
                  title: 'if activate is false, device should only download

                    images and not present them to app instance'
                artifacts:
                  type: array
                  items:
                    $ref: '#/components/schemas/BinaryArtifact'
                  description: Patch envelope artifacts
                projectId:
                  type: string
                  description: project id
                deviceCount:
                  type: number
                  format: int64
                  description: number of devices referencing this patch envelope
                projectName:
                  type: string
                  description: project name
              description: PatchEnvelope is a proto that should be used by user-agents to create/update opaque data for application instances.
              title: Opaque data for application instances
              required:
              - name
              - title
              - action
              - artifacts
        required: true
  /v1/patch-envelope/name/{name}:
    get:
      summary: Get patch envelope by name
      description: Get patch envelope detail by patch envelope name.
      operationId: PatchEnvelopeConfiguration_GetPatchEnvelopeByName
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatchEnvelope'
        '401':
          description: Unauthorized. The API gateway did not process the request because it lacks valid authentication credentials for the target resource. The request header has either no authorization details or an authorization that has been refused.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZsrvResponse'
        '403':
          description: Forbidden. The API gateway did not process the request because the requestor does not have application level access permission for the operation or does not have access scope to the project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZsrvResponse'
        '404':
          description: Not Found. The API gateway did not process the request because the requested resource could not be found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZsrvResponse'
        '500':
          description: Internal Server Error. The API gateway experienced an unexpected condition. Specific error condition is indicated in error codes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZsrvResponse'
        '504':
          description: Gateway Timeout. The API gateway did not receive a timely response from an upstream microservice it needed to communicate with in order to complete the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZsrvResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googlerpcStatus'
      parameters:
      - name: name
        description: User defined name of the patch envelope, unique across the enterprise. Once object is created, name can’t be changed
        in: path
        required: true
        schema:
          type: string
      - name: X-Request-Id
        in: header
        required: false
        description: User-Agent specified id to track a request
        schema:
          type: string
      tags:
      - PatchEnvelopeConfiguration
  /v1/patch-envelope/status:
    get:
      summary: Get patch envelope status
      description: Get patch envelope status information.
      operationId: PatchEnvelopeConfiguration_GetPatchEnvelopeStatus
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatchStatusListMsg'
        '401':
          description: Unauthorized. The API gateway did not process the request because it lacks valid authentication credentials for the target resource. The request header has either no authorization details or an authorization that has been refused.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZsrvResponse'
        '403':
          description: Forbidden. The API gateway did not process the request because the requestor does not have application level access permission for the operation or does not have access scope to the project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZsrvResponse'
        '500':
          description: Internal Server Error. The API gateway experienced an unexpected condition. Specific error condition is indicated in error codes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZsrvResponse'
        '504':
          description: Gateway Timeout. The API gateway did not receive a timely response from an upstream microservice it needed to communicate with in order to complete the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZsrvResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googlerpcStatus'
      parameters:
      - name: summary
        in: query
        required: false
        schema:
          type: boolean
      - name: filter.deviceName
        in: query
        required: false
        schema:
          type: string
      - name: next.pageToken
        description: Page Token
        in: query
        required: false
        schema:
          type: string
      - name: next.orderBy
        description: OrderBy helps in sorting the list response
        in: query
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: next.pageNum
        description: Page Number
        in: query
        required: false
        schema:
          type: number
          format: int64
      - name: next.pageSize
        description: Defines the page size
        in: query
        required: false
        schema:
          type: number
          format: int64
      - name: next.totalPages
        description: Total number of pages to be fetched.
        in: query
        required: false
        schema:
          type: number
          format: int64
      - name: fields
        in: query
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: X-Request-Id
        in: header
        required: false
        description: User-Agent specified id to track a request
        schema:
          type: string
      tags:
      - PatchEnvelopeConfiguration
components:
  schemas:
    BinaryArtifact:
      type: object
      properties:
        format:
          $ref: '#/components/schemas/OpaqueObjectCategory'
          title: base64 or binary blob only - secret type is invalid
        base64Artifact:
          $ref: '#/components/schemas/InlineOpaqueBase64Data'
        binaryArtifact:
          $ref: '#/components/schemas/ExternalOpaqueBinaryBlob'
        artifactMetaData:
          type: string
          title: optional - any arbitrary metadata about/for artifact encoded to base64 string
        id:
          type: string
          description: System defined universally unique Id of the artifact.
          title: artifact id
          readOnly: true
          pattern: '[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}'
          uniqueItems: true
    PatchEnvelope:
      type: object
      properties:
        id:
          type: string
          description: System defined universally unique Id of the patch envelope.
          readOnly: true
          pattern: '[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}'
          uniqueItems: true
        name:
          type: string
          description: User defined name of the patch envelope, unique across the enterprise. Once patch envelope is created, name can’t be changed.
          maxLength: 256
          minLength: 3
          pattern: '[a-zA-Z0-9][a-zA-Z0-9_.-]+'
          uniqueItems: true
        title:
          type: string
          description: User defined title of the patch envelope. Title can be changed at any time.
          maxLength: 256
          minLength: 3
          pattern: '[a-zA-Z0-9]+[a-zA-Z0-9!-~ ]+'
        description:
          type: string
          description: Detailed description of the patch envelope.
          maxLength: 256
        revision:
          $ref: '#/components/schemas/ObjectRevision'
          description: system defined info
          readOnly: true
        userDefinedVersion:
          type: string
          description: User defined version for the given patch envelope
          title: optional - arbitrary version string if any by user
        action:
          $ref: '#/components/schemas/PatchEnvelopeAction'
          description: Flag to represent whether device needs to present it to app instance
          title: 'if activate is false, device should only download

            images and not present them to app instance'
        artifacts:
          type: array
          items:
            $ref: '#/components/schemas/BinaryArtifact'
          description: Patch envelope artifacts
        projectId:
          type: string
          description: project id
        deviceCount:
          type: number
          format: int64
          description: number of devices referencing this patch envelope
        projectName:
          type: string
          description: project name
      description: PatchEnvelope is a proto that should be used by user-agents to create/update opaque data for application instances.
      title: Opaque data for application instances
      required:
      - name
      - title
      - action
      - artifacts
    PatchEnvelopeStatus:
      type: object
      properties:
        id:
          type: string
          description: patch envelope id
        name:
          type: string
          description: User defined name of the patch envelope, unique across the enterprise. Once patch envelope is created, name can’t be changed
          maxLength: 256
          minLength: 3
          pattern: '[a-zA-Z0-9][a-zA-Z0-9_.-]+'
          uniqueItems: true
        userDefinedVersion:
          type: string
          description: User defined version for the given patch envelope
        state:
          $ref: '#/components/schemas/PatchEnvelopeState'
          description: Patch envelope state
        errors:
          type: array
          items:
            type: string
          description: Patch envelope error
        projectId:
          type: string
          description: project id
        projectName:
          type: string
          description: project name
        deviceId:
          type: string
          description: device id
        deviceName:
          type: string
          description: device name
      description: PatchEnvelopeStatus encapsulates the status of an patch envelope
      title: Patch Envelope status message
    ZsrvError:
      type: object
      properties:
        ec:
          $ref: '#/components/schemas/ZsrvErrorCode'
          title: 'Enumrated error code, describes more granular numerical

            value than just httpStatus'
        location:
          type: string
          title: 'Ignore: Internal field only'
        details:
          type: string
          title: Field captures string description of details
    Summary:
      type: object
      properties:
        description:
          type: string
          description: Summary description
        total:
          type: number
          format: int64
          description: Total
        values:
          type: object
          additionalProperties:
            type: integer
            format: int64
          description: 'Values: Map for storing <string, uint32>'
      description: Summary is used to store the Summary details
      title: Summary is used to store the Summary details
    protobufAny:
      type: object
      properties:
        typeUrl:
          type: string
        value:
          type: string
          format: byte
    Cursor:
      type: object
      properties:
        pageToken:
          type: string
          description: Page Token
        orderBy:
          type: array
          items:
            type: string
          description: OrderBy helps in sorting the list response
        pageNum:
          type: number
          format: int64
          description: Page Number
        pageSize:
          type: number
          format: int64
          description: Defines the page size
        totalPages:
          type: number
          format: int64
          description: Total number of pages to be fetched.
      description: 'Cursor helps in filtering the various list response like edge-app bundle list, model list, bundle list etc. '
      title: Cursor is used as filter in list operation.
    PatchEnvelopeState:
      type: string
      enum:
      - PatchEnvelopeStateUnknown
      - PatchEnvelopeStateErrored
      - PatchEnvelopeStateReceived
      - PatchEnvelopeStateDownloading
      - PatchEnvelopeStateDownloaded
      - PatchEnvelopeStateReady
      - PatchEnvelopeStateActive
      default: PatchEnvelopeStateUnknown
      title: "- PatchEnvelopeStateErrored: there is an error with config or during download or verification failed\n - PatchEnvelopeStateReceived: Configuration received but no downloads started\n - PatchEnvelopeStateDownloading: Artifact/Volume download started\nOne or more of the artifacts are being downloaded\n - PatchEnvelopeStateDownloaded: all downloads finished, verified and added to content tree\n - PatchEnvelopeStateReady: patch envelope ready for application instances\napplication instances will still not be allowed\nto fetch the patch envelope contents\n - PatchEnvelopeStateActive: application instances are now allowed to fetch contents"
    InlineOpaqueBase64Data:
      type: object
      properties:
        base64Data:
          type: string
          title: base64 encoded
        fileNameToUse:
          type: string
          title: 'file name to be used for storing this data in EVE.

            the same file name shall be advertised to application agent'
        base64MetaData:
          type: string
          title: optional - any arbitrary metadata encoded to base64 string
    ZcOpsType:
      type: string
      enum:
      - OPS_TYPE_UNSPECIFIED
      - OPS_TYPE_READ
      - OPS_TYPE_DELETE
      - OPS_TYPE_CREATE
      - OPS_TYPE_UPDATE
      - OPS_TYPE_LIST
      default: OPS_TYPE_UNSPECIFIED
      title: ZedCloud internal operation type
    ZsrvResponse:
      type: object
      properties:
        operationType:
          $ref: '#/components/schemas/ZcOpsType'
          title: "Describes one of the operations type : possible values\n                        Read/Delete/Create/Update/List"
        operationStatus:
          $ref: '#/components/schemas/ZcOpsStatus'
          title: if this is log running job
        objectKind:
          type: string
          title: zedcloud object kind on which the operation was performed
        objectId:
          type: string
          title: Unique value identifies the object that was operated on
        objectName:
          type: string
          title: name of the object
        objectRevision:
          type: string
          title: 'object revision post the operation, note Read operation

            doesn''t change the revision'
        objectType:
          $ref: '#/components/schemas/ObjectType'
        operationTime:
          type: string
     

# --- truncated at 32 KB (39 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/zededa/refs/heads/main/openapi/zededa-patchenvelopeconfiguration-api-openapi.yml