dataplane-signaling/signaling-control-plane-openapi.yaml at main · FraunhoferISST/dataplane-signaling · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
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 control-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: Control plane endpoints
    description: All endpoints that must be implemented by the control plane
    externalDocs:
      description: Find out more about our store
      url: 'https://github.com/eclipse-dataplane-signaling/dataplane-signaling/blob/main/docs/signaling.md#control-plane-endpoint'
  - name: Data Plane Registration
    description: Data plane registration endpoints, to be implemented by the control plane. Note that these endpoints are OPTIONAL, but either NONE or ALL must be implemented.
paths:

  /transfers/{transferId}/dataflow/prepared:
    post:
      tags:
        - Control plane endpoints
      summary: Signals the PREPARED state
      description: |
        The prepared request signals to the control plane that the data plane is in the PREPARED state and ready to start a data transfer
      operationId: signalPrepared
      parameters:
        - name: transferId
          in: path
          required: true
          description: the unique identifier of the data transfer (= data flow)
          schema:
            type: string
            example: 93a78371-7891-495e-afb5-9b11ac6b1e94
      requestBody:
        description: DataFlow prepared notification
        required: true
        content:
          application/json:
            schema:
              $ref: 'https://w3id.org/dspace-sig/v1.0/DataFlowStatusMessage.schema.json'
            example:
              dataplaneId: dataplane-64345
              state: PREPARED
      responses:
        '200':
          description: Notification received successfully
        '400':
          description: Bad Request - invalid input, invalid object state or missing required parameters
        '404':
          description: Not Found - transfer process with specified ID does not exist

  /transfers/{transferId}/dataflow/started:
    post:
      tags:
        - Control plane endpoints
      summary: Signals the STARTED state
      description: |
        The started request signals to the control plane that the data plane is in the STARTED state and clients can start transmitting data
      operationId: signalStarted
      parameters:
        - name: transferId
          in: path
          required: true
          description: the unique identifier of the data transfer (= data flow)
          schema:
            type: string
            example: 93a78371-7891-495e-afb5-9b11ac6b1e94
      requestBody:
        description: DataFlow started notification
        required: true
        content:
          application/json:
            schema:
              $ref: 'https://w3id.org/dspace-sig/v1.0/DataFlowStatusMessage.schema.json'
            example:
              dataplaneId: dataplane-64345
              state: STARTED
      responses:
        '200':
          description: Notification received successfully
        '400':
          description: Bad Request - invalid input, invalid object state or missing required parameters
        '404':
          description: Not Found - transfer process with specified ID does not exist

  /transfers/{transferId}/dataflow/completed:
    post:
      tags:
        - Control plane endpoints
      summary: Signals the COMPLETED state
      description: |
        The completed request signals to the control plane that the data plane is in the COMPLETED state and all transmissions have finished normally.
      operationId: signalCompleted
      parameters:
        - name: transferId
          in: path
          required: true
          description: the unique identifier of the data transfer (= data flow)
          schema:
            type: string
            example: 93a78371-7891-495e-afb5-9b11ac6b1e94
      requestBody:
        description: DataFlow completed notification
        required: true
        content:
          application/json:
            schema:
              $ref: 'https://w3id.org/dspace-sig/v1.0/DataFlowStatusMessage.schema.json'
            example:
              dataplaneId: dataplane-64345
              state: COMPLETED
      responses:
        '200':
          description: Notification received successfully
        '400':
          description: Bad Request - invalid input, invalid object state or missing required parameters
        '404':
          description: Not Found - transfer process with specified ID does not exist

  /transfers/{transferId}/dataflow/errored:
    post:
      tags:
        - Control plane endpoints
      summary: Signals the TERMINATED state
      description: |
        The prepared request signals to the control plane that the data plane is in the TERMINATED state which indicates abnormal termination.
      operationId: signalTerminated
      parameters:
        - name: transferId
          in: path
          required: true
          description: the unique identifier of the data transfer (= data flow)
          schema:
            type: string
            example: 93a78371-7891-495e-afb5-9b11ac6b1e94
      requestBody:
        description: DataFlow terminated notification
        required: true
        content:
          application/json:
            schema:
              $ref: 'https://w3id.org/dspace-sig/v1.0/DataFlowStatusMessage.schema.json'
            example:
              dataplaneId: dataplane-64345
              state: TERMINATED
      responses:
        '200':
          description: Notification received successfully
        '400':
          description: Bad Request - invalid input, invalid object state or missing required parameters
        '404':
          description: Not Found - transfer process with specified ID does not exist

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

    delete:
      tags:
        - Data Plane Registration
      summary: Delete a data plane registration
      operationId: deleteDataplaneRegistration
      parameters:
        - name: dataplaneId
          in: path
          required: true
          description: The unique identifier of the data plane to delete
          schema:
            type: string
      responses:
        '204':
          description: Data 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'