¶ API Introduction
The VergeIO system offers an API interface for custom development integration. This document serves to outline use of the API. Detailed information for the API can be found within the VergeIO UI, as a Swagger wiki page; the wiki page is created dynamically and will show a complete listing of VergeIO tables to access.
¶ Swagger Interface
Customers can access the inline Swagger documentation by navigating following these steps:
-
Login in to any VergeIO system with valid user credentials
-
From the Main Dashboard, click System on the left menu.
-
Once inside the System Dashboard, at the bottom left, there is a link to the API documentation.
-
Click the link to launch the Swagger documentation wiki (Note: The page may take a couple minutes to load.) The swagger page provides examples of each function, a list of operations for each, and an ability to test each.
-
Click an individual table in the line to access options:
-
Click one of the GET/POST/DELETE/PUT options:
-
Specify parameters and click the Execute Button to run the API Command
This will return the response which includes the response body and header. Included is a curl example to be used in your program.
¶ Authentication
The following are ways to pass authentication through the API. Currently, VergeIO offers two methods:
- Basic http authentication
- API database table
For the basic http authentication, the API is only available through SSL.
For API Database table, this is done by
- Passing a database into the table
- The table responds with a token
- That token needs to pass in all subsequent functions in the header
To get a login token, developers will need to post to the /sys/tokens table for the customer system. As an example, the API URL for a test tenant would be https://systemname.systemdomain.com/api/sys/tokens . Here is an example curl:
curl --header "X-JSON-Non-Compact: 1" --basic --data-ascii '{"login": "USERNAME", "password": "PASSWORD"}' --insecure --request "POST" --header 'Content-Type: application/json' 'https://test.cloud.Verge.io.com/api/sys/tokens’
Here is an example of what would be returned:
{
"location":"\/sys\/tokens\/3a334563456378845634563b7b82d2efcadce9",
"dbpath":"tokens\/3a334563456378845634563b7b82d2efcadce9",
"$row":1,
"$key":"3a334563456378845634563b7b82d2efcadce9"
}
Developers would now need to pass the value in "$key" in the HTTP header "x-yottabyte-token". So in this example a developer would send the following header:
x-yottabyte-token: 3a334563456378845634563b7b82d2efcadce9
To issue a logout for this token/session, the API will need to send a DELETE HTTP Method to /sys/tokens/3a334563456378845634563b7b82d2efcadce9
Optionally, when sending API requests, developers can pass the header "X-JSON-Non-Compact: 1" to have all responses sent back as friendly-spaced JSON.
¶ API Helper Script
Developers can request a copy of the "yb-api" script which is a helper used to make API calls. For help and a list of options developers can run "yb-api --help". To run this, connect to a node in your cluster, either directly or through SSH. Then type in the commands there.
Notes regarding yb-api helper script:
The helper "yb-api" script uses wget, which may not automatically be installed on OSX.
The helper "yb-api" script also uses curl on an upload function.
The following are example commands using yb-api:
Get a list of VMs (the filter will make this query exclude VM snapshots):
yb-api --get --user=admin --server=10.0.0.100 --fields='name,$key,ram,machine#status#status as machine_status' --filter='is_snapshot eq false' /v4/vms
Get a list of VMs Simple Dump (--server, --user, --filter, --fields are optional):
yb-api --get /v4/vms
Get most of the fields, including drives and nics, for VM 1 (this number would be the value of $key that is returned in the above query):
yb-api --get --user=admin --server=10.0.0.100 --fields='most,machine[most,drives[most],nics[most]]' /v4/vms/1
Change the name of VM 1:
yb-api --put='{"name":"NEWNAME"}' --user=admin --server=10.0.0.100 /v4/vms/1
Delete VM 1:
yb-api --delete --user=admin --server=10.0.0.100 --fields='name,$key,ram' /v4/vms/1
Create a new VM:
yb-api --post='{"name":"NEWVM","enabled":true,"description":"test vm","os_family":"linux","cpu_cores":4,"ram":"8192"}' --user=admin --server=10.0.0.100 /v4/vms
Get the VMs database table schema:
yb-api --get --user=admin --server=10.0.0.100 '/v4/vms/$table'
Clone VM 1:
yb-api --get --user=admin --server=10.0.0.100 '/v4/vm_actions' --post='{"vm":1, "action": "clone", "params": {"name": "NEW VM NAME"}}'
Power on VM 1:
yb-api --get --user=admin --server=10.0.0.100 '/v4/vm_actions' --post='{"vm":1, "action": "poweron"}'
¶ API Basics
Overview
The yCenter API is RESTlike. All API requests must be made over HTTPS and should be authenticated with Basic Access Authentication. It is also possible to POST to /api/sys/tokens to create a session and pass that as the header "x-yottabyte-token" which needs to be deleted to log out.
Resources
Below is an example URL used to query a list of machines.
Example: https://user1:xxxxxx@server1.verge.io/api/v4/machines?fields=all
| https:// | user | : | password | @ | server | /api | /v4/machines | ? | filter=&fields=all&sort=&limit= |
| User name | User Password | Server host name or IP | Resource location (URI) | These options are described below |
GET Options
Fields
- Specify which fields to return in the result set (may also be a view if there is one defined for the table schema)
- all is a view for every field
- most is a view for every field except for argument fields and rows
- summary is the default value and only fields that have 'summary' set to 'true' in their schema will be returned
- fields=name,email,enabled,groups[all] as all_groups,collapse(groups[name]) as first_groups_name
- field functions:
- collapse
- datetime
- upper
- lower
- count
- diskspace
- display
- hex
- sha1
- sum
- avg
- min
- max
Filter
- Filter result set by specified criteria
- Similar to OData
- filter=enabled eq true and size gt 1048576
- filter=cputype eq 'qemu' or cputype eq 'kvm'
- When creating a filter a field, it may not be required, make sure it is included in the fields list
| Operator | Description |
| eq | Equal |
| ne | Not equal |
| gt | Greater than |
| ge | Greater than or equal |
| lt | Less than |
| le | Less than or equal |
| bw | Begins with |
| ew | Ends with |
| and | Logical and |
| or | Logical or |
| cs | Contains string (case sensitive) |
| ct | Contains text (case insensitive) |
| rx | Regex match |
Sort
- Sort results by the field specified
- sort=+name
- sort=-id ##
Limit
- (integer) limit result set - value of 0 for unlimited
- **limit=**1
Generic HTTP Response Codes
- 400 - Bad request
- 401 - Failed login / login required
- 403 - Permission denied
- 404 - Row or API doesn't exist
- 405 - Not permitted
- 409 - Row exists
- 422 - Failed validation / Invalid parameter
- 500 - Unhandled error code
Post Specific
- 201 – Created row
Websocket Specific (Used for VNC/SPICE)
- 101 – Switching protocol
PUT/GET/DELETE
- 200 – Success
¶ Schema Table Definitions
¶ Field types:
- bool
- text
- string
- num
- uint8
- uint16
- uint32
- uint64
- int8
- int16
- int32
- int64
- enabled
- created
- created_ms
- created_us
- modified
- modified_ms
- modified_us
- filename
- filesize
- fileused
- fileallocated
- filemodified
- json
- row
- rows
Schema Owner / Parent Field
- owner field: if owner field is null then normal permissions apply, if owner field has value then permissions are replaced by a permission check to the owner
- parent field: the permission check is applied to the row itself, and if permissions fail then permissions are also checked on the parent
¶ Full Table Schema
To retrieve a table’s schema append $table to the URI:
/api/v4/machines/$table (replace machines with the table name)
It will ask for your credentials, this does not support your other authentication methods and requires your VergeIO admin credentials.
Note: The output is in JSON format. Firefox will display this by default in a nice readable format. For other browsers you may want to output to another program to view the JSON correctly.
¶ Example Errors
¶ Example Error from Server (HTTP Code 422)
{
"err": "Validation error on field: 'dhcp_start' - 'fails validation test'"
}
Need more Help? Email support@verge.io or call us at (855) 855-8300