Revision bd4bb8ae

b/docs/plankton-api-guide.rst
1 1
.. _plankton-api-guide:
2 2

  
3
Plankton API Guide
4
==================
3
Cyclades/Image API Guide
4
========================
5 5

  
6 6
Introduction
7 7
------------
8 8

  
9
Plankton is an image service implemented by `GRNET <http://www.grnet.gr>`_ as part of the `Synnefo <http://www.synnefo.org>`_ cloud software, and implements an extension of the `OpenStack Image API <http://docs.openstack.org/api/openstack-image-service/1.1/content/>`_. To take full advantage of the Plankton infrastructure, client software should be aware of the extensions that differentiate Plankton from OOSs `Glance <http://docs.openstack.org/developer/glance/glanceapi.html>`_.
9
The Image Service of `Synnefo <http://www.synnefo.org>`_ is implemented as part
10
of Cyclades. It exposes the OpenStack `Glance API
11
<http://docs.openstack.org/developer/glance/glanceapi.html>`_, with minor
12
changes or additions wherever needed.
10 13

  
11 14
This document's goals are:
12 15

  
13
* Define the Plankton ReST API
14
* Clarify the differences between Plankton and Glance
16
* Define the Cyclades/Image ReST API
17
* Clarify the differences between Cyclades/Image and Glance
15 18

  
16 19
Image ReST API
17 20
--------------
18 21
========================================= ===================================== ====== ======== ======
19
Description                               URI                                   Method Plankton Glance
22
Description                               URI                                   Method Image    Glance
20 23
========================================= ===================================== ====== ======== ======
21 24
`List Available Images <#id2>`_           ``/images``                           GET    ✔        ✔
22 25
`List Available Images in Detail <#id3>`_ ``/images/detail``                    GET    ✔        ✔
......
35 38
Authentication
36 39
--------------
37 40

  
38
**Plankton** depends on Astakos to handle authentication of clients. An authentication token must be obtained from the identity manager which should be send along with each API requests through the *X-Auth-Token* header. Plankton handles the communication with Astakos to verify the token validity and obtain identity credentials.
41
**Image** depends on Astakos to handle authentication of clients. An
42
authentication token must be obtained from the identity manager which should be
43
send along with each API requests through the *X-Auth-Token* header. Image
44
handles the communication with Astakos to verify the token validity and obtain
45
identity credentials.
39 46

  
40
**Glance** handles authentication in a `similar manner <http://docs.openstack.org/developer/glance/glanceapi.html#authentication>`_, with the only difference being the suggested identity manager.
47
**Glance** handles authentication in a `similar manner
48
<http://docs.openstack.org/developer/glance/glanceapi.html#authentication>`_,
49
with the only difference being the suggested identity manager.
41 50

  
42 51

  
43 52
List Available Images
44 53
---------------------
45 54

  
46
This request returns a list of all images accessible by the user. In specific, the list contains images falling at one of the following categories:
55
This request returns a list of all images accessible by the user. In specific,
56
the list contains images falling at one of the following categories:
47 57

  
48 58
* registered by the user
49 59
* shared to  user by others
50 60
* public
51 61

  
52 62
=========== ====== ======== ======
53
URI         Method Plankton Glance
63
URI         Method Image    Glance
54 64
=========== ====== ======== ======
55 65
``/images`` GET    ✔        ✔
56 66
=========== ====== ======== ======
......
58 68
|
59 69

  
60 70
====================== ======================================= ======== ======
61
Request Parameter Name Value                                   Plankton Glance
71
Request Parameter Name Value                                   Image    Glance
62 72
====================== ======================================= ======== ======
63 73
name                   Return images of given name             ✔        ✔
64 74
container_format       Return images of given container format ✔        ✔
......
77 87
**sort_key** values: id, name, status, size, disk_format, container_format, created_at, updated_at
78 88

  
79 89
======== ================ ======== =======
80
sort_dir Description      Plankton Glance
90
sort_dir Description      Image    Glance
81 91
======== ================ ======== =======
82 92
asc      Ascending order  default  default
83 93
desc     Descending order ✔        ✔
......
86 96
|
87 97

  
88 98
====================  ========================= ======== =========
89
Request Header Name   Value                     Plankton Glance
99
Request Header Name   Value                     Image    Glance
90 100
====================  ========================= ======== =========
91 101
X-Auth-Token          User authentication token required required
92 102
====================  ========================= ======== =========
......
106 116
The response data is a list of images in a json format containing the fields presented bellow
107 117

  
108 118
================ ===================== ======== ======
109
Name             Description           Plankton Glance
119
Name             Description           Image    Glance
110 120
================ ===================== ======== ======
111 121
id               A unique image id      ✔        **✘**
112 122
uri              Unique id in URI form **✘**    ✔
......
117 127
size             Image size in bytes   ✔        ✔
118 128
================ ===================== ======== ======
119 129

  
120
Example Plankton response:
130
Example Image response:
121 131

  
122 132
::
123 133

  
......
140 150
List Available Images in Detail
141 151
-------------------------------
142 152

  
143
This request returns the same list of images as in `List Available Images <#id2>`_, but the results are reacher in metadata.
153
This request returns the same list of images as in `List Available Images
154
<#id2>`_, but the results are reacher in metadata.
144 155

  
145 156
================== ====== ======== ======
146
URI                Method Plankton Glance
157
URI                Method Image    Glance
147 158
================== ====== ======== ======
148 159
``/images/detail`` GET    ✔        ✔
149 160
================== ====== ======== ======
150 161

  
151
**Request parameters** and **headers** as well as **response headers** and **error codes** are exactly the same as in `List Available Images <#id2>`_, both syntactically and semantically.
162
**Request parameters** and **headers** as well as **response headers** and
163
**error codes** are exactly the same as in `List Available Images <#id2>`_,
164
both syntactically and semantically.
152 165

  
153 166

  
154
The response data is a list of images in json format containing the fields presented bellow
167
The response data is a list of images in json format containing the fields
168
presented bellow
155 169

  
156 170
================ ===================== ======== ======
157
Name             Description           Plankton Glance
171
Name             Description           Image    Glance
158 172
================ ===================== ======== ======
159 173
id               A unique image id     ✔        **✘**
160 174
uri              Unique id in URI form **✘**    ✔
......
177 191

  
178 192
|
179 193

  
180
Example Plankton response::
194
Example Image response::
181 195

  
182 196
    [{
183 197
        "status": "available", 
......
216 230
Add or update an image
217 231
----------------------
218 232

  
219
According to the Synnefo approach, this request performs two functionalities:
233
According to the Synnefo approach, this request performs two operations:
220 234

  
221
* registers a new image to Plankton
235
* registers a new image to Cyclades/Image 
222 236
* commits metadata for the new image
223 237
* update the metadata of an existing image
224 238

  
225
The physical image file must be uploaded on a `Pithos+ <pithos.html>`_ server, at a space accessible by the user. The Pithos+ location of the physical file acts as a key for the image (image ids and image locations are uniquely coupled).
239
The physical image file must be uploaded on a `Pithos+ <pithos.html>`_ server,
240
at a space accessible by the user. The Pithos+ location of the physical file
241
acts as a key for the image (image ids and image locations are uniquely
242
coupled).
226 243

  
227
According to the OpenStack approach, this request performs the first two functionalities by uploading the the image data and metadata to Glance. In Glance, the update mechanism is not implemented with this specific request.
244
According to the OpenStack approach, this request performs the first two
245
functionalities by uploading the the image data and metadata to Glance. In
246
Glance, the update mechanism is not implemented with this specific request.
228 247

  
229 248
=========== ====== ======== ======
230
URI         Method Plankton Glance
249
URI         Method Image    Glance
231 250
=========== ====== ======== ======
232 251
``/images`` POST   ✔        ✔
233 252
=========== ====== ======== ======
......
235 254
|
236 255

  
237 256
============================= ========================= ========  ========
238
Request Header Name           Value                     Plankton  Glance
257
Request Header Name           Value                     Image     Glance
239 258
============================= ========================= ========  ========
240 259
X-Auth-Token                  User authentication token required  required
241 260
X-Image-Meta-Name             Img name                  required  required
......
296 315
The following is used when the response code is 200:
297 316

  
298 317
============================= ===================== ======== ======
299
Response Header               Description           Plankton Glance
318
Response Header               Description           Image    Glance
300 319
============================= ===================== ======== ======
301 320
X-Image-Meta-Id               Unique img id         ✔        **✘**
302 321
X-Image-Meta-Name             Img name              ✔        **✘**
......
316 335
Update an Image
317 336
---------------
318 337

  
319
In Plankton, an image can be updated either by re-registering with different metadata, or by using the request described in the present subsection.
338
In Cyclades/Image, an image can be updated either by re-registering with
339
different metadata, or by using the request described in the present
340
subsection.
320 341

  
321
In Glance, an update is implemented as a *PUT* request on ``/images`` URI. The method described bellow is not part of the Glance API.
342
In Glance, an update is implemented as a *PUT* request on ``/images`` URI. The
343
method described bellow is not part of the Glance API.
322 344

  
323 345
====================== ====== ======== ======
324
URI                    Method Plankton Glance
346
URI                    Method Image    Glance
325 347
====================== ====== ======== ======
326 348
``/images``            PUT    **✘**    ✔
327 349
``/images/<image-id>`` PUT    ✔        **✘**
328 350
====================== ====== ======== ======
329 351

  
330
The following refers only to the Plankton implementation.
352
The following refers only to the Cyclades/Image implementation.
331 353

  
332 354
**image-id** is explained at :ref:`id-ref`
333 355

  
......
354 376

  
355 377
**X-Image-Meta-Is-Public** values are true or false (case insensitive)
356 378

  
357
**X-Image-Meta-Property-*** is used as a prefix to update image property values, or set some extra proeperties. If a registered image already contains some custom properties that are not addressed in the update request, these properties will remain untouched. For example::
379
**X-Image-Meta-Property-*** is used as a prefix to update image property
380
values, or set some extra proeperties. If a registered image already contains
381
some custom properties that are not addressed in the update request, these
382
properties will remain untouched. For example::
358 383

  
359 384
    X-Image-Meta-Property-OS: Debian Linux
360 385
    X-Image-Meta-Property-Users: Root
......
396 421
X-Image-Meta-Property-*       Custom img properties
397 422
============================= =====================
398 423

  
399
.. hint:: In Plankton, use POST to completely reset all image properties and metadata, but use PUT to update a few values without affecting the rest.
424
.. hint:: In Cyclades/Image, use POST to completely reset all image properties
425
          and metadata, but use PUT to update a few values without affecting the
426
          rest.
400 427

  
401 428
Retrieve Image Metadata
402 429
-----------------------
403 430

  
404
This request returns the metadata of an image. Images are identified by their unique image id.
431
This request returns the metadata of an image. Images are identified by their
432
unique image id.
405 433

  
406
In a typical scenario, client applications would query the server to `List Available Images <#id2>`_ for them and then choose one of the image ids returned.
434
In a typical scenario, client applications would query the server to `List
435
Available Images <#id2>`_ for them and then choose one of the image ids
436
returned.
407 437

  
408 438
====================== ====== ======== ======
409
URI                    Method Plankton Glance
439
URI                    Method Image    Glance
410 440
====================== ====== ======== ======
411 441
``/images/<image-id>`` HEAD   ✔        ✔
412 442
====================== ====== ======== ======
......
416 446
|
417 447

  
418 448
====================  ========================= ======== =========
419
Request Header Name   Value                     Plankton Glance
449
Request Header Name   Value                     Image    Glance
420 450
====================  ========================= ======== =========
421 451
X-Auth-Token          User authentication token required  required
422 452
====================  ========================= ======== =========
......
436 466
|
437 467

  
438 468
============================= ===================== ======== ======
439
Response Header               Description           Plankton Glance
469
Response Header               Description           Image    Glance
440 470
============================= ===================== ======== ======
441 471
X-Image-Meta-Id               Unique img id         ✔        ✔
442 472
X-Image-Meta-Location         Pithos+ file location ✔        **✘**
......
462 492
X-Image-Meta-Property-*       Custom img properties ✔        ✔
463 493
============================= ===================== ======== ======
464 494

  
465
**X-Image-Created-At** is the (immutable) date of initial registration, while **X-Image-Meta-Updated-At** indicates the date of last modification of the image (if any).
495
**X-Image-Created-At** is the (immutable) date of initial registration, while
496
**X-Image-Meta-Updated-At** indicates the date of last modification of the
497
image (if any).
466 498

  
467 499
**X-Image-Meta-Store** values are listed at :ref:`store-ref`
468 500

  
469 501
**X-Image-Meta-Disk-Format** values are listed at :ref:`disk-format-ref`
470 502

  
471
**X-Image-Meta-Container-Format** values are listed at :ref:`container-format-ref`
503
**X-Image-Meta-Container-Format** values are listed at
504
:ref:`container-format-ref`
472 505

  
473 506
**X-Image-Meta-Is-Public** values are true or false (case insensitive)
474 507

  
475
**X-Image-Meta-Property-*** is used as a prefix to set custom, free-form key:value properties on an image, e.g.::
508
**X-Image-Meta-Property-*** is used as a prefix to set custom, free-form
509
key:value properties on an image, e.g.::
476 510

  
477 511
    X-Image-Meta-Property-OS: Debian Linux
478 512
    X-Image-Meta-Property-Users: Root
479 513

  
480
Example Plankton Headers response::
514
Example Cyclades/Image Headers response::
481 515

  
482 516
    x-image-meta-id: 940509eb-eb4f-496c-8443-22ffd24912e9
483 517
    x-image-meta-location: pithos://25cced7-bd53-4145-91ee-cf4737e9fb2/images/some-image.diskdump
......
505 539
Retrieve Raw Image Data
506 540
-----------------------
507 541

  
508
In **Plankton**, the raw image data is stored at a `Pithos <pithos.html>`_ server and it can be downloaded from the Pithos web UI, with a `client <https://okeanos.grnet.gr/services/pithos/>`_ or with `kamaki <http://www.synnefo.org/docs/kamaki/latest/index.html>`_. The location of an image file can be retrieved from the *X-Image-Meta-Location* header field (see `Retrieve Image Meta <#id10>`_)
542
In **Image**, the raw image data is stored at a `Pithos <pithos.html>`_
543
server and it can be downloaded from the Pithos web UI, with a `client
544
<https://okeanos.grnet.gr/services/pithos/>`_ or with `kamaki
545
<http://www.synnefo.org/docs/kamaki/latest/index.html>`_. The location of an
546
image file can be retrieved from the *X-Image-Meta-Location* header field (see
547
`Retrieve Image Meta <#id10>`_)
509 548

  
510
In **Glance**, the raw image can be downloaded with a GET request on ``/images/<image-id>``.
549
In **Glance**, the raw image can be downloaded with a GET request on
550
``/images/<image-id>``.
511 551

  
512 552
List Image Memberships
513 553
----------------------
514 554

  
515
This request returns the list of users who can access an image. Plankton returns an empty list if the image is publicly accessible.
555
This request returns the list of users who can access an image. Cyclades/Image
556
returns an empty list if the image is publicly accessible.
516 557

  
517 558
============================== ====== ======== ======
518
URI                            Method Plankton Glance
559
URI                            Method Image    Glance
519 560
============================== ====== ======== ======
520 561
``/images/<image-id>/members`` GET    ✔        ✔
521 562
============================== ====== ======== ======
......
525 566
|
526 567

  
527 568
====================  ========================= ======== =========
528
Request Header Name   Value                     Plankton Glance
569
Request Header Name   Value                     Image    Glance
529 570
====================  ========================= ======== =========
530 571
X-Auth-Token          User authentication token required  required
531 572
====================  ========================= ======== =========
......
547 588
The response data is a list of users (members) who can access this image
548 589

  
549 590
================ ===================== ======== ======
550
Name             Description           Plankton Glance
591
Name             Description           Image    Glance
551 592
================ ===================== ======== ======
552 593
member_id        uuid (user id)        ✔        ✔
553 594
can_share        Member can share img  false    ✔
554 595
================ ===================== ======== ======
555 596

  
556
**can_share** in Plankton is always false and is returned for compatibility reasons.
597
**can_share** in Cyclades/Image is always false and is returned for
598
compatibility reasons.
557 599

  
558
Example Plankton response::
600
Example Cyclades/Image response::
559 601

  
560 602
    {'members': [
561 603
        {'member_id': 'th15-4-u53r-1d-fr0m-p1th05',
......
566 608
Replace a Membership List
567 609
-------------------------
568 610

  
569
This request replaces the list of users who can access a registered image. The term "replace" means that the old permission list of the image is abandoned (old permission settings are lost).
611
This request replaces the list of users who can access a registered image. The
612
term "replace" means that the old permission list of the image is abandoned
613
(old permission settings are lost).
570 614

  
571 615
============================== ====== ======== ======
572
URI                            Method Plankton Glance
616
URI                            Method Image    Glance
573 617
============================== ====== ======== ======
574 618
``/images/<image-id>/members`` PUT    ✔        ✔
575 619
============================== ====== ======== ======
......
579 623
|
580 624

  
581 625
====================  ========================= ======== =========
582
Request Header Name   Value                     Plankton Glance
626
Request Header Name   Value                     Image    Glance
583 627
====================  ========================= ======== =========
584 628
X-Auth-Token          User authentication token required  required
585 629
====================  ========================= ======== =========
586 630

  
587 631
|
588 632

  
589
Request data should be json-formated. It must consist of a *memberships* field which is a list of members with the following fields:
633
Request data should be json-formated. It must consist of a *memberships* field
634
which is a list of members with the following fields:
590 635

  
591 636
================ ===================== ======== ======
592
Name             Description           Plankton Glance
637
Name             Description           Image    Glance
593 638
================ ===================== ======== ======
594 639
member_id        uuid (user id)        ✔        ✔
595 640
can_share        Member can share img  ignored  ✔
596 641
================ ===================== ======== ======
597 642

  
598
**can_share** is optional and ignored in Plankton.
643
**can_share** is optional and ignored in Cyclades/Image.
599 644

  
600 645
A request data example::
601 646

  
......
622 667
Add a Member to an Image
623 668
------------------------
624 669

  
625
This request appends a user id to the list of users who can access a registered image.
670
This request appends a user id to the list of users who can access a registered
671
image.
626 672

  
627 673
===================================== ====== ======== ======
628
URI                                   Method Plankton Glance
674
URI                                   Method Image    Glance
629 675
===================================== ====== ======== ======
630 676
``/images/<image-id>/members/<uuid>`` PUT    ✔        ✔
631 677
===================================== ====== ======== ======
632 678

  
633 679
**image-id** is explained at :ref:`id-ref`
634 680

  
635
**uuid** is the unique user id of the user (see `Astakos API <astakos-api-guide.html>`_ on how to handle it)
681
**uuid** is the unique user id of the user (see `Astakos API
682
<astakos-api-guide.html>`_ on how to handle it)
636 683

  
637 684
|
638 685

  
639 686
====================  ========================= ======== =========
640
Request Header Name   Value                     Plankton Glance
687
Request Header Name   Value                     Image    Glance
641 688
====================  ========================= ======== =========
642 689
X-Auth-Token          User authentication token required  required
643 690
====================  ========================= ======== =========
......
657 704
Remove a Member from an Image
658 705
-----------------------------
659 706

  
660
This request ensures that, after a successful call, the user with the given uuid will not have access to that image.
707
This request ensures that, after a successful call, the user with the given
708
uuid will not have access to that image.
661 709

  
662 710
===================================== ====== ======== ======
663
URI                                   Method Plankton Glance
711
URI                                   Method Image    Glance
664 712
===================================== ====== ======== ======
665 713
``/images/<image-id>/members/<uuid>`` DELETE ✔        ✔
666 714
===================================== ====== ======== ======
667 715

  
668 716
**image-id** is explained at :ref:`id-ref`
669 717

  
670
**uuid** is the unique user id of the user (see `Astakos API <astakos-api-guide.html>`_ on how to handle it)
718
**uuid** is the unique user id of the user (see `Astakos API
719
<astakos-api-guide.html>`_ on how to handle it)
671 720

  
672 721
|
673 722

  
674 723
====================  ========================= ======== =========
675
Request Header Name   Value                     Plankton Glance
724
Request Header Name   Value                     Image    Glance
676 725
====================  ========================= ======== =========
677 726
X-Auth-Token          User authentication token required  required
678 727
====================  ========================= ======== =========
......
695 744
This request returns a list of the images that are shared with a given user.
696 745

  
697 746
========================= ====== ======== ======
698
URI                       Method Plankton Glance
747
URI                       Method Image    Glance
699 748
========================= ====== ======== ======
700 749
``/shared-images/<uuid>`` DELETE ✔        ✔
701 750
========================= ====== ======== ======
......
705 754
|
706 755

  
707 756
====================  ========================= ======== =========
708
Request Header Name   Value                     Plankton Glance
757
Request Header Name   Value                     Image    Glance
709 758
====================  ========================= ======== =========
710 759
X-Auth-Token          User authentication token required  required
711 760
====================  ========================= ======== =========
......
722 771
500 (Internal Server Error) The request cannot be completed because of an internal error
723 772
=========================== =====================
724 773

  
725
In case of a 200 response, the response data is json-formated list of images that are shared with given user
774
In case of a 200 response, the response data is json-formated list of images
775
that are shared with given user
726 776

  
727 777
================ ===================== ======== ======
728
Name             Description           Plankton Glance
778
Name             Description           Image    Glance
729 779
================ ===================== ======== ======
730 780
image_id         The Image ID          ✔        ✔
731 781
can_share        Member can share img  false    ✔
732 782
================ ===================== ======== ======
733 783

  
734
**can_share** in Plankton is always false and is returned for compatibility reasons.
784
**can_share** in Cyclades/Image is always false and is returned for
785
compatibility reasons.
735 786

  
736
Example Plankton response::
787
Example Cyclades/Image response::
737 788

  
738 789
    {'shared_images': [
739 790
        {'image_id': 'th3-r3qu3573d-1m4g3-1d',
......
751 802
Image ID
752 803
^^^^^^^^
753 804

  
754
The image id is a unique identifier for an image stored in Plankton or Glance.
805
The image id is a unique identifier for an image stored in Cyclades/Image or
806
Glance.
755 807

  
756 808
======================= ========  ======
757
Image-Id                Plankton  Glance
809
Image-Id                Image     Glance
758 810
======================= ========  ======
759 811
Automatically generated ✔         **✘**
760 812
Can be provided by user **✘**     ✔
......
769 821

  
770 822
    pithos://<unique-user-id>/<container>/<object-path>
771 823

  
772
The terms unique-user-id (uuid), container and object-path are used as defined in `Pithos <pithos.html>`_ context.
824
The terms unique-user-id (uuid), container and object-path are used as defined
825
in `Pithos <pithos.html>`_ context.
773 826

  
774 827
.. _container-format-ref:
775 828

  
......
777 830
^^^^^^^^^^^^^^^^
778 831

  
779 832
===== ================================= ======== ======
780
Value Description                       Plankton Glance
833
Value Description                       Image    Glance
781 834
===== ================================= ======== ======
782 835
aki   Amazon kernel image               ✔        ✔
783 836
ari   Amazon ramdisk image              ✔        ✔
......
792 845
^^^^^^^^^^^
793 846

  
794 847
======== ================================= ======== ======
795
Value    Description                       Plankton Glance
848
Value    Description                       Image    Glance
796 849
======== ================================= ======== ======
797 850
diskdump Any disk image dump               default  **✘**
798 851
extdump  EXT3 image                        ✔        **✘**
......
814 867
^^^^^^^^^^^
815 868

  
816 869
======================= ========  ======
817
X-Image-Meta-Store      Plankton  Glance
870
X-Image-Meta-Store      Image     Glance
818 871
======================= ========  ======
819 872
pithos                  ✔         **✘**
820 873
file                    **✘**     ✔
821 874
s3                      **✘**     ✔
822 875
swift                   **✘**     ✔
823
======================= ========  ======
876
======================= ========  ======

Also available in: Unified diff