APIExamples

Introduction

Examples of how to perform tasks with multiple requests using the Abiquo API can be found in API Tutorials. Before you begin working with the Abiquo API, please read Get Started with the Abiquo API, which shows you how to obtain information about your environment's resources and the API by using the Abiquo UI and API together.

This APIExamples section contains the standardized API examples that are also provided in the Abiquo wiki in the resource and method descriptions in the API Reference section. The example pages are named based on the REST option (e.g. GET) and the URL of the API resource and method, as well as the media types and formats.These standardized API examples are simple cURL commands designed to help new developers get an overall picture of the Abiquo API. We also hope that the examples may be useful in providing information about the vitally important resource links that can be found in most Abiquo resources, but which present challenges in documentation.

We expect every user will have their preferred tools for making quick test requests, from cURL to POSTman, or Advanced REST client, and every developer will have their own development languages. Therefore, we have tried to create consistent, easy to read examples to help you quickly translate the information in the documentation into actions in the real world of the Abiquo API.

In order to quickly and efficiently produce examples of most of the requests of the very expansive Abiquo API, we have taken advantage of the output of the Abiquo integration tests. This means that dummy entities, strange text strings, or empty lists may at times appear in the examples. As there around 900 examples, the manual revision of these files is an ongoing project.

Commands

The integration tests may be run using HTTP with a localhost address on port 9000. To use the examples, you will need to change this, for example to use HTTPS, and replace the URL and port with those of of your Abiquo system. For example, https://my.abiquo.com/api. For simplicity, user and password authentication is shown in the examples. However, for production systems, OAuth is recommended. See Authentication.

To enable cut and paste to a shell, backslashes are placed at the end of each line to escape the new line. Requests should contain single quotation marks, not back ticks. Every effort has been made to ensure that single quotation marks are used in the cURL commands in the examples, to enable copy and paste where required. However, you may achieve better results by checking and modifying the command in a text editor before pasting it in a shell. You should always use the version number with your media types in requests to the Abiquo API in order to avoid compatibilty issues in future versions.

Data payloads

Put and post requests contain a request payload. We have made these payloads visible, rather than using file attachments, because we believe that they can provide useful information about the data entities involved in each query.

To achieve consistency for all request payloads, regardless of their length, we use a data file format in the examples. The cURL command has a -d parameter, which indicates the request payload. The \@ symbol means that the following text is a file name. To run the query, you can create a file with the name requestpayload.<format>, where format could be json, xml, text, etc. 

 Instead of using a file, you could put the request payload inline. In this case, the easiest approach is to put any authentication line (-u user:password --verbose) above the payload line with a backslash at the end. The payload line should contain -d followed by single quotation marks enclosing the data entity. To ensure JSON compatibility, double quotation marks should be used in JSON strings. You can validate your data entities with JSON or XML formatters or checkers. 

Please remember that the example payloads are not specially designed templates for creating a new resource or modifying a resource. For create requests, you may find additional examples of simple requests in the API Reference pages or you may be able to find examples of simple entities by looking at requests made by the Abiquo UI. For modify requests, you should perform a get of an existing object and then make your changes. See Get Started with the Abiquo API. The Abiquo API will return a response to post requests in the accept media type you specify in your requests. When you use cURL, then the response payload will be raw data. You can then pipe this output to a formatter, such as xmllint, xmlindent or pjson. Or cut and paste to format it in an online tool.

Example cURL command

So here is an example of how a cURL command might look for a test system, where the insecure -k connection is used with https.

curl -X POST --verbose -k https://my.abiquoserver.com/api/cloud/virtualdatacenters/1/virtualappliances/1/virtualmachines \
     -H 'Content-Type: application/vnd.abiquo.virtualmachine+json; version=3.6' \
     -H 'Accept: application/vnd.abiquo.virtualmachine+json; version=3.6' \
     -u admin:xabiquo \
     -d '{"label":"Core_new","links":[{"title":"Core","rel":"virtualmachinetemplate","type":"application/vnd.abiquo.virtualmachinetemplate+json",
          "href":"http://example.com/api/admin/enterprises/1/datacenterrepositories/1/virtualmachinetemplates/1"}],"vdrpEnabled":true}' | python -m json.tool

Abbreviations used in page and file names