-
Notifications
You must be signed in to change notification settings - Fork 0
/
openapi.yml
211 lines (194 loc) · 8.14 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
openapi: 3.0.0
info:
title: kytos/pathfinder
version: 2.2.2
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
The Kytos Pathfinder repository can be found [here.](https://github.com/kytos/pathfinder)\n
## Overview\n
This API uses HTTP POST requests with JSON arguments and JSON responses."
tags:
- name: Paths
paths:
/api/kytos/pathfinder/v2/:
post:
summary: Returns best paths between the source and destination.
description: "Returns a list of best paths between source and destination, in order. These best paths, namely their metadata, meet standards set by the user.\n
_Standards_, or _Constraints_, are optional, user-specified attributes that best paths will have. The following is an example of a constraint that this API supports:\n
- Bandwidth must be at least **34** units\n
- Delay must be at most **45** units\n
- Owner must be **Joe**.\n
- Reliability can be at least **3** units, or utilization can be at most **32** units, or both.\n
- Path must have links **A** and **B**.\n
- Path must not have link **C**.\n
A path's metadata is the set of data names and corresponding values that each of its edges holds. The following edge data are currently supported:\n
- Bandwidth\n
- Delay\n
- Reliability\n
- Utilization\n
- Priority\n
- Ownership\n
A path has an attribute if each of its edges has that attribute. For example, if a path's metadata has the attribute `bandwidth is at least 50 units`, then each of its edges has a bandwidth of **50** units or higher.\n
To see the connection between a user's standards and a path's metadata, assume a path has two edges **A** and **B**, with the following metadata:\n
- A: bandwidth **44**, delay **56**\n
- B: bandwidth **22**, delay **38**\n
If the user is looking for a path with attribute `delay is at most 60 units`, this path will appear in the search results since edges **A** and **B** have delays that are at most **60** units.\n
If the user is looking for a path with attribute `delay is at most 55 units`, however, this path will ***not*** appear in the search results since edge **A** lacks a delay that is at most **55** units.\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'
desired_links:
type: array
description: Constraint in the form of a list of desired links inside all paths found. All paths will have the desired links.
items:
$ref: "#/components/schemas/Link"
example:
- '2bd01b0d-c875-4263-ad38-fec0b2999582'
- 'c41f6249-3ea6-4aba-a083-08049face1e2'
- '7e8b6bd2-701e-4465-894a-40623e727047'
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"
base_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: 30.5
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: 30.5
reliability: 3
minimum_flexible_hits:
type: integer
description: Minimum number of attributes listed in flexible_metrics that a path will meet.
example: 2
minimum: 1
maximum: 6
required:
- source
- destination
responses:
200:
description: Best paths found, with legal metadata.
content:
application/json:
schema:
type: object
properties:
0:
type: object
properties:
metrics:
description: Path attributes that meet a user's standards.
allOf:
- $ref: "#/components/schemas/Attributes"
paths:
type: array
description: Best paths found
items:
$ref: "#/components/schemas/Path"
400:
description: Illegal value provided.
content:
application/json:
schema:
$ref: "#/components/schemas/badRequest"
examples:
Illegal bandwidth value:
value:
error: "Error in bandwidth value: Expected type: (<class 'int'>, <class 'float'>)"
Illegal ownership value:
value:
error: "Error in ownership value: Expected type: (<class 'str'>)"
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: array
description: Hops between two points
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 bandwidth attribute.
example: 36.2
minimum: 0
maximum: 100
utilization:
type: number
description: Maximum utilization attribute.
example: 58
minimum: 0
maximum: 100
priority:
type: number
description: Minimum priority attribute.
example: 81
minimum: 0
maximum: 100
reliability:
type: number
description: Minimum reliability attribute.
example: 42
minimum: 0
maximum: 100
delay:
type: number
description: Maximum delay attribute.
example: 58.72
minimum: 0
maximum: 100
ownership:
type: string
description: Exact owner attribute.
example: "Bill"
badRequest:
title: Bad Request
type: object
properties:
error:
type: string