signaling-data-plane-openapi.yaml

openapi: 3.1.2
servers:
  - url: https://example.com/signaling/v1
info:
  description: |-
    This specification contains all mandatory and optional endpoints for the [Dataplane Signaling Protocol (DPS)](https://github.com/eclipse-dataplane-signaling/dataplane-signaling/blob/main/docs/signaling.md)
    to be implemented by the data-plane.
    It is based on OpenAPI 3.1.2 and uses JSON Schema for data modeling.
  version: 0.0.1
  title: Dataplane Signaling Protocol DPS
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
tags:
  - name: Data plane endpoints
    description: Endpoints that must be implemented by the data plane
    externalDocs:
      description: Find out more
      url: 'https://github.com/eclipse-dataplane-signaling/dataplane-signaling/blob/main/docs/signaling.md#data-plane-endpoint'
  - name: Control Plane Registration
    description: Control plane registration endpoints, to be implemented by the data plane. Note that these endpoints are OPTIONAL, but either NONE or ALL must be implemented.
paths:
  /dataflows/prepare:
    post:
      tags:
        - Data plane endpoints
      summary: Prepare a DataFlow
      description: |
        The `prepare` request signals to the [=Data Plane=] to initialize a [=Data Flow=] and any resources required for
        data transfer. The request results in a state machine transition to PREPARING or PREPARED. If the state machine
        transitions to PREPARING, the [=Data Plane=] MUST return HTTP 202 Accepted with the `Location` header set to the
        [data flow status relative URL](#status) and a message body containing a `DataFlowStatusMessage`. If the state
        machine transitions to PREPARED, the [=Data Plane=] MUST return HTTP 200 OK and a `DataFlowStatusMessage`.
      operationId: prepareDataFlow
      responses:
        '200':
          description: DataFlow prepared successfully
          content:
            application/json:
              schema:
                $ref: 'https://w3id.org/dspace-sig/v1.0/DataFlowStatusMessage.schema.json'
              example:
                dataplaneId: dataplane-64345
                state: PREPARED
        '202':
          description: Request received, DataFlow preparation in progress
          headers:
            Location:
              description: URL to poll for DataFlow status
              schema:
                type: string
                format: uri
              example: /dataflows/flow-1234/status
          content:
            application/json:
              schema:
                $ref: 'https://w3id.org/dspace-sig/v1.0/DataFlowStatusMessage.schema.json'
              example:
                dataplaneId: dataplane-64345
                state: PREPARING
        '400':
          description: Bad Request - invalid input, invalid object state or missing required parameters, supplying the
            dataAddress on consumer-pull transfers
      requestBody:
        description: DataFlow preparation request
        required: true
        content:
          application/json:
            schema:
              $ref: 'https://w3id.org/dspace-sig/v1.0/DataFlowPrepareMessage.schema.json'

  /dataflows/{id}/started:
    post:
      tags:
        - Data plane endpoints
      summary: Notify a consumer data plane that a transfer has been started
      description: |
        The `started` request signals to the consumer [=Data Plane=] that a data transmission has begun. For pull
        transfers this indicates the consumer [=Data Plane=] may transmit data. For push transfers this
        indicates the provider has already begun sending data. The request results in a state machine transition to
        STARTED and the Data Plane MUST return HTTP 200 OK and a `DataFlowStatusMessage`.

      operationId: notifyStarted
      parameters:
        - name: id
          in: path
          required: true
          description: The unique identifier of the data flow to start
          schema:
            type: string
            example: flow-1234
      responses:
        '200':
          description: Signals to a data plane that the data transmission has been started normally.
        '400':
          description: Bad Request - invalid input, invalid object state or missing required parameters, omitting the
            dataAddress on consumer-pull transfers or supplying a dataAddress on provider-push transfers.
        '404':
          description: Not Found - data flow with specified ID does not exist
      requestBody:
        description: Notify consumer data plane about started transfer. Required for consumer pull transfers.
        required: false
        content:
          application/json:
            schema:
              $ref: 'https://w3id.org/dspace-sig/v1.0/DataFlowStartedNotificationMessage.schema.json'

  /dataflows/start:
    post:
      tags:
        - Data plane endpoints
      summary: Start a DataFlow (provider side)
      description: |
        The `start` request signals to the [=Data Plane=] to begin a data transfer. The request results in a state
        machine transition to STARTING or STARTED. If the state machine transitions to STARTING, the [=Data Plane=] MUST
        return HTTP 202 Accepted with the `Location` header set to the [data flow status relative URL](#status) and a
        message body containing a `DataFlowStatusMessage`. If the state machine transitions to STARTED, the Data
        Plane MUST return HTTP 200 OK and a `DataFlowStatusMessage`.
      operationId: startDataFlow
      requestBody:
        description: DataFlow start request
        required: true
        content:
          application/json:
            schema:
              $ref: 'https://w3id.org/dspace-sig/v1.0/DataFlowStartMessage.schema.json'

      responses:
        '200':
          description: DataFlow started successfully
          content:
            application/json:
              schema:
                $ref: 'https://w3id.org/dspace-sig/v1.0/DataFlowStatusMessage.schema.json'
              example:
                dataplaneId: dataplane-64345
                state: STARTED
                dataAddress:
                  '@type': DataAddress
                  endpointType: https://23id.org.idsa/v4.1/HTTP
                  endpoint: https://example.com/api/data
                  endpointProperties:
                    - '@type': EndpointProperty
                      name: authorization
                      value: 5up3r53cur3t0k3n
                    - '@type': EndpointProperty
                      name: authType
                      value: bearer
        '202':
          description: Start request received, DataFlow is being started
          headers:
            Location:
              description: The URL to retrieve the data flow status
              schema:
                type: string
                format: uri
              example: /dataflows/flow-1234/status
          content:
            application/json:
              schema:
                $ref: 'https://w3id.org/dspace-sig/v1.0/DataFlowStatusMessage.schema.json'
              example:
                example:
                  dataplaneId: dataplane-64345
                  state: STARTING
        '400':
          description: Bad Request - invalid input, invalid object state or missing required parameters, supplying a
            dataAddress in consumer-pull transfers or omitting the dataAddress in provider-push transfers
        '404':
          description: Not Found - data flow with specified ID does not exist

  /dataflows/{id}/suspend:
    post:
      tags:
        - Data plane endpoints
      summary: Suspend a DataFlow
      description: |
        The suspend request signals to the data plane to suspend an ongoing data transfer.
      operationId: suspendDataFlowById
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: 'https://w3id.org/dspace-sig/v1.0/DataFlowSuspendMessage.schema.json'
      parameters:
        - name: id
          in: path
          required: true
          description: The unique identifier of the data flow to suspend
          schema:
            type: string
            example: flow-1234
      responses:
        '200':
          description: DataFlow suspended successfully
        '400':
          description: Bad Request - invalid input, invalid object state or missing required parameters
        '404':
          description: Not Found - data flow with specified ID does not exist

  /dataflows/{id}/resume:
    post:
      tags:
        - Data plane endpoints
      summary: Resume a DataFlow
      description: |
        The suspend request signals to the data plane to resume a suspended data transfer.
      operationId: resumeDataFlowById
      requestBody:
        content:
          application/json:
            schema:
              $ref: 'https://w3id.org/dspace-sig/v1.0/DataFlowResumeMessage.schema.json'
      parameters:
        - name: id
          in: path
          required: true
          description: The unique identifier of the data flow to resume
          schema:
            type: string
            example: flow-1234
      responses:
        '200':
          description: DataFlow resumed successfully
          content:
            application/json:
              schema:
                $ref: 'https://w3id.org/dspace-sig/v1.0/DataFlowStatusMessage.schema.json'
              example:
                dataplaneId: dataplane-64345
                state: STARTED
        '400':
          description: Bad Request - invalid input, invalid object state or missing required parameters
        '404':
          description: Not Found - data flow with specified ID does not exist

  /dataflows/{id}/terminate:
    post:
      tags:
        - Data plane endpoints
      summary: Terminate a DataFlow
      description: |
        The terminate request signals to the data plane to terminate an ongoing data transfer.
      operationId: terminateDataFlowById
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: 'https://w3id.org/dspace-sig/v1.0/DataFlowTerminateMessage.schema.json'
      parameters:
        - name: id
          in: path
          required: true
          description: The unique identifier of the data flow to terminate
          schema:
            type: string
            example: flow-1234
      responses:
        '200':
          description: DataFlow terminated successfully
        '400':
          description: Bad Request - invalid input, invalid object state or missing required parameters
        '404':
          description: Not Found - data flow with specified ID does not exist

  /dataflows/{id}/status:
    get:
      tags:
        - Data plane endpoints
      summary: Get the status of a DataFlow
      description: |
        The status endpoint returns a representation of the data flow as managed by the data plane
      operationId: getDataFlowStatusById
      parameters:
        - name: id
          in: path
          required: true
          description: The unique identifier of the data flow to retrieve the status for
          schema:
            type: string
            example: flow-1234
      responses:
        '200':
          description: DataFlow status retrieved successfully
          content:
            application/json:
              schema:
                $ref: 'https://w3id.org/dspace-sig/v1.0/DataFlowStatusResponseMessage.schema.json'
              example:
                dataplaneId: dataplane-64345
                state: PREPARING
        '400':
          description: Bad Request - invalid input, invalid object state or missing required parameters
        '404':
          description: Not Found - data flow with specified ID does not exist

  /dataflows/{id}/completed:
    post:
      tags:
        - Data plane endpoints
      summary: Notify the data plane of a completed transfer
      description: |
        The complete endpoint signals to a data plane that the data transmission has completed normally.
      operationId: notifyComplete
      parameters:
        - name: id
          in: path
          required: true
          description: The unique identifier of the data flow to mark as complete
          schema:
            type: string
            example: flow-1234
      responses:
        '200':
          description: DataFlow successfully marked as completed
        '400':
          description: Bad Request - invalid input, invalid object state or missing required parameters
        '404':
          description: Not Found - data flow with specified ID does not exist

  /controlplanes:
    put:
      tags:
        - Control Plane Registration
      summary: Create or Update a control plane registration
      description: |
        The registration endpoint is hosted on the data plane, and may be used to create a new control plane or to
        update an existing control plane registration, fully replacing the existing one.
      operationId: upsertControlplaneRegistration
      requestBody:
        description: Control plane registration data
        required: true
        content:
          application/json:
            schema:
              $ref: 'https://w3id.org/dspace-sig/v1.0/ControlPlaneRegistrationMessage.schema.json'
      responses:
        '200':
          description: Control plane registration updated successfully
        '400':
          description: Bad Request - invalid input, invalid object state or missing required parameters

    delete:
      tags:
        - Control Plane Registration
      summary: Delete a control plane registration
      operationId: deleteControlplaneRegistration
      parameters:
        - name: controlplaneId
          in: path
          required: true
          description: The unique identifier of the control plane to delete
          schema:
            type: string
      responses:
        '204':
          description: Control plane registration deleted successfully
        '400':
          description: Bad Request - invalid input, invalid object state or missing required parameters
        '404':
          description: Not Found - data plane with specified ID does not exist


externalDocs:
  description: Find out more about Dataplane Signaling Protocol
  url: 'https://github.com/eclipse-dataplane-signaling/dataplane-signaling/blob/main/docs/signaling.md'