======== REST API ======== Development of the RESTful API for GWM started as a Google Summer of Code 2011 project. The developer, Bojan Suzic, can be reached at bojan.suzic@gmail.com. The mentor for this project is Peter Krenesky. The current version of the page describes its status as of ~end August 2011. Currently it supports a fair amount of the underlying functionality. Additionally, this page is intented as a development resource and documentation source for the project. The project code can be reached at https://github.com/bsu/GWM2. The additional code (changes in other related modules) can be found at the following locations: * https://github.com/bsu/django_obj_perm * https://github.com/bsu/django_obj_log. Users and developers are encouraged to try this addon and send their suggestions/bug reports/improvements either directly to the author, using the `GWM mailing list `_ or `issue tracker `_. Please put the line ****[REST-API]**** in the subject if you are sending email message. REST API for GWM can now be considered as a beta software. For the further development the following is proposed: Roadmap: * completion of unit tests * relocate parts of endpoints which may contain long answers - that variables should be accessed separately (such as object logs) * further refinement of the code and documentation * work on further integration (like cloud driver) The **users/developers/visitors are advised to test** the code and **submit the comments/notices/wishes**. Comments can be submitted either directly to the author, here on this wiki or using the `Redmine ticket `_ The version containing significant changes to this version may be expected in **November 2011**. About this documentation ------------------------ This documentation covers basic functionality of the REST API. It consists of the subsections, referring to particular endpoints forming the API. As an endpoints referred are application resources exposed as URIs through appropriate hierarchy. Currently, the system exposes the following resources as REST API endpoints: **User**, **Group**, **Virtual Machine**, **Cluster**, **Node**, **Job**. These are accessible in the form of CRUD operations using HTTP protocol. By default, each API endpoint returns a list of resources. For example:: /api/vm/ would return a list of Virtual Machines in the system, while the particular VM resource is accessed through:: /api/vm/1/ where 1 represents identifier of particular Virtual Machine. This way only that particular resource is returned. Each resource contains fields related to particular instance in the system. The field types and their properties are described further in the documentation, as a part of related subsections. For each endpoint described is basic scheme of its resource representation. The scheme includes name, type and description of the particular fields, Additional properties described are possibility for the field to be modified and whether the field returned may be excluded from the representation e.g. nullable. The later one might be useful for clients to prevent unexpected behavior. While **type** field represents basic data types, it should be noted that **related** type points to other resource in the system. For example:: ... ... /api/vm/5 ... says that particular cluster resource includes virtualmachine resource, described by related URI. Therefore, if necessary, the complete resource referred at that point may be obtained through provided URI. This documentation trends to provide as much as complete list of resources and their schematic description. However, due to the level of deepness and limitations of the current wiki system, in some cases this representation is simplified and explained in words rather than in tabular form. It should be noted that all these descriptions are already included in the system. Using:: http://somesite.com/api/?format=xml user is able to get the list of resources exposed, while with the help of:: http://somesite.com/api/resource/schema/?format=xml the system returns detailed schema of resource representation and field properties in XML format. Therefore, the user is always able to take a look and check detailed description about a resource, if the one provided here in documentation is not detailed and clear enough. Design principles ----------------- This API aims to expose the resources of Ganeti Web Manager, making suitable for integration into other systems or just performing of simple operations on resources. It does not aim to expose all resources and functions contained in the software, but only the set deemed necessary in order to support its business functions. Currently, it means that the most of the functionality present in the web interface is available for usage and manipulation also using this REST API. Installation ------------ The most of the code of this addon comes under **/api** directory of GWM distribution. Other code changes are done in some of views and dependent modules (like **django_object_log** and **django_object_permissions**). Its inclusion in the GWM is done in **/urls.py** via:: urlpatterns = patterns('', ... (r'^', include('api.urls')), ... The prerequisite for running RESTful API over Ganeti Web Manager is to have **django-tastypie** installed. The latest active version/commit of **tastypie** should be used in order to support **ApiKeys** based authentication. That means, as of time of writing this documentation, that **tastypie** should be installed manually. Additionally, the following line in **tastypie/authentication.py**:: username = request.GET.get('username') or request.POST.get('username') should be changed to:: username = request.GET.get('username') or request.POST.get('username') or request.GET.get('user') or request.POST.get('user') This is the known issue with **tastypie** already reported in its bug system. If not changed, the part **username** in **/api/user/?api_key=xxx&username=xxx** will produce error message during browsing the main user endpoint. This change makes **tastypie** to accept **user** for authentication instead of **username**. Later produces collision with the field of the same name under **User** model class. The next change related to the installation of the module is inclusion of **'tastypie'** in **INSTALLED_APPS** of **settings.py**. This will produce necessary tables during installation/migration. Development ----------- The code is prepared as a part of GSoC activities, and therefore by person not being a part of narrowed GWM development team before. As a such, the main principle to be followed is to try not to interfere too much with existing code. It implies further that the resulting code should be considered as an simple to install add-on. The core business logic of the GWM have not been changed or altered. The most changes done on GWM code are of technical nature, trying to make functions/views accessible to REST backend interface additionally. The code has been committed to separate repository. I tried mostly to perform smaller commits in size, in order to make the code and changes easily readable and trackable. The framework used to introduce RESTful interface is **django-tastypie**. It has been selected after initial research and testing of several popular Python/Django/REST frameworks. The system supports both XML and JSON as input/output serializations. Authentication and Authorization ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The authentication is done using **API keys**. For each user the appropriate API key is generated automatically. The key can be renewed/recreated using **POST** request and appropriate action inside API. The access to the system looks like in the following example:: http://localhost:8000/api/?format=xml&api_key=381a5987a611fb1f8c68ffad49d2cd2b9f92db71&user=test .. Note:: **username** initially supported by **tastypie** has been replaced with **user** in the example query above. The changes and reasons are described in the installation section of this document. Authorization is completely dependent on Django's authorization system. The existing views from the GWM have been used to expose the most of resources available. Those views are already integrated in Django's authorization system. Therefore, this API should not contain critical security flaws or problems and should be easier to maintenance. REST API endpoints ------------------ /api/user ~~~~~~~~~ This endpoint exposes data and operations related to the user management. The following table provides the descriptions of the fields: .. raw:: html
Name Type ReadOnly Nullable Description
username string Required. 30 characters or fewer. Letters, numbers and @/./+/-/_ characters
ssh_keys list x SSH keys for user's account. The list may be composed of several objects.
first_name string Unicode string data. Ex: "Hello World"
last_name string Unicode string data. Ex: "Hello World"
actions_on_user list x x Returns the actions done on the user. The list is composed of objects, containing elements as described here.
groups related x x Returns the groups the user is member of
api_key string x x Returns the api key of the user
used_resources list x x Returns the resources used by the objects user has access to in the form of the list.
is_active boolean Designates whether this user should be treated as active. Unselect this instead of deleting accounts.
id string x Unicode string data. Ex: "Hello World"
is_superuser boolean Designates that this user has all permissions without explicitly assigning them.
is_staff boolean Designates whether the user can log into this admin site.
last_login datetime A date & time as a string. Ex: "2010-11-10T03:07:43"
date_joined datetime A date & time as a string. Ex: "2010-11-10T03:07:43"
user_actions list x Returns the actions done by the user. The list is composed of objects, containing elements as described here.
permissions list x x Returns the status of users permissions on different families of objects
password string Returns hashed password
email string Unicode string data. Ex: "Hello World"
resource_uri string x Unicode string data. Ex: "Hello World"
Explanations for particular list elements ''''''''''''''''''''''''''''''''''''''''' **Container: ssh_keys** The elements of the list are denoted as **value** nodes, containing paricular ssh key for the user in the form of **string hash** Example:: 1 ssh-rsa A398kuwNzaC1yc2EAAAADAQABAAABAQDI2oqyrleSvAg4CV5A/4ZZ2fTEFAYU1W2i8373zspaJCSO0eHIl+v4fGeIzH7CFokbM98ip2mwe7KtFk2VoO1 /E9ucXR4xcxo77sxGSGH8hiS89aUcHmPKyRYlYj5TwqkZopxYTFmeUhkhP9e5YrlTRXMdhMsIXqXAKRujjySycQ45QLqdYOHbfohU0aKtDN01bYFOQ7/y/9wepXczlXD7rTIhT6 /aq2vvOoyiGo9vaiIfqbtLjqkjwecDGykesw1c9d07vH53myiLLLkAGGk4KudKSWV6ZxK0ap3/olzzJ3HZpk5MAel5ELX6XuT8VmA3H3Yl5N//DrBUmKciMIaRx xxx@gmail.com 2 ssh-rsa 7398kuwNzaC1yc2EAAAADAQABAAABAQDI2oqyrleSvAg4CVjskajslajwFAYU1W2i8373zspaJCSO0eHIl+v4fGeIzH7CFokbM98ip2mwe7KtFk2VoO1 /E9ucXR4xcxo77sxGSGH8hiS89aUcHmPKyRYlYj5TwqkZopxYTFmeUhkhP9e5YrlTRXMdhMsIXqXAKRujjySycQ45QLqdYOHbfohU0aKtDN01bYFOQ7/y/9wepXczlXD7rTIhT6 /aq2vvOoyiGo9vaiIfqbtLjqkjwecDGykesw1c9d07vH53myiLLLkAGGk4KudKSWV6ZxK0ap3/olzzJ3HZpk5MAel5ELX6XuT8VmA3H3Yl5N//DrBUmKciMIYYY yyy@gmail.com **Containers: user_actions and actions_on_users** This is the list of **objects**, each object consisting of nullable fields denoted as **obj1, obj2, user, action_name**. The both containers share the representation. The difference between these is the fact that first describes actions performed by user, while the second one describes actions performed on user (by administrator, for instance). The both containers provide read only information. .. raw:: html
Name Type Description
obj1, obj2 related Describe action object
timestamp timestamp> Date and time of action execution
user related User performing the action
action_name string Describes action name using internal descriptions
Example:: /api/vm/3/ 2011-07-31T15:23:45.533479 /api/job/68/ /api/user/2/ VM_REBOOT /api/vm/3/ 2011-07-31T17:04:02.333061 /api/user/2/ EDIT **Container used_resources** This list consists of **object** elements, each containing **resource**, **object** and **type**. The field **object** represents related resource for which the system resources consumption is given. The **type** is **string** describing the object type using internal descriptions (like **VirtualMachine** for virtual machine). The **resource** contains subfields **virtual_cpus**, **disk** and **ram**, each of type **integer** and representing actual consumption of the particular system resource in system's default dimension (e.g. MBs for RAM consumption). Example:: 0 0 0 /api/vm/3/< type>VirtualMachine 0 0 0 /api/vm/11/ VirtualMachine **Container permissions** **Permissions** contains elements describing particular resource type, each further containing a list of resources. The primary **elements** are described as **Cluster**, **VirtualMachine**, **Group**. Their list member main nodes are described as **object**, containing **object** reference (related resource) for which the permissions are set, and the **permissions** list containing list of **values** as strings, describing permission type in internal format (like **create_vm**). Example:: /api/vm/3/ admin power tags /api/vm/11/ admin Manipulation and operations using POST/PUT/DELETE methods ''''''''''''''''''''''''''''''''''''''''''''''''''''''''' The fields marked as non-readonly (table above) can be subject of further manipulation and operations. **The same applies to the rest of the document - those fields can be automatically updated or deleted by performing analog request.** In order to maintain consistency with REST approach, the **PUT** method is used on currently available resources with purpose to change or update them. On another side, **POST** method is used either to generate new resources, or to perform predefined actions on currently existing resources. The following example demonstrates changing of users lastname and status in system (disabling its account). Request URI:: PUT /api/user/1/?api_key=xxxxx&username=yyyyy Request header:: Content-Type: application/json Accept: application/json Request payload:: {"last_name":"New LastName", "is_active":false} Server response:: HTTP/1.1 204 NO CONTENT Date: Sat, 06 Aug 2011 11:18:25 GMT Server: WSGIServer/0.1 Python/2.7.1+ Vary: Accept-Language, Cookie Content-Length: 0 Content-Type: text/html; charset=utf-8 Content-Language: en The next example demonstrates generating of new Api key for the user: Request URI:: POST /api/user/2/?api_key=xxxxx&username=yyyyy Request header:: Content-Type: application/json Accept: application/xml Request payload:: {"action":"generate_api_key"} Server response:: HTTP/1.1 201 CREATED Date: Sat, 06 Aug 2011 11:21:56 GMT Server: WSGIServer/0.1 Python/2.7.1+ Vary: Accept-Language, Cookie Content-Type: text/html; charset=utf-8 Content-Language: en Response body:: de0a57db0ce43d0f3c52f83eaf33387750ac9953 2 For the API Key manipulation under **/api/user/** endpoint implemented are two POST actions: **generate_api_key**, as demonstrated in the example above, and **clean_api_key**. The former generates a new API key for the user and returns it in the response, while the later one cleans user's API key. This way its access to the system using REST API is disabled, but the standard access using web interface is untouch. Additionally, two POST actions are implemented for user-group membership manipulation. .. raw:: html
Action Payload Description Example
add_to_group group Add the user to the group
{'action':'add_to_group', 'group':'/api/group/1/'}
remove_from_group group Remove the user from the group
{'action':'remove_from_group', 'group':'/api/group/1/'}
generate_api_key - Generate API key for the user
{'action':'generate_api_key'}
clean_api_key - Clean API key for the user
{'action':'clean_api_key'}
/api/group ~~~~~~~~~~ This endpoint exposes data and operations related to the group management. The following table summarizes supported fields. .. raw:: html
Name Type ReadOnly Nullable Description
actions_on_group list x Returns the actions done on the group. The list is composed of objects, containing elements as described here.
users related x Returns a list of the users belonging to the group.
used_resources list x x Returns the resources used by the objects the group has access to in the form of the list.
permissions list x x Returns the status of users permissions on different families of objects
resource_uri string x Unicode string data. Ex: "Hello World"
id string x Unicode string data. Ex: "Hello World"
name string Unicode string data. Ex: "Hello World"
**Container: actions_on_group** This is the list of **objects**, each object consisting of nullable fields denoted as **obj1, obj2, user, action_name**. This container describes actions performed on the group (by administrator, for instance) in the form of read-only information. Please note that inclusion od **obj1** and **obj2** depends on the action type, e.g. one of these may be omitted. .. raw:: html
Name Type Description
obj1, obj2 related Describe action object
timestamp timestamp> Date and time of action execution
user related User performing the action
action_name string Describes action name using internal descriptions
Example:: /api/group/1/ 2011-07-29T08:28:24.566903 /api/user/1/ CREATE /api/cluster/1/ 2011-07-29T08:28:59.854791 /api/group/1/ /api/user/1/ ADD_USER **Field: users** This simple field contains a list of users belonging to the group. The type of the resource is **related**, which means that it points to the URI representing the resource. Example:: /api/user/2/ /api/user/3/ **Container used_resources** The syntax used here is the same as used in the User resource. For more information and example, please refer to the user section of this document. **Container permissions** The syntax used here is the same as used in the User resource. For more information and example, please refer to the user section of this document. Manipulation actions '''''''''''''''''''' .. raw:: html
Action Payload Description Example
add_user user Add the user to the group
{'action':'add_user', 'user':'/api/user/2/'}
remove_user user Remove the user from the group
{'action':'remove_user', 'user':'/api/user/2/'}
/api/vm ~~~~~~~ This endpoint exposes methods for VirtualMachine inspection and manipulation. **Important**: as the attributes exposing VM object are related to many other objects and many calls are done on different views, here the somewhat different approach to attribute exposure is used. At the main point **/api/vm/**, which provides a list of virtual machines, only the basic attributes of VM are provided. However, when the particular object is called, sad **/api/vm/3/**, the system returns additional set of its attributes. This is due to need to perform additional calls which introduce network latency. Performing all those calls at once for all virtual machines could produce unnecessary overhead. Fields exposed (main endpoint): .. raw:: html
Name Type ReadOnly Nullable Description
pending_delete boolean Boolean data. Ex: True
ram integer Integer data. Ex: 2673
cluster related x A single related resource. Can be either a URI or set of nested resource data.
last_job related x A single related resource. Can be either a URI or set of nested resource data.
virtual_cpus integer Integer data. Ex: 2673
id string Unicode string data. Ex: "Hello World"
hostname string Unicode string data. Ex: "Hello World"
status string Unicode string data. Ex: "Hello World"
secondary_node related x A single related resource. Can be either a URI or set of nested resource data.
operating_system string Unicode string data. Ex: "Hello World"
disk_size integer Integer data. Ex: 2673
primary_node related x A single related resource. Can be either a URI or set of nested resource data.
resource_uri string Unicode string data. Ex: "Hello World"
Fields exposed (additionally, particular object): .. raw:: html
Name Type ReadOnly Nullable Description
cluster_admin Boolean x Determines if the current user has admin permissions over cluster.
power Boolean x Determines if the current user has admin permissions to power vm.
modify Boolean x Determines if the current user has admin permissions to modify vm.
job Boolean x x Points to the jobs related to the vm, if any.
actions_on_vm list x x Returns the actions done on the user. The list is composed of objects, containing elements as described here.
permissions list x Lists the objects (users and groups) having permissions over vm. Contains sublists users and groups, each having objects pointing to related user/group.
admin Boolean x Determines if the current user has admin permissions over vm.
remove Boolean x Determines if the current user has permissions to remove vm.
migrate Boolean x Determines if the current user has admin permissions to migrate.
**Containers: actions_on_vm and permissions** The format and members of those lists are similar to previous mentioned fields, e.g. in **cluster** endpoint. For detailed description, please refer to those. The field **actions_on_vm** contains object(s) taking part in action, user initiated the action, timestamp and the internal description of the action in form of the string. The field **permissions>** lists users and groups (as related fields) which have any form of permissions on virtual machine. **Operations supported** Operations on VM are accomplished in form of action. Action is initiated using POST request. Example:: POST /api/vm/7 {"action":"shutdown"} In this example, user initiates @POST@ request on Virtual Machine described with @id=7@. The action type is described in field @action@ in request header. After the action is initiated, server sends back response. Example: Header:: HTTP/1.1 200 OK Date: Wed, 27 Jul 2011 18:39:31 GMT Server: WSGIServer/0.1 Python/2.7.1+ Vary: Accept-Language, Cookie Content-Type: application/json Content-Language: en Body:: {"end_ts": null, "id": "138722", "oplog": [[]], "opresult": [null], "ops": [{"OP_ID": "OP_INSTANCE_SHUTDOWN", "debug_level": 0, "dry_run": false, "ignore_offline_nodes": false, "instance_name": "ooga.osuosl.org", "priority": 0, "timeout": 120}], "opstatus": ["running"], "received_ts": [1311791966, 837045], "start_ts": [1311791966, 870332], "status": "running", "summary": ["INSTANCE_SHUTDOWN(ooga.osuosl.org)"]} The following actions and parameters are supported: .. raw:: html
Action Parameters Description
reboot Reboot VM
shutdown Shutdown VM
startup Start VM up
rename hostname,ip_check,name_check Rename VM
/api/cluster ~~~~~~~~~~~~ This endpoint describes fields and operations available for the Cluster. .. raw:: html
Name Type ReadOnly Nullable Description
ram integer x Integer data. Ex: 2673
nodes_count Integer x x Returns nodes count for the cluster.
default_hypervisor string x Returns a default hypervisor for the cluster.
virtual_cpus integer x Integer data. Ex: 2673
disk integer x Integer data. Ex: 2673
port integer Integer data. Ex: 2673
hostname string Unicode string data. Ex: "Hello World"
id string Unicode string data. Ex: "Hello World"
available_ram list x x Returns a list with elements describing RAM status, including total, allocated, used and free memory.
master string x Returns master node
missing_ganeti list x x Returns a list with names of missing nodes in ganeti.
username string x Unicode string data. Ex: "Hello World"
missing_db list x x Returns a list with names of missing nodes in DB.
description string x Unicode string data. Ex: "Hello World"
software_version string x Returns a software version.
quota list x x Returns a list containing objects describing quotas for the user performing the request.
slug string Unicode string data. Ex: "Hello World"
info list x x Complex container exposing many information related to the cluster. More details with example can be found in documentation/wiki.
available_disk list x x Returns a list with elements describing disk status, including total, allocated, used and free disk space.
default_quota list x x Returns a list containing objects describing default quotas.
resource_uri string Unicode string data. Ex: "Hello World"
vm_count Integer x x Returns a number of virtual machines on the cluster.
**Containers: available_ram and available_disk** The first container provides information about status of the RAM in the cluster. Analogously, the second one provides information about disk space in the cluster. .. raw:: html
Name Type Description
total Integer Total RAM available to the cluster
allocated Integer> Allocated RAM
used Integer Amount of RAM used in the cluster
free Integer Free RAM
Example:: 1024 2004 874 980 **Containers: missing_ganeti and missing_db** Here the names of the missing machines are provided in the simple form. The former container describes machines missing in the Ganeti, while the former contains the machines missing in the database. Example:: 3429_test breakthis.gwm.osuosl.org brookjon.gwm.osuosl.org noinstall2.gwm.osuosl.org **Container: quota and default_quota** This container returns the quotas for the user performing request. If the user is not found or do not have a quotas assigned, default quota is returned. If there are no values for the specific quota element, null is returned. Default_quota container is additionally returned for the case that quota for the user if found. .. raw:: html
Name Type Description
default Integer Used if default quota is returned
virtual_cpus Integer Virtual CPUs
ram Integer Amount of RAM available to the user
disk Integer Amount of disk available to the user
Example:: 1 **Container: info** This element provides extensive information related to the cluster. These information are used internally in Ganeti Web Manager to render specific pages. As of level of detail used, the field contained here will not be described but just provided in detail in example. :: False paravirtual False 8102 0.0.0.0 30 ro disk False default False False False False 32 paravirtual live pool /dev/vda3 True kvm 8001 8030 False 4 1308862451.98 0b3b2432-a8e1-4c17-a99b-87303841cb95 0 gwm1.osuosl.org br0 bridged 2040000 2040000 2.4.2 20 10 /var/lib/ganeti-storage/file kvm /bin/true 1292887189.41 gwm.osuosl.org eth0 64bit x86_64 ganeti True 2 512 /api/node ~~~~~~~~~ In this endpoint exposed are the attributes and operations on the Cluster. .. raw:: html
Name Type ReadOnly Nullable Description
info list x This complex field returns various information related to the node.
ram_free integer x Integer data. Ex: 2673
Admin boolean x Determines if the user has admin status on the node
hostname string x Hostname of the node
modify boolean x Determines if the user is able to modify node parameters
cluster related x Cluster the node belongs to
disk_total integer Integer data. Ex: 2673
node_count Integer x Number of the nodes in the cluster
last_job related x A single related resource. Can be either a URI or set of nested resource data.
disk_free integer x Integer data. Ex: 2673
ram_total integer x Integer data. Ex: 2673
role string x Unicode string data. Ex: "Hello World"
offline boolean x Boolean data. Ex: True
id string x Unicode string data. Ex: "Hello World"
primary_list list x x List of virtual machines (primary node). Contains vm link (related) and hostname for particular object.
secondary_list list x x List of virtual machines (secondary node). Contains vm link (related) and hostname for particular object.
actions_on_node list x Returns the actions done on the node. The list is composed of objects, containing elements as described here.
resource_uri string x Unicode string data. Ex: "Hello World"
**Container: actions_on_node** This container provides the actions done on the node in form of the log. It is similar in the form to the other actions_on_X containers in other endpoints. For more info please take a look there. **Container: primary_list and secondary_list** These containers provide the list of virtual machines existing on the node in primary and secondary node mode. The list is simple and includes object hostname and related link. Example:: 3429 /api/vm/1/ breakthis.gwm.osuosl.org /api/vm/2/ **Container: info** This element provides extensive information related to the node. These information are used internally in Ganeti Web Manager to render specific pages. As of level of detail used, the field contained here will be described partially only. It should be noted that the elements in the table may be nullable. The full example output is included after the table. .. raw:: html
Name Type Description
pinst_cnt Integer Number of virtual machines for which the node is primary
sinst_cnt Integer Number of virtual machines for which the node is secondary
pinst_list List Virtual machines on this node (primary)
sinst_list List Virtual machines on this node (secondary)
drained Boolean Determines if the node is drained
offline Boolean Determines if the node is ofline
vm_capable Boolean Determines if the node is capable of hosting virtual machines
master_capable Boolean Determines if the node is capable to become master node
master_candidate Boolean Determines if the node is master candidate
mnode Boolean Determines if the node is active master node
pip String Primary IP address of the node
sip String Secondary IP address of the node
uuid String UUID
group.uuid String group UUID
tags List Tags attached to the node
:: 30336 1 1 60012 0 140.211.15.61 1310 140.211.15.61 4a0e9df5-0b59-4643-b156-c133edb035bc False 1 M 2 False True 15 2004 e318906a-40cd-4702-813b-c2185abaf8ec True True gwm1.osuosl.org 730 3429 noinstall2.gwm.osuosl.org failed success derpers.gwm.osuosl.org testtestbreakthis.gwm.osuosl.org foobarherpderp.gwm brookjon.gwm.osuosl.org orphanme foobar352 testcdrom2.gwm.osuosl.org ooga.osuosl.org diskless3 noinstall.gwm.osuosl.org /api/job ~~~~~~~~ This endpoint exposes information related to the job execution in the system. .. raw:: html
Name Type ReadOnly Nullable Description
status string Unicode string data. Ex: "Hello World"
summarys string x x Describes the job summary.
job_id integer Integer data. Ex: 2673
cluster_admin Boolean x Determines if the current user has admin permissions over related cluster.
ops list x Complex field containing details about job. The field contents depend on the job type. More details can be found in the wiki.
opresult list x x Describes the error occurred during job execution.
cluster related A single related resource. Can be either a URI or set of nested resource data.
finished datetime x A date & time as a string. Ex: "2010-11-10T03:07:43"
cleared boolean Boolean data. Ex: True
resource_uri string Unicode string data. Ex: "Hello World"
**Container: opresult** This field contains a detailed description of error encountered during job execution. The fields included are the following: .. raw:: html
Name Type Description
error_type string Denotes the type of the error
error_message string Contains a summary description of the error. May be omitted.
error_family string Relates error to the family of errors. May be omitted.
Example:: OpPrereqError The given name (owelwjqe) does not resolve: Name or service not known resolver_error **Container: ops** This field contains information about the job executed. There may be many subfields included, spanned through several levels. The following excerpts provide two typical example outputs: ::
    
    
    
    paravirtual
    disk
    /dev/vda3
    False
    
    paravirtual
    
    
    0
    plain
    True
    
    
    
    False
    gwm1.osuosl.org
    
    
    br0
    bridged
    
    
    True
    0
    True
    True
    120
    
    False
    
    
    False
    OP_INSTANCE_CREATE
    
    
    kvm
    False
    
    
    408
    
    
    owelwjqe
    create
    
    loop
    image+debian-squeeze
    
    2
    512
    
    
    
    
::
    
    
    brookjon.gwm.osuosl.org
    False
    False
    0
    0
    OP_INSTANCE_REBOOT
    hard
    120