forked from kytos/pathfinder
-
Notifications
You must be signed in to change notification settings - Fork 8
/
openapi.yml
217 lines (200 loc) · 7.75 KB
/
openapi.yml
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
206
207
208
209
210
211
212
213
214
215
216
217
openapi: 3.0.0
info:
title: kytos/pathfinder
version: v3
description: "**Warning**: *This documentation is experimental and will
change soon.*\n
## Introduction\n
Kytos Pathfinder's Best Path API has a single endpoint used to provide the best path between two points in a graph when given the following:\n
* Source\n
* Destination\n
* Constraints\n
Kytos Pathfinder repository can be found [here.](https://github.com/kytos-ng/pathfinder)\n
## Overview\n
This API uses HTTP POST requests with JSON arguments and JSON responses."
tags:
- name: Paths
paths:
/api/kytos/pathfinder/v3/:
post:
summary: Returns best paths between the source and destination.
description: "Returns a list of k best paths between source and destination, in order.\n
_Constraints_, are optional, user-specified attributes that best paths will have. \n
The following is an example of link constraints that is supported:\n
- Bandwidth\n
- Delay\n
- Owner\n
- Reliability\n
- Path must have links\n
- Path must not have links\n
In addition, this API also exposes general SPF configuration options that you could leverage:\n
- Link metadata attribute that will be used as link cost by SPF\n
- Maximum number of best paths to be computed\n
- Maximum accumulated path cost to be consireded a best path\n"
tags:
- Paths
requestBody:
content:
application/json:
schema:
type: object
properties:
source:
type: string
description: The source identifier. It may be a datapath or an interface.
example: '00:00:00:00:00:00:00:01:1'
destination:
type: string
description: The destination identifier. It may be a datapath or an interface.
example: '00:00:00:00:00:00:00:02:2'
undesired_links:
type: array
description: Constraint in the form of a list of undesired links in all paths found. When an undesired link is found the endpoint will ignore remove that.
items:
$ref: "#/components/schemas/Link"
example:
- "f13e8308-ecb2-49be-b507-3823af9cc409"
- "ee8d9017-1efd-49ac-9149-4cbeea86f751"
- "a3723e31-bdd3-4102-8b1a-c9fbde6d301a"
spf_attribute:
type: string
description: Link metadata attribute that will be used as link cost by SPF.
default: "hop"
enum:
- "hop"
- "delay"
- "priority"
spf_max_paths:
type: integer
description: Maximum number of 'k' best paths that should be computed by SPF. The lower the value the faster it is going to compute. If you only need a single best path, you should set this value as 1.
default: 2
minimum: 1
maximum: 10
spf_max_path_cost:
type: number
description: Maximum accumulated path cost to be consireded a best path. You should only set this value if you want to set an upper bound accumulated cost.
minimum: 1
mandatory_metrics:
description: Constraint in the form of a set that contains attributes. Paths will have every attribute specified in this set.
allOf:
- $ref: "#/components/schemas/Attributes"
example:
bandwidth: 100
ownership: "Bill"
flexible_metrics:
description: Constraint in the form of a set that contains attributes. Paths will have a user-specified minimum number of attributes specified in this set.
allOf:
- $ref: "#/components/schemas/Attributes"
example:
delay: 81
utilization: 100
reliability: 3
minimum_flexible_hits:
type: integer
description: Minimum number of attributes listed in flexible_metrics that a path will meet.
example: 2
minimum: 0
maximum: 6
parameter:
type: string
example: "hop"
description: "Link metadata attribute that will be used as link cost by SPF. Please use spf_attribute instead, this parameter will be deprecated in the future."
required:
- source
- destination
responses:
200:
description: Best paths found, with legal metadata.
content:
application/json:
schema:
type: object
properties:
paths:
$ref: "#/components/schemas/Paths"
400:
description: Illegal value provided.
content:
application/json:
schema:
$ref: "#/components/schemas/BadRequest"
components:
schemas:
Hop:
type: string
description: Hop identification. Usually is a `switch.id:interface.id`.
example: 00:00:00:00:00:00:00:01:3
Link:
type: string
description: Link identification.
example: f13e8308-ecb2-49be-b507-3823af9cc409
Path:
type: object
properties:
cost:
type: number
description: Path cost
example: 100
hops:
$ref: "#/components/schemas/Hops"
Paths:
type: array
items:
$ref: "#/components/schemas/Path"
Hops:
type: array
description: Path hops
items:
$ref: "#/components/schemas/Hop"
example:
- 00:00:00:00:00:00:00:01:1
- 00:00:00:00:00:00:00:01:2
- 00:00:00:00:00:00:00:01:3
Attributes:
type: object
properties:
bandwidth:
type: number
description: Minimum speed of the link in Gbps. It should be a positive float number.
example: 100
minimum: 0.1
utilization:
type: number
description: Maximum average percentage of utilization of the link. Utilization as 100 means the link does not have capacity left.
example: 70
minimum: 0
maximum: 100
priority:
type: number
description: Maximum priority of the link. The priority of the link could be set based on certain administrative traffic-engineering criteria.
example: 1
minimum: 0
reliability:
type: number
description: Minimum percentage of the reliability of the link. Reliability as 0 means always down.
example: 95
minimum: 1
maximum: 100
delay:
type: number
description: Maximum propagation delay of the link in milliseconds. It should be a positive float number.
example: 200
minimum: 0.1
ownership:
type: string
description: The exact user who should have ownership or be authorized to use the link.
example: "Bill"
not_ownership:
type: array
items:
type: string
description: A list of users whose links we shouldn't use.
example: ["Alice", "Bob"]
BadRequest:
title: Bad Request
type: object
properties:
code:
type: integer
description:
type: string