Basic Behaviors

This document describes how to generate requests and interpret responses of the Abiquo API, supported by the Abiquo Server (the Server). The Abiquo API aims to follow a consistent REST style with navigable hyperlinks (HATEOAS).

Server and resource URIs

To begin operations, a client must know the URI of a Server, for example, https://abiquo.example.com/api
The system identifies the resources using URIs, for example, https://abiquo.example.com/api/admin/enterprises, where /enterprises/ refers to the collection of enterprises and /enterprises/x refers to a single enterprise.
From each resource, the Abiquo API links to all of the accessible resources, and a client should reach a resource URI only by following links from other entities. The client should avoid creating the URI of a resource
All requests use the Hypertext Transfer Protocol (HTTP), version 1.1 as the transport protocol.
We do not recommend the use of HTTP Basic Authentication, but the Server can authenticate these requests. If you use them, they should be sent over a secure channel such as a VPN, or using the HTTPS protocol. See Authentication

Data media types and request headers

Clients must provide a vendor-specific media type for each data entity, for example, if you wanted to send or retrieve an Abiquo tenant, you would use "application/vnd.abiquo.enterprise".
- If clients DO NOT supply a media type, the Abiquo API may return an error or an arbitrary media type (where more than one method uses the same URI and returns different media types)
Clients can use JSON or XML format for data, and this should be specified after the media type with "+json" or "+xml". If not specified, the "+json" default will be assumed
- Do not try to convert data objects from XML to JSON or vice versa.
Clients should also provide the version of the data entity (after the media type and the format), for example, "version=5.0"
- If clients DO NOT supply the version of the data entity, the Abiquo API will use the MOST RECENT VERSION of a feature. We STRONGLY RECOMMEND that you always use versions to avoid problems on upgrades.
Clients should supply the media type of the data entity they are sending with the "Content-Type" header.
Clients should supply the media type they expect for the response in the "Accept" header.

Example request headers

Example Accept and Content type headers (POST and PUT requests)

'Accept:application/vnd.abiquo.virtualmachine+json; version=5.0' 
'Content-Type:application/vnd.abiquo.virtualmachine+json; version=5.0'

Example of Accept header (GET requests)

'Accept:application/vnd.abiquo.virtualmachine+json; version=5.0'

Request Parameters

Request parameters include paging parameters for collections of data entities, which are described in the Paging parameters section, and additional query parameters to filter and sort resource data, which are described in the API reference documentation for each resource.

Collection data entities

The Abiquo API has two main media entity types: collections and single entities.

Collection media types may contain multiple data entities. An example of a collection is the "enterprises" media type, in contrast to the "enterprise" media type for a single enterprise. The collection object is a list of single data entities.

Collection media types may return large numbers of data entities, so the API will usually paginate them, and you can use paging parameters and links to access groups of entities.

The collection media type includes:

A totalSize attribute that is the total number of objects in the resource
Pagination links so you can navigate the data entities of the resource.

The collection media type may contain other links and other variables in addition to the ones listed above.

The following collection of virtual datacenters has a link to the alarm search. It does not include networks and links to reduce the size of the virtual datacenter objects.

A collection of virtualdatacenter entities without networks or links

{
    "totalSize": 5,
    "links": [
        {
            "rel": "first",
            "href": "https://nardo40.bcn.abiquo.com:443/api/cloud/virtualdatacenters?limit=25&by=name&asc=true"
        },
        {
            "rel": "last",
            "href": "https://nardo40.bcn.abiquo.com:443/api/cloud/virtualdatacenters?startwith=0&limit=25&by=name&asc=true"
        },
        {
            "title": "alarmssearch",
            "rel": "alarmssearch",
            "type": "application/vnd.abiquo.alarms+json",
            "href": "https://nardo40.bcn.abiquo.com:443/api/cloud/virtualdatacenters/alarms"
        }
    ],
    "collection": [
        {
            "id": 2489,
            "hypervisorType": "VCD",
            "name": "vcd_vcloud510_TEF",
            "network": { ...
            },
            "providerId": "urn:vcloud:vapp:f400c68f-fa57-4b91-838c-30ef15b37cd4",
            "syncState": "NONE",
            "usersRole": [],
            "diskSoftLimitInMb": 0,
            "diskHardLimitInMb": 0,
            "storageSoftInMb": 0,
            "storageHardInMb": 0,
            "vmsSoft": 0,
            "vmsHard": 0,
            "vlansSoft": 0,
            "vlansHard": 0,
            "publicIpsSoft": 0,
            "publicIpsHard": 0,
            "links": [ ...
            ],
            "ramSoft": 0,
            "ramHard": 0,
            "cpuSoft": 0,
            "cpuHard": 0
        },
        {
            "id": 2486,
            "hypervisorType": "VCENTER_CLUSTER",
            "name": "vdc_api_tutorial",
            "network": { ...
            },
            "syncState": "NONE",
            "usersRole": [],
            "diskSoftLimitInMb": 0,
            "diskHardLimitInMb": 0,
            "storageSoftInMb": 0,
            "storageHardInMb": 0,
            "vmsSoft": 0,
            "vmsHard": 0,
            "vlansSoft": 0,
            "vlansHard": 0,
            "publicIpsSoft": 0,
            "publicIpsHard": 0,
            "links": [ ...
            ],
            "ramSoft": 0,
            "ramHard": 0,
            "cpuSoft": 0,
            "cpuHard": 0
        },
        {
            "id": 2452,
            "hypervisorType": "VCENTER_CLUSTER",
            "name": "vdc_ESXI_DC1_cluster",
            "network": { ...
            },
            "syncState": "NONE",
            "usersRole": [],
            "diskSoftLimitInMb": 0,
            "diskHardLimitInMb": 0,
            "storageSoftInMb": 0,
            "storageHardInMb": 0,
            "vmsSoft": 0,
            "vmsHard": 0,
            "vlansSoft": 0,
            "vlansHard": 0,
            "publicIpsSoft": 0,
            "publicIpsHard": 0,
            "links": [
            ],
            "ramSoft": 0,
            "ramHard": 0,
            "cpuSoft": 0,
            "cpuHard": 0
        },
        {
            "id": 2450,
            "hypervisorType": "VMX_04",
            "name": "vdc_ESXI_DC2_vcenter",
            "network": { ...
            },
            "syncState": "NONE",
            "usersRole": [],
            "diskSoftLimitInMb": 0,
            "diskHardLimitInMb": 0,
            "storageSoftInMb": 0,
            "storageHardInMb": 0,
            "vmsSoft": 0,
            "vmsHard": 0,
            "vlansSoft": 0,
            "vlansHard": 0,
            "publicIpsSoft": 0,
            "publicIpsHard": 0,
            "links": [ ...
            ],
            "ramSoft": 0,
            "ramHard": 0,
            "cpuSoft": 0,
            "cpuHard": 0
        },
        {
            "id": 2482,
            "hypervisorType": "VCENTER_CLUSTER",
            "name": "vdc_ESXI_tocho",
            "network": { ...
            },
            "syncState": "NONE",
            "usersRole": [],
            "diskSoftLimitInMb": 0,
            "diskHardLimitInMb": 0,
            "storageSoftInMb": 0,
            "storageHardInMb": 0,
            "vmsSoft": 0,
            "vmsHard": 0,
            "vlansSoft": 0,
            "vlansHard": 0,
            "publicIpsSoft": 0,
            "publicIpsHard": 0,
            "links": [ ...
            ],
            "ramSoft": 0,
            "ramHard": 0,
            "cpuSoft": 0,
            "cpuHard": 0
        }
    ]
}

Links for navigating paged resources

There are up to 4 pagination links with the following values of the "rel" (relation) link.

rel='first': always refers to the first page (startwith=0). This link is always shown
rel='last': always refers to the last page. This link is always shown
rel='previous': refers to the previous page. This link is shown when we are not on the 'first' page
rel='next': refers to the next page. This link is shown when we are not on the 'last' page

Example of total size attribute and paging links

 {
  "totalSize": 254,
  "links": [
    {
      "href": "http://localhost:9009/api/admin/datacenters/4017/network/1608/ips?limit=25&by=ip&asc=true",
      "rel": "first"
    },
    {
      "href": "http://localhost:9009/api/admin/datacenters/4017/network/1608/ips?startwith=25&limit=25&by=ip&asc=true",
      "rel": "previous"
    },
    {
      "href": "http://localhost:9009/api/admin/datacenters/4017/network/1608/ips?startwith=50&limit=25&by=ip&asc=true",
      "rel": "next"
    },
    {
      "href": "http://localhost:9009/api/admin/datacenters/4017/network/1608/ips?startwith=229&limit=25&by=ip&asc=true",
      "rel": "last"
    }
  ],

Pagination links will respect your current request parameters. If you do not specify pagination parameters, the pagination links will include the default values. If you send custom values, for example, a custom limit, the 'next' link will offer another page of the same length, where the 'startwith' parameter will continue from the last element of your current page.

Pagination parameters

To control the number of data entities to retrieve and/or sort entities, in order to improve the user experience, clients can specify the following pagination parameters.

Parameter Name	Description	Default Value
startwith	The first element to be retrieved of the filtered search	0
limit	The number of entities to retrieve. To retrieve all entities, use limit = 0	25
has	Filter with a text value for specific attributes. See resource documentation	''
by	Sort preference. Usually an attribute name. See resource documentation	Depends on the resource
asc	Specifies if the value of the 'by' parameter must be sorted in ascending order (true) or descending order (false)	true

As described in the default value column, by default the Server filters by retrieving the first 25 entities, starting with the first one, and sorts them in ascending order.

Error responses

When an error occurs, for every request in error, the Abiquo API returns:

An appropriate HTTP status code. See https://httpstatuses.com/
A collection of error response

The error response data model is as follows:

Field Name	Type	Occurs	Required	Description
code	String	1	true	The internal application error code.
message	String	1	true	The description of the error

For a list of codes and messages, see API Error Code List. For a list of platform events, including actions, tracer messages, and associated error codes, see Events Table.

The JSON error response message format is as follows.

JSON error response format

{
  "errors": [
     {"code": "CODE-01", "message": "Error details"},
      ....
  ]
}

Related links: