xref: /aosp_15_r20/external/ot-br-posix/src/rest/openapi.yaml (revision 4a64e381480ef79f0532b2421e44e6ee336b8e0d) 
1openapi: 3.0.3
2info:
3  title: Swagger OpenThread REST API
4  description: |-
5    This describes the OpenThread Border Router REST API. The API is provided by the otbr-agent, if the cmake flag `OTBR_REST=ON` is set. By default
6    the REST API listens on any address on port 8081.
7
8    Some useful links:
9    - [OpenThread Border Router repository](github.com/openthread/ot-br-posix/)
10  license:
11    name: BSD 3-Clause
12    url: https://github.com/openthread/ot-br-posix/blob/main/LICENSE
13  version: 0.3.0
14servers:
15  - url: http://localhost:8081
16tags:
17  - name: node
18    description: Thread parameters of this node.
19  - name: diagnostics
20    description: Thread network diagnostic.
21paths:
22  /diagnostics:
23    get:
24      tags:
25        - diagnostics
26      summary: Get Thread network diagnostics
27      responses:
28        "200":
29          description: Successful operation
30          content:
31            application/json:
32              schema:
33                type: object
34  /node:
35    get:
36      tags:
37        - node
38      summary: Get current active node parameters
39      responses:
40        "200":
41          description: Successful operation
42          content:
43            application/json:
44              schema:
45                type: object
46    delete:
47      tags:
48        - node
49      summary: Erase all persistent information, essentially factory reset the Border Router.
50      responses:
51        "200":
52          description: Successful operation
53        "409":
54          description: Thread interface is in wrong state.
55  /node/ba-id:
56    get:
57      tags:
58        - node
59      summary: Get the border agent ID
60      responses:
61        "200":
62          description: Successful operation
63          content:
64            application/json:
65              schema:
66                type: string
67                description: 16 byte border agent ID as hex string.
68                example: "AA897CA8A67F6E6DD6166133AD1562A5"
69  /node/rloc:
70    get:
71      tags:
72        - node
73      summary: Routing Locator IPv6 address of this Thread node.
74      responses:
75        "200":
76          description: Successful operation
77          content:
78            application/json:
79              schema:
80                type: string
81                description: RLOC IPv6 address
82                example: "fda4:728e:4b39:bc4a:0:ff:fe00:1000"
83  /node/rloc16:
84    get:
85      tags:
86        - node
87      summary: Routing Locator Router and Child ID (RLOC16).
88      description: Last 16-bit of the Routing Locator IPv6 consisting of the Router ID and a Child ID.
89      responses:
90        "200":
91          description: Successful operation
92          content:
93            application/json:
94              schema:
95                type: number
96                description: RLOC16 address
97                example: 4096
98  /node/ext-address:
99    get:
100      tags:
101        - node
102      summary: IEEE 802.15.4 Extended Address (EUI-64).
103      responses:
104        "200":
105          description: Successful operation
106          content:
107            application/json:
108              schema:
109                type: string
110                description: 8-byte IEEE 802.15.4 Extended Address of this node as hex string.
111                example: "C21F906BE0352A4C"
112  /node/state:
113    get:
114      tags:
115        - node
116      summary: Get current Thread state.
117      description: |-
118        State describing the current Thread role of this Thread node.
119        - disabled: The Thread stack is disabled.
120        - detached: Not currently participating in a Thread network/partition.
121        - child: The Thread Child role.
122        - router: The Thread Router role.
123        - leader: The Thread Leader role.
124      responses:
125        "200":
126          description: Successful operation
127          content:
128            application/json:
129              schema:
130                type: string
131                description: Current state
132                example: "leader"
133    put:
134      tags:
135        - node
136      summary: Set current Thread state.
137      description: |-
138        Enable and disable the Thread protocol operation. If network interface
139        hasn't been started yet, it will get started automatically.
140      responses:
141        "200":
142          description: Successful operation.
143      requestBody:
144        description: New Thread state
145        content:
146          application/json:
147            schema:
148              type: string
149              description: Can be "enable" or "disable".
150              example: "enable"
151  /node/network-name:
152    get:
153      tags:
154        - node
155      summary: Thread network name this node is part of.
156      responses:
157        "200":
158          description: Successful operation
159          content:
160            application/json:
161              schema:
162                type: string
163                description: Thread network name.
164                example: "OpenThread-e445"
165  /node/leader-data:
166    get:
167      tags:
168        - node
169      summary: Gets the network's leader data.
170      responses:
171        "200":
172          description: Successful operation
173          content:
174            application/json:
175              schema:
176                $ref: "#/components/schemas/LeaderData"
177  /node/ext-panid:
178    get:
179      tags:
180        - node
181      summary: Extended PAN ID.
182      responses:
183        "200":
184          description: Successful operation
185          content:
186            application/json:
187              schema:
188                type: string
189                description: 8-byte extended PAN ID as hex string.
190                example: "3CAB144450CF407E"
191  /node/num-of-router:
192    get:
193      tags:
194        - node
195      summary: Get number of router devices
196      responses:
197        "200":
198          description: Successful operation
199          content:
200            application/json:
201              schema:
202                type: number
203                description: Number of routers
204                example: 1
205  /node/dataset/active:
206    get:
207      tags:
208        - node
209      summary: Get current active operational dataset
210      responses:
211        "200":
212          description: Returns currently active operational dataset
213          content:
214            application/json:
215              schema:
216                $ref: "#/components/schemas/Dataset"
217            text/plain:
218              schema:
219                $ref: "#/components/schemas/DatasetTlv"
220        "204":
221          description: No active operational dataset
222    put:
223      tags:
224        - node
225      summary: Creates or updates the active operational dataset
226      description: |-
227        Creates or updates the the active operational dataset on the current node. Only allowed if the Thread node
228        is inactive. If the Thread node is active, a pending dataset should be used to update the current active
229        operational dataset.
230      requestBody:
231        description: |-
232          Operational dataset that will be stored as active operational dataset. Supports request body Content-Type
233          `text/plain` (dataset in TLV format as hex string) or `application/json` (dataset in JSON format). In both
234          cases keys which are not set will be initialized with defaults.
235        content:
236          application/json:
237            schema:
238              $ref: "#/components/schemas/ActiveDataset"
239          plain/text:
240            schema:
241              $ref: "#/components/schemas/DatasetTlv"
242      responses:
243        "200":
244          description: Successfully updated the active operational dataset.
245        "201":
246          description: Successfully created the active operational dataset.
247        "400":
248          description: Invalid request body.
249        "409":
250          description: Writing active operational dataset rejected because Thread network is active.
251  /node/dataset/pending:
252    get:
253      tags:
254        - node
255      summary: Get current pending operational dataset
256      responses:
257        "200":
258          description: Returns currently pending operational dataset
259          content:
260            application/json:
261              schema:
262                $ref: "#/components/schemas/PendingDataset"
263            text/plain:
264              schema:
265                $ref: "#/components/schemas/DatasetTlv"
266        "204":
267          description: No pending operational dataset
268    put:
269      tags:
270        - node
271      summary: Creates or updates the pending operational dataset
272      description: |-
273        Creates or updates the the pending operational dataset on the current node. Delay needs to be set to let
274        the pending dataset apply as active dataset in the near future.
275      requestBody:
276        description: |-
277          Operational dataset that will be stored as pending operational dataset. Supports request body Content-Type
278          `text/plain` (dataset in TLV format as hex string) or `application/json` (dataset in JSON format). In both
279          cases keys which are not set will be initialized with defaults.
280        content:
281          application/json:
282            schema:
283              $ref: "#/components/schemas/PendingDataset"
284          text/plain:
285            schema:
286              $ref: "#/components/schemas/DatasetTlv"
287      responses:
288        "200":
289          description: Successfully updated the pending operational dataset.
290        "201":
291          description: Successfully created the pending operational dataset.
292        "400":
293          description: Invalid request body.
294components:
295  schemas:
296    LeaderData:
297      type: object
298      properties:
299        PartitionId:
300          type: number
301          format: uint32
302          description: Partition ID
303          example: 1230046604
304        Weighting:
305          type: number
306          format: uint8
307          description: Leader Weight
308          example: 64
309        DataVersion:
310          type: number
311          description: Full network data version
312          example: 244
313        StableDataVersion:
314          type: number
315          format: uint8
316          description: Stable Network Data Version
317          example: 186
318        LeaderRouterId:
319          type: number
320          format: uint8
321          description: Leader Router ID
322          example: 4
323    ActiveDataset:
324      type: object
325      properties:
326        ActiveTimestamp:
327          $ref: "#/components/schemas/Timestamp"
328        NetworkKey:
329          type: string
330          description: Network key, 16 bytes long, formatted as a hexadecimal string
331          example: 08277229F21FB7342D705D3CEFDC042A
332          default: random
333        NetworkName:
334          type: string
335          description: Network name, 16 bytes long
336          example: OpenThread-e445
337          default: OpenThread-<PanId>
338        ExtPanId:
339          type: string
340          description: Extended PAN ID, 8 bytes long, formatted as a hexadecimal string
341          example: 996D3BEE320097A3
342          default: random
343        MeshLocalPrefix:
344          type: string
345          description: Mesh local IPv6 prefix
346          example: fd33:d3b9:89e3:72e4::/64
347          default: random
348        PanId:
349          type: integer
350          description: IEEE 802.15.4 PAN ID of the Thread network
351          format: uint16
352          example: 58437
353          default: random
354        Channel:
355          type: integer
356          description: IEEE 802.15.4 channel of the Thread network
357          format: uint16
358          example: 21
359          default: random
360        PSKc:
361          type: string
362          description: The pre-shared commissioner key
363          example: FD943ECA225A28979B991EFAC1218A72
364          default: random
365        SecurityPolicy:
366          $ref: "#/components/schemas/SecurityPolicy"
367        ChannelMask:
368          type: integer
369          description: Channel mask
370          format: uint32
371          example: 134215680
372          default: 134215680
373    PendingDataset:
374      type: object
375      properties:
376        ActiveDataset:
377          oneOf:
378            - $ref: "#/components/schemas/ActiveDataset"
379            - $ref: "#/components/schemas/DatasetTlv"
380        PendingTimestamp:
381          $ref: "#/components/schemas/Timestamp"
382        Delay:
383          type: integer
384          description: Delay timer in milliseconds
385          format: uint32
386          example: 30000
387          default: not set
388    SecurityPolicy:
389      type: object
390      properties:
391        RotationTime:
392          type: integer
393          description: Thread key rotation time in hours
394          format: uint16
395          example: 672
396          default: 672
397        ObtainNetworkKey:
398          type: boolean
399          description: Obtaining the Network Key for out-of-band commissioning is enabled
400          example: true
401          default: true
402        NativeCommissioning:
403          type: boolean
404          description: Native Commissioning using PSKc is allowed
405          example: true
406          default: true
407        Routers:
408          type: boolean
409          description: Thread 1.0/1.1.x Routers are enabled
410          example: true
411          default: true
412        ExternalCommissioning:
413          type: boolean
414          description: External Commissioner authentication is allowed
415          example: true
416          default: true
417        CommercialCommissioning:
418          type: boolean
419          description: Commercial Commissioning is enabled
420          example: false
421          default: false
422        AutonomousEnrollment:
423          type: boolean
424          description: Autonomous Enrollment is enabled
425          example: false
426          default: false
427        NetworkKeyProvisioning:
428          type: boolean
429          description: Network Key Provisioning is enabled
430          example: false
431          default: false
432        TobleLink:
433          type: boolean
434          description: ToBLE link is enabled
435          example: false
436          default: false
437        NonCcmRouters:
438          type: boolean
439          description: Non-CCM Routers enabled
440          example: false
441          default: false
442    Timestamp:
443      type: object
444      properties:
445        Seconds:
446          type: integer
447          description: Timestamp seconds
448          format: uint64
449          example: 10
450          default: 1
451        Ticks:
452          type: integer
453          description: Timestamp ticks
454          format: uint16
455          example: 0
456          default: 0
457        Authoritative:
458          type: boolean
459          example: false
460          default: false
461    DatasetTlv:
462      type: string
463      description: Operational dataset as hex-encoded TLVs.
464      example: 0E080000000000010000000300000F35060004001FFFE0020811111111222222220708FDAD70BFE5AA15DD051000112233445566778899AABBCCDDEEFF030E4F70656E54687265616444656D6F010212340410445F2B5CA6F2A93A55CE570A70EFEECB0C0402A0F7F8
465