rest.rst 11.1 KB
Newer Older
1 2 3 4 5 6
SlapOS Master REST API (v1)
***************************

Find your SSL keys
------------------

Łukasz Nowak's avatar
Łukasz Nowak committed
7
You can find  X509 key/certificate to authenticate to the SlapOS Master.
8 9 10 11 12 13 14
Visit https://www.vifib.net/.

Exchange format
---------------

SlapOS master will support both XML and JSON formats for input and output.

Łukasz Nowak's avatar
Łukasz Nowak committed
15
The Accept header is required and responsible for format selection.
16 17 18 19 20 21 22 23 24 25 26 27 28 29

Response status code
--------------------

Success
+++++++

``GET`` requests will return a ``"200 OK"`` response if the resource is successfully retrieved.

``POST`` requests which create a resource we will return a ``"201 Created"`` response if successful.

``POST`` requests which perform some other action such as sending a campaign
will return a ``"200 OK"`` response if successful.

Łukasz Nowak's avatar
Łukasz Nowak committed
30
``PUT`` requests will return a ``"200 OK"`` response if the resource is successfully updated and ``"204 No Content"`` in case if no modification was applied..
31 32 33

``DELETE`` requests will return a ``"200 OK"`` response if the resource is successfully deleted.

Łukasz Nowak's avatar
Łukasz Nowak committed
34 35
``OPTIONS`` requests will return ``"200 OK"`` response with allowed method on given url.

Łukasz Nowak's avatar
Łukasz Nowak committed
36 37
Common Error Responses
++++++++++++++++++++++
38

Łukasz Nowak's avatar
Łukasz Nowak committed
39 40 41
400 Bad Request
~~~~~~~~~~~~~~~
The request body does not follow the API (one argument is missing or malformed). The full information is available as text body::
42

Łukasz Nowak's avatar
Łukasz Nowak committed
43
  HTTP/1.1 400 Bad Request
Łukasz Nowak's avatar
Łukasz Nowak committed
44
  Content-Type: application/json
Łukasz Nowak's avatar
Łukasz Nowak committed
45 46 47 48 49 50 51

  {
    "computer_id": "Parameter is missing"
  }

402 Payment Required
~~~~~~~~~~~~~~~~~~~~
52

Łukasz Nowak's avatar
Łukasz Nowak committed
53
The request can not be fulfilled because account is locked.
54

Łukasz Nowak's avatar
Łukasz Nowak committed
55 56 57 58 59 60 61 62 63 64 65
403 Forbidden
~~~~~~~~~~~~~
Wrong SSL key used or access to invalid ID.

404 Not Found
~~~~~~~~~~~~~
Request to non existing resource made.

500 Internal Server Error
~~~~~~~~~~~~~~~~~~~~~~~~~
Unexpected error.
66 67 68 69 70 71 72

Instance Methods
****************

Requesting a new instance
-------------------------

Łukasz Nowak's avatar
Łukasz Nowak committed
73
Request a new instantiation of a software.
74 75 76

`Request`::

Łukasz Nowak's avatar
Łukasz Nowak committed
77
  POST http://example.com/api/v1/request HTTP/1.1
Łukasz Nowak's avatar
Łukasz Nowak committed
78
  Accept: application/json
Łukasz Nowak's avatar
Łukasz Nowak committed
79
  Content-Type: application/json; charset=utf-8
80 81 82 83 84 85 86

`Expected Request Body`::

  {
    "title": "My unique instance",
    "software_release": "http://example.com/example.cfg",
    "software_type": "type_provided_by_the_software",
Łukasz Nowak's avatar
Łukasz Nowak committed
87 88
    "slave": False, # one of: True or False
    "status": "started", # one of: started, stopped
89 90 91 92 93 94 95 96 97 98 99 100 101 102
    "parameter": {
      "Custom1": "one string",
      "Custom2": "one float",
      "Custom3": ["abc", "def"],
      },
    "sla": {
      "computer_id": "COMP-0",
      }
  }

`Expected Response`::

  HTTP/1.1 201 Created
  Content-Type: application/json; charset=utf-8
103
  Location: http://maybeother.example.com/some/url/instance_id
104 105 106 107 108 109 110 111 112

  {
    "status": "started",
    "connection": {
      "custom_connection_parameter_1": "foo",
      "custom_connection_parameter_2": "bar"
    }
  }

Łukasz Nowak's avatar
Łukasz Nowak committed
113
`Additional Responses`::
114

Łukasz Nowak's avatar
Łukasz Nowak committed
115 116
  HTTP/1.1 202 Accepted
  Content-Type: application/json; charset=utf-8
117
  Location: http://maybeother.example.com/some/url/instance_id
118

Łukasz Nowak's avatar
Łukasz Nowak committed
119 120 121
  {
    "status": "processing"
  }
122

Łukasz Nowak's avatar
Łukasz Nowak committed
123
The request has been accepted for processing
124

Łukasz Nowak's avatar
Łukasz Nowak committed
125 126 127
`Error Responses`:

* ``409 Conflict`` The request can not be process because of the current status of the instance (sla changed, instance is under deletion, software release can not be changed, ...).
128 129 130 131 132


Get instance information
------------------------

Łukasz Nowak's avatar
Łukasz Nowak committed
133
Request all instance information.
134 135 136

`Request`::

Łukasz Nowak's avatar
Łukasz Nowak committed
137
  GET http://example.com/api/v1/instance/{instance_id} HTTP/1.1
Łukasz Nowak's avatar
Łukasz Nowak committed
138
  Accept: application/json
139 140 141 142 143 144 145 146 147 148 149

`Route values`:

* ``instance_id``: the ID of the instance

`No Expected Request Body`

`Expected Response`::

  HTTP/1.1 200 OK
  Content-Type: application/json; charset=utf-8
Łukasz Nowak's avatar
Łukasz Nowak committed
150

151
  {
Łukasz Nowak's avatar
Łukasz Nowak committed
152
    "title": "The Instance Title",
Łukasz Nowak's avatar
Łukasz Nowak committed
153
    "status": "start", # one of: start, stop, destroy
154 155
    "software_release": "http://example.com/example.cfg",
    "software_type": "type_provided_by_the_software",
Łukasz Nowak's avatar
Łukasz Nowak committed
156
    "slave": False, # one of: True, False
157 158 159 160 161 162 163 164 165 166 167 168 169 170
    "connection": {
      "custom_connection_parameter_1": "foo",
      "custom_connection_parameter_2": "bar"
    },
    "parameter": {
      "Custom1": "one string",
      "Custom2": "one float",
      "Custom3": ["abc", "def"],
      },
    "sla": {
      "computer_id": "COMP-0",
      }
    "children_id_list": ["subinstance1", "subinstance2"],
    "partition": {
Łukasz Nowak's avatar
Łukasz Nowak committed
171 172
      "public_ip": ["::1", "91.121.63.94"],
      "private_ip": ["127.0.0.1"],
173 174 175 176 177 178 179 180
      "tap_interface": "tap2",
    },
  }

`Error Responses`:

* ``409 Conflict`` The request can not be process because of the current status of the instance

Łukasz Nowak's avatar
Łukasz Nowak committed
181 182
Get instance authentication certificates
----------------------------------------
183 184 185 186 187

Request the instance certificates.

`Request`::

Łukasz Nowak's avatar
Łukasz Nowak committed
188
  GET http://example.com/api/v1/instance/{instance_id}/certificate HTTP/1.1
Łukasz Nowak's avatar
Łukasz Nowak committed
189
  Accept: application/json
190 191 192 193 194 195 196 197 198 199 200

`Route values`:

* ``instance_id``: the ID of the instance

`No Expected Request Body`

`Expected Response`::

  HTTP/1.1 200 OK
  Content-Type: application/json; charset=utf-8
Łukasz Nowak's avatar
Łukasz Nowak committed
201

202
  {
Łukasz Nowak's avatar
Łukasz Nowak committed
203 204
    "ssl_key": "-----BEGIN PRIVATE KEY-----\nMIIEvgIBADAN...h2VSZRlSN\n-----END PRIVATE KEY-----",
    "ssl_certificate": "-----BEGIN CERTIFICATE-----\nMIIEAzCCAuugAwIBAgICHQI...ulYdXJabLOeCOA=\n-----END CERTIFICATE-----",
205 206 207 208 209 210 211 212 213
  }

`Error Responses`:

* ``409 Conflict`` The request can not be process because of the current status of the instance

Bang instance
-------------

Łukasz Nowak's avatar
Łukasz Nowak committed
214
Trigger the re-instantiation of all partitions in the instance tree
215 216 217

`Request`::

Łukasz Nowak's avatar
Łukasz Nowak committed
218
  POST http://example.com/api/v1/instance/{instance_id}/bang HTTP/1.1
Łukasz Nowak's avatar
Łukasz Nowak committed
219
  Accept: application/json
Łukasz Nowak's avatar
Łukasz Nowak committed
220
  Content-Type: application/json; charset=utf-8
221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236

`Route values`:

* ``instance_id``: the ID of the instance

`Expected Request Body`::

  {
    "log": "Explain why this method was called",
  }

`Expected Response`::

  HTTP/1.1 200 OK
  Content-Type: application/json; charset=utf-8

Łukasz Nowak's avatar
Łukasz Nowak committed
237 238
Modifying instance
------------------
239

Łukasz Nowak's avatar
Łukasz Nowak committed
240
Modify the instance information and status.
241 242 243

`Request`::

Łukasz Nowak's avatar
Łukasz Nowak committed
244
  PUT http://example.com/api/v1/instance/{instance_id} HTTP/1.1
Łukasz Nowak's avatar
Łukasz Nowak committed
245
  Accept: application/json
246 247 248 249 250
  Content-Type: application/json; charset=utf-8

`Expected Request Body`::

  {
Łukasz Nowak's avatar
Łukasz Nowak committed
251
    "title": "The New Instance Title",
Łukasz Nowak's avatar
Łukasz Nowak committed
252 253
    "status": "started", # one of: started, stopped, updating, error
    "log": "explanation of the status",
254 255 256
    "connection": {
      "custom_connection_parameter_1": "foo",
      "custom_connection_parameter_2": "bar"
Łukasz Nowak's avatar
Łukasz Nowak committed
257
    }
258 259
  }

Łukasz Nowak's avatar
Łukasz Nowak committed
260 261 262
Where `status` is required with `log`, `connection` and `title` are optional and their existence allow to not send `status` and `log`.

Setting different.
Łukasz Nowak's avatar
Łukasz Nowak committed
263

264 265 266
`Expected Response`::

  HTTP/1.1 200 OK
Łukasz Nowak's avatar
Łukasz Nowak committed
267
  Content-Type: application/json; charset=utf-8
268

Łukasz Nowak's avatar
Łukasz Nowak committed
269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284
  {
    'action': ['Action description', 'Action description', ...]
  }

Where `action` describes what happened:

 * 'Renamed' (where title was different)
 * 'Updated status' (where status changed)
 * 'Updated connection information' (where connection changed)

`Additional Responses`::

  HTTP/1.1 204 No Content

When nothing was modified.

285 286 287 288 289 290 291 292 293 294 295 296 297 298
`Error Responses`:

* ``409 Conflict`` The request can not be process because of the current status of the instance (sla changed, instance is under deletion, software release can not be changed, ...).

Computer Methods
****************

Registering a new computer
--------------------------

Add a new computer in the system.

`Request`::

Łukasz Nowak's avatar
Łukasz Nowak committed
299
  POST http://example.com/api/v1/computer HTTP/1.1
Łukasz Nowak's avatar
Łukasz Nowak committed
300
  Accept: application/json
Łukasz Nowak's avatar
Łukasz Nowak committed
301
  Content-Type: application/json; charset=utf-8
302 303 304 305 306 307 308 309 310 311 312

`Expected Request Body`::

  {
    "title": "My unique computer",
  }

`Expected Response`::

  HTTP/1.1 201 Created
  Content-Type: application/json; charset=utf-8
313
  Location: http://maybeother.example.com/some/url/computer_id-0
Łukasz Nowak's avatar
Łukasz Nowak committed
314

315
  {
Łukasz Nowak's avatar
Łukasz Nowak committed
316 317
    "ssl_key": "-----BEGIN PRIVATE KEY-----\nMIIEvgIBADAN...h2VSZRlSN\n-----END PRIVATE KEY-----",
    "ssl_certificate": "-----BEGIN CERTIFICATE-----\nMIIEAzCCAuugAwIBAgICHQI...ulYdXJabLOeCOA=\n-----END CERTIFICATE-----",
318 319 320 321 322 323 324 325 326 327 328 329 330
  }

`Error Responses`:

* ``409 Conflict`` The request can not be process because of the existence of a computer with the same title

Getting computer information
----------------------------

Get the status of a computer

`Request`::

Łukasz Nowak's avatar
Łukasz Nowak committed
331
  GET http://example.com/api/v1/computer/{computer_id} HTTP/1.1
Łukasz Nowak's avatar
Łukasz Nowak committed
332
  Accept: application/json
333 334 335

`Route values`:

Łukasz Nowak's avatar
Łukasz Nowak committed
336
* ``computer_id``: the ID of the computer
337 338 339 340 341 342 343

`No Expected Request Body`

`Expected Response`::

  HTTP/1.1 200 OK
  Content-Type: application/json; charset=utf-8
Łukasz Nowak's avatar
Łukasz Nowak committed
344

345 346 347 348
  {
    "computer_id": "COMP-0",
    "software": [
      {
Łukasz Nowak's avatar
Łukasz Nowak committed
349 350
        "software_release": "http://example.com/example.cfg",
        "status": "install" # one of: install, uninstall
351 352 353 354
      },
    ],
    "partition": [
      {
Łukasz Nowak's avatar
Łukasz Nowak committed
355 356 357 358
        "title": "slapart1",
        "instance_id": "foo",
        "status": "start", # one of: start, stop, destroy
        "software_release": "http://example.com/example.cfg"
359 360
      },
      {
Łukasz Nowak's avatar
Łukasz Nowak committed
361 362 363 364
        "title": "slapart2",
        "instance_id": "bar",
        "status": "stop", # one of: start, stop, destroy
        "software_release": "http://example.com/example.cfg"
365 366 367 368
      },
    ],
  }

Łukasz Nowak's avatar
Łukasz Nowak committed
369 370
Modifying computer
------------------
371

Łukasz Nowak's avatar
Łukasz Nowak committed
372
Modify computer information in the system
373 374 375

`Request`::

Łukasz Nowak's avatar
Łukasz Nowak committed
376
  PUT http://example.com/api/v1/computer/{computer_id} HTTP/1.1
Łukasz Nowak's avatar
Łukasz Nowak committed
377
  Accept: application/json
Łukasz Nowak's avatar
Łukasz Nowak committed
378
  Content-Type: application/json; charset=utf-8
379 380 381

`Route values`:

Łukasz Nowak's avatar
Łukasz Nowak committed
382
* ``computer_id``: the ID of the computer
383 384 385 386 387 388 389 390 391 392 393 394

`Expected Request Body`::

  {
    "partition": [
      {
        "title": "part1",
        "public_ip": "::1",
        "private_ip": "127.0.0.1",
        "tap_interface": "tap2",
      },
    ],
Łukasz Nowak's avatar
Łukasz Nowak committed
395 396
    "software": [
      {
Łukasz Nowak's avatar
Łukasz Nowak committed
397 398 399
        "software_release": "http://example.com/example.cfg",
        "status": "installed", # one of: installed, uninstalled, error
        "log": "Installation log"
Łukasz Nowak's avatar
Łukasz Nowak committed
400 401
      },
    ],
402 403
  }

Łukasz Nowak's avatar
Łukasz Nowak committed
404 405
Where ``partition`` and ``software`` keys are optional, but at least one is required.

406 407 408 409 410 411 412 413
`Expected Response`::

  HTTP/1.1 200 OK
  Content-Type: application/json; charset=utf-8

Supplying new software
----------------------

Łukasz Nowak's avatar
Łukasz Nowak committed
414
Request to supply a new software release on a computer
415 416 417

`Request`::

Łukasz Nowak's avatar
Łukasz Nowak committed
418
  POST http://example.com/api/v1/computer/{computer_id}/supply HTTP/1.1
Łukasz Nowak's avatar
Łukasz Nowak committed
419
  Accept: application/json
Łukasz Nowak's avatar
Łukasz Nowak committed
420
  Content-Type: application/json; charset=utf-8
421 422 423

`Route values`:

Łukasz Nowak's avatar
Łukasz Nowak committed
424
* ``computer_id``: the ID of the computer
425 426 427 428

`Expected Request Body`::

  {
Łukasz Nowak's avatar
Łukasz Nowak committed
429
    "software_release": "http://example.com/example.cfg"
430 431 432 433 434 435 436 437 438 439 440 441 442 443
  }

`Expected Response`::

  HTTP/1.1 200 OK
  Content-Type: application/json; charset=utf-8

Bang computer
-------------

Request update on all partitions

`Request`::

Łukasz Nowak's avatar
Łukasz Nowak committed
444 445
  POST http://example.com/api/v1/computer/{computer_id}/bang HTTP/1.1
  Accept: application/json
Łukasz Nowak's avatar
Łukasz Nowak committed
446
  Content-Type: application/json; charset=utf-8
447 448 449

`Route values`:

Łukasz Nowak's avatar
Łukasz Nowak committed
450
* ``computer_id``: the ID of the computer
451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469

`Expected Request Body`::

  {
    "log": "Explain why this method was called",
  }

`Expected Response`::

  HTTP/1.1 200 OK
  Content-Type: application/json; charset=utf-8

Report usage
------------

Report computer usage

`Request`::

Łukasz Nowak's avatar
Łukasz Nowak committed
470
  POST http://example.com/api/v1/computer/{computer_id}/report HTTP/1.1
Łukasz Nowak's avatar
Łukasz Nowak committed
471
  Accept: application/json
Łukasz Nowak's avatar
Łukasz Nowak committed
472
  Content-Type: application/json; charset=utf-8
473 474 475

`Route values`:

Łukasz Nowak's avatar
Łukasz Nowak committed
476
* ``computer_id``: the ID of the computer
477 478 479 480

`Expected Request Body`::

  {
Łukasz Nowak's avatar
Łukasz Nowak committed
481 482 483 484 485 486 487 488 489 490 491
    "title": "Resource consumptions",
    "start_date": "2011/11/15",
    "stop_date": "2011/11/16",
    "movement": [
      {
        "resource": "CPU Consumption",
        "title": "line 1",
        "reference": "slappart0",
        "quantity": 42.42
      }
    ]
492 493 494 495 496
  }

`Expected Response`::

  HTTP/1.1 200 OK
Łukasz Nowak's avatar
Łukasz Nowak committed
497
  Content-Type: application/json; charset=utf-8