Abiquo Documentation Cookies Policy

Our Documentation website uses cookies to improve your experience. Please visit our Cookie Policy page for more information about cookies and how we use them.


Abiquo Documentation

Skip to end of metadata
Go to start of metadata

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 be 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 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=4.5"
    • 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=4.4' 
    'Content-Type:application/vnd.abiquo.virtualmachine+json; version=4.4' 
    Example of Accept header (GET requests)
    'Accept:application/vnd.abiquo.virtualmachine+json; version=4.4' 

Request Parameters

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

Paginated resources

Collection media types may return large numbers of data entities, so the API will paginate the data entities. 

Parameters to control pagination of response data

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 NameDescriptionDefault Value
startwithThe first element to be retrieved of the filtered search0
limitThe number of entities to retrieve. To retrieve all entities, use limit = 025
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
ascSpecifies 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. 

Total size and links for navigating paged resources

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.

Collections include:

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

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.

Error responses

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

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"},
      ....
  ]
}