Basic Behaviors

version: 1.1
Based on: Project Kenai: RESTful Cloud Specification - Common Behaviors
Copyright © Sun Microsystems, 2009. This work is licensed under Creative Commons Attribution 3.0 Unported License
This document specifies constraints that apply to all the requests and responses that occur in the RESTful APIs supported by the Abiquo Server, hereinafter referred to as "The Server".

Imperative Terms In Specifications

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document, and all other documents that comprise the specification of The Platform RESTful API, are to be interpreted as described in "Key words for use in RFCs to Indicate Requirement Levels" (RFC 2119).

Transport Protocol

All of The Server APIs are based on the Hypertext Transfer Protocol, version 1.1 (RFC 2616). Each request will be authenticated using HTTP Basic Authentication (RFC 2617). Therefore, requests sent from clients on the public Internet (and not on a secure channel such as a VPN) SHOULD use the https protocol.

URI Space

All the resources of the system are identified by URIs. To begin operations, a client must know the URI for a Server.
Clients MUST NOT make assumptions about the layout of the URIs within a Space.

Versioning and Mime Types in Abiquo API v2.0 and above

In version 2.0, the API has been changed to support versioning and a vendor-specific mime type needs to be specified. This API Documentation is currently being updated to reflect these changes. See Versioning.

Abiquo API will use the most recent version of a feature if the version parameter of the Accept and Content-type headers is not supplied. Even if you are using a client updated to the latest version of the API, we strongly recommend you use version parameters in order to avoid future problems with updates: Abiquo's API will not know if you have updated or not!

Media Types

In The Server API, resource representations and request bodies are normally encoded in JSON or XML.

Each type of resource matches the pattern application/xml and application/json, even the errors.

The Server MUST provide representations of all resources available in JSON and XML.

The Server MUST accept requests from clients encoded in JSON and XML.

Request Headers

version number in Abiquo v2.0

Request Headers in Abiquo v2.0 and above may include the version number. An example of a request header with version:
Accept:application/vnd.abiquo.enterpriseexclusionrules+json; version=3.1;

In requests made to services implementing abiCloud APIs, several specific HTTP headers are used as described in the following table:

Header	Supported Values	Description of Use	Required
Accept	Comma-delimited list of media types or media type patterns.	Indicates to the server what media type(s) this client is prepared to accept.	Recommended, on requests that will produce a response message body.
Authorization	"Basic" plus username and password (under RFC 2617)	Identifies the authorized user making this request.	No.
Content-Length	Length (in bytes) of the request message body.	Length (in bytes) of the request message body.	Yes, on requests that contain a message body.(1)
Content-Type	Media type describing the request message body.	Describes the representation and syntax of the request message body.	Yes, on requests that contain a message body.
Host	Identifies the origin host receiving the message.	Required to allow support of multiple origin hosts at a single IP address.	All requests. Note that since a single Space may spread its URIs across multiple hosts, this may need to be set again for each request.
X-YYYYY-Client-Specification-Version	String containing a specification version number.	Declares the specification version of the YYYYY API that this client was programmed against.	No (current version is assumed if this header is not present).

(1) Some APIs MAY require a "Content-Length: 0" header to be included on a POST request that contains no request message body.

Note that because all interactions with RESTful abiCloud APIs are stateless, no Cookie header (or any other mechanism to provide a session identifier) is used.

Request Parameters

Since the URI space is controlled by the Server, client programs MUST not make any assumptions about the meanings of request parameters.

Paging Parameters

Some resources (like IPs, number of Virtual Datacenters per Datacenter) contain a large number of entities to be retrieved. In these cases, Abiquo API offers a way to filter the search, control the number of entities to be retrieved or control its sorting method in resource's query parameters in order to improve the user experience. When a resource offers this functionality we name it paged resource.

Paged resources are always exposed the same way using the same query parameters. These parameters are:

Parameter Name	Description	Default Value
startwith	The first element to be retrieved of the filtered search	0
limit	The number of entities to retrieve	25
has	Filter value. Depends on the resource, this value affects different to the request. That means the resource must be properly documented to let you know what you can filter and what you can not	''
by	Sort preference. Depends on the resource, this value affects different to the request. That means the resource must be properly documented to let you know how you can sort the output	Depends on the resource
asc	If the value of the 'by' parameter must be sorted in ascending way (true) or descending way (false)	true

The Default Value column values mean that by default all paged resources are already filtered retrieving the first 25 entities, starting with the first one, and sorted arbitrarily (depending on the resource) in ascending way. If you want all the entities back instead of a range of them, just use the limit=0 query parameter.

Even though you will see always these parameter values in the resource method documentation, we will remark its paging nature with the following macro:

Paging method

This method works with paging. Go to Basic Behaviors for more information about how it works

Paging Links

When a resource is paged, then the API offers you a way to navigate through the full range of entities with paging links in its response. These links look like this:

    <link rel="first" href="http://example.com/api/cloud/virtualdatacenters/1/privatenetworks/1/ips?by=ip"/>
    <link rel="previous" href="http://example.com/api/cloud/virtualdatacenters/1/privatenetworks/1/ips?by=ip"/>
    <link rel="next" href="http://example.com/api/cloud/virtualdatacenters/1/privatenetworks/1/ips?startwith=36&by=ip"/>
    <link rel="last" href="http://example.com/api/cloud/virtualdatacenters/1/privatenetworks/1/ips?startwith=252&by=ip"/>

There are up to 4 paging links:

rel='first': it will always refer to the first page (startwith=0). This link is always shown
rel='last': it will always refer to the last page. This link is always shown
rel='previous': it will refer to the previous page. This links is always shown unless we are in the 'first' page.
rel='next': it will refer to the next page. This link is always shown unless we are in the 'last' page.

Good news about the paging links is they respect you current request parameters. For instance, if you execute the following request:

curl -X GET "http://example.com/api/cloud/virtualdatacenters/1/privatenetworks/1/ips" -u user:password

The 'next' link will be:

<link rel="next" href="http://example.com/api/cloud/virtualdatacenters/1/privatenetworks/1/ips?startwith=25&limit=25&by=ip"/>

Since in the request we are using the 'Default Values' for this resource. But, if you execute:

curl -X GET "http://example.com/api/cloud/virtualdatacenters/1/privatenetworks/1/ips?limit=3" -u user:password

The 'next' link will be:

<link rel="next" href="http://example.com/api/cloud/virtualdatacenters/1/privatenetworks/1/ips?startwith=3&limit=3&by=ip"/>

See how it overrides the limit parameter and calculates the startwith parameter for the next page according with the current page length.

Response Headers

In responses returned by The Server, several specific HTTP headers are used as described in the following table:

Header	Supported Values	Description of Use	Required
Content-Length	Length (in bytes) of the response message body.	Describes the size of the message body.	Yes, on responses that contain a message body.
Content-Type	Media type describing the response message body.	Describes the representation and syntax of the response message body.	Yes, on responses that contain a message body.

Standard HTTP Status Codes

Abiquo APIs will return standard HTTP response codes as described in the following table, under the conditions listed in the description. See also Response Errors

HTTP Status	Description
200 OK	The request was successfully completed. If this request created a new resource that is addressable with a URI, and a response body is returned containing a representation of the new resource, a 200 status will be returned with a Location header containing the canonical URI for the newly created resource.
201 Created	A request that created a new resource was completed, and no response body containing a representation of the new resource is being returned. A Location header containing the canonical URI for the newly created resource should also be returned.
202 Accepted	The request has been accepted for processing, but the processing has not been completed. Under the HTTP/1.1 specification, the returned entity (if any) SHOULD include an indication of the request's current status, and either a pointer to a status monitor or some estimate of when the user can expect the request to be fulfilled. Most asynchronous API methods (deploy virtual machine, reconfigure virtual machine) return this status.
204 No Content	The request has been accepted but it does not return any data in the message body. DELETE methods and asynchronous methods that have already finished return this status code.
400 Bad Request	The request could not be processed because it contains missing or invalid information (such as validation error on an input field, a missing required value, and so on).
401 Unauthorized	The authentication credentials included with this request are missing or invalid.
403 Forbidden	The server recognized your credentials, but you do not possess authorization to perform this request.
404 Not Found	The request specified a URI of a resource that does not exist.
405 Method Not Allowed	The HTTP verb specified in the request (DELETE, GET, HEAD, POST, PUT) is not supported for this request URI.
406 Not Acceptable	The resource identified by this request is not capable of generating a representation corresponding to one of the media types in the Accept header of the request.
409 Conflict	A creation or update request could not be completed, because it would cause a conflict in the current state of the resources supported by the server (for example, an attempt to create a new resource with a unique identifier already assigned to some existing resource).
415 Unsupported Media Type	The header "Content-type" does not match with the expected content type
500 Internal Server Error	The server encountered an unexpected condition which prevented it from fulfilling the request.
501 Not Implemented	The server does not (currently) support the functionality required to fulfill the request.
503 Service Unavailable	The server is currently unable to handle the request due to temporary overloading or maintenance of the server.

Basic Links Data Model

This resource is the most basic one. It only has links to other resources. It is used when we want to associate a resource to another one. For instance, when we attach a Volume that was already created to a Virtual Machine.

Field Name	Type	Occurs	Required	Description
link	String (a link)	1..n	optional	A link to an existing resource. Normally it has a REL field to provide a better understanding of the resource it points to