Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 62 Next »



This section is a quick introduction to the Abiquo REST API and link navigation starting from the Abiquo user interface.



Introduction

Welcome to the REST API of the Abiquo cloud platform. Yes, the Abiquo API really is a HATEOAS REST API. 

So, there are links everywhere, for navigation, to perform actions, and even to define the configuration of cloud entities.

Fortunately, the Abiquo UI is a client of the Abiquo public REST API, so it's easy to look in your browser tools and find out how the UI performs any API request. 

In this tutorial you will:

  1. Create a VM with the UI and the API
  2. Get a VM and deploy it
  3. Get a group of VMs with the API



Requirements

You will need to be familiar with your browser tools. We used Google Chrome.

To complete this tutorial and part 2, you will need a working Abiquo platform with: 

  1. Private cloud infrastructure 
  2. A virtual datacenter with a virtual appliance inside
  3. An Abiquo private network in the virtual datacenter with two IP addresses in it

To become familiar with the UI and create the required entities:


Authentication

You will need to authenticate with your own credentials as appropriate in your environment. For a complete guide, see Authentication. For this tutorial you could use:

  • Token authentication: 
    1. Send a GET request with basic authentication to the login resource of your API, for example, https://abiquo.example.com/api/login
    2. Get the token from the X-Abiquo-Token header 
    3. In your request, use the format of Authentication: Token XXXXXXXX
  • Basic authentication: in a securely isolated test environment only
    • Use Authentication: Basic XXXXX with the format user:password in base64 encoding
      Or in the request line use the option -u user:password 
    • In your test environment you may also need to add the insecure -k option to the request. 
  • OAuth authentication. See Authentication



Create a VM with the UI and obtain the POST request

Create a VM with the UI to obtain the API method link and data object.

  1. Log in to Abiquo and open your browser console to the Network tab
  2. Record browser actions
  3. Create a VM in the UI. The UI will send a POST request to the API

  4. In the browser console, find the POST request

    1. Tips when using Chrome:
      1. To display the Method column to easily identify the POST request, right-click on the header row to display the header options list, then select Method.
      2. To copy the request directly from the UI, right-click on the request URL and select Copy as cURL and delete UI cache details from the URL before you run it
  5. From Headers, Response Headers find the location. This is the VM link where you will send requests to modify the VM 
  6. From the Payload, click view source, and right-click and copy, then format with a JSON formatter. This is the VM object that you can modify and use in the next request to create a VM

Screenshot from Chrome: the POST request to create a VM is selected.






Analyze the post request

This section explains the request to create the VM in a bit more detail.

When you created the VM:

  • The UI sent the POST request to the virtualmachines link of the virtual appliance. The link contains the IDs of the virtual datacenter and virtual appliance.

    https://mjsabiquo.lab.abiquo.com:443/api/cloud/virtualdatacenters/12/virtualappliances/4/virtualmachines
    • You can use this link to create another VM

    • In this case, the ID values are 12 and 4.

  • The Request Payload contains the basic VM object with a name and a link to a VM template, and an option to enable remote access to the VM.

    {
   "name":"vmapihowto",
   "links":[
      {
         "title":"yVM",
         "rel":"virtualmachinetemplate",
         "type":"application/vnd.abiquo.virtualmachinetemplate+json",
         "href":"https://mjsabiquo.lab.abiquo.com:443/api/admin/enterprises/1/datacenterrepositories/2/virtualmachinetemplates/145"
      }
   ],
   "vdrpEnabled":true
}
    • You can copy this object and modify it to create another VM

  • After the POST request is successful, the Location link, which you can obtain from the Request headers is the URL of the VM in the API.

     https://mjsabiquo.lab.abiquo.com:443/api/cloud/virtualdatacenters/12/virtualappliances/4/virtualmachines/304
    • You can use this link to manage the VM in the API

    • The last element of the URL is the ID of the VM, which has a value of 304.




Create a VM using the API

To create a new VM:

  1. Create a POST request to the virtualmachines link

  2. Add headers to describe your JSON data objects 

    1. The Content-Type header refers to the VM object you are sending. 

    2. The Accept header refers to the API response you will receive

  3. Add your authentication (see the Authentication section above)
  4. As request data, you can add the VM entity from the previous step and change the name attribute, e.g., change  vmapihowto to vmapihowto2

  5. You can use a tool such as jq to format the API response

    curl -X POST 'https://mjsabiquo.lab.abiquo.com/api/cloud/virtualdatacenters/12/virtualappliances/4/virtualmachines' \
-H 'Accept: application/vnd.abiquo.virtualmachine+json;version=6.1' \
-H 'Authorization: Token XXXXXX' \
-H 'Content-Type: application/vnd.abiquo.virtualmachine+json;version=6.1' \
--data-raw '{"name":"vmapihowto2","links":[{"title":"yVM","rel":"virtualmachinetemplate","type":"application/vnd.abiquo.virtualmachinetemplate+json","href":"https://mjsabiquo.lab.abiquo.com:443/api/admin/enterprises/1/datacenterrepositories/2/virtualmachinetemplates/145"}],"vdrpEnabled":true}' \
--insecure --verbose | jq .
  6. Send the POST request 

If the API creates the machine successfully, the response code is 201 and the body contains the VM object.



To manage the VM, you will send requests to VM links, so you should now save some links from the VM object. It is also useful to know the ID of the VM in the API.

From the VM object,

  • Get the link with a rel key that has a value of edit. Also note that in the example the VM has an id of 305.

    ...
{  
   "links":[
...
    {
      "title": "vmapihowto2",
      "rel": "edit",
      "type": "application/vnd.abiquo.virtualmachine+json",
      "href": "https://mjsabiquo.lab.abiquo.com:443/api/cloud/virtualdatacenters/12/virtualappliances/4/virtualmachines/305"
    },
...

  • Also get the link with a rel key that has a value of deploy.

    ...
    {
      "title": "virtual machine deploy",
      "rel": "deploy",
      "type": "application/vnd.abiquo.acceptedrequest+json",
      "href": "https://mjsabiquo.lab.abiquo.com:443/api/cloud/virtualdatacenters/12/virtualappliances/4/virtualmachines/305/action/deploy"
    },
...



Display the VM in the UI

When you've created the VM, return to the UI and you should be able to find the new VM!  



Get the new VM using the API

To retrieve the details of the VM you just created, perform a GET request to the edit link of the VM.

curl --verbose 'https://mjsabiquo.lab.abiquo.com:443/api/cloud/virtualdatacenters/12/virtualappliances/4/virtualmachines/305' \
	-H 'Accept: application/vnd.abiquo.virtualmachine+json; version=6.1' \
	-u user:password -k | jq .

The result of this query is a VM data object in JSON format. To shorten the data object we replaced many of the links with an ellipsis (...).

√ ~ % curl --verbose 'https://mjsabiquo.lab.abiquo.com:443/api/cloud/virtualdatacenters/12/virtualappliances/4/virtualmachines/305' \ 
        -H 'Accept: application/vnd.abiquo.virtualmachine+json; version=6.1' \
        -u user:password -k | jq .
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:-- 
> GET /api/cloud/virtualdatacenters/12/virtualappliances/4/virtualmachines/305 HTTP/1.1
> Host: mjsabiquo.lab.abiquo.com
> Authorization: Basic XXXXXXXXX
> User-Agent: curl/7.82.0
> Accept: application/vnd.abiquo.virtualmachine+json; version=6.1
> 
{ [5 bytes data]
* Mark bundle as not supporting multiuse
< HTTP/1.1 200 200
< Date: Tue, 06 Jun 2023 09:44:33 GMT
< Server: Apache/2.4.6 (CentOS) OpenSSL/1.0.2k-fips
< Set-Cookie: ABQSESSIONID=5894817455706476983; Max-Age=1800; Expires=Tue, 06-Jun-2023 10:14:33 GMT; Path=/; Secure; HttpOnly; SameSite=strict
< X-Abiquo-TracerContext: 7a0c3949-f905-4eea-a071-12b783ed180e
< X-Abiquo-Token: XXXXXXXXXXXX
< Cache-Control: no-cache, no-store, max-age=0, must-revalidate
< Pragma: no-cache
< Expires: 0
< Strict-Transport-Security: max-age=31536000 ; includeSubDomains
< X-XSS-Protection: 1; mode=block
< X-Frame-Options: DENY
< X-Content-Type-Options: nosniff
< Content-Type: application/vnd.abiquo.virtualmachine+json; version=6.1
< Transfer-Encoding: chunked
< 
  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0{ [5 bytes data]
100  9452    0  9452    0     0  14513      0 --:--:-- --:--:-- --:--:-- 14496
* Connection #0 to host mjsabiquo.lab.abiquo.com left intact
{
  "id": 305,
  "uuid": "eb613c22-ffa1-4498-827a-ccaf37385c2e",
  "description": "A virtual machine",
  "coresPerSocket": 1,
  "idState": 1,
  "idType": 0,
  "type": "MANAGED",
  "highDisponibility": 0,
  "monitored": false,
  "protected": false,
  "variables": {},
  "backuppolicies": [],
  "generateGuestInitialPassword": false,
  "natrules": [],
  "vdrpEnabled": true,
  "vdrpPort": 0,
  "password": "6t51rgZ9",
  "deallocated": false,
  "name": "vmapihowto2",
  "ram": 48,
  "cpu": 1,
  "state": "NOT_ALLOCATED",
  "creationTimestamp": 1686042455000,
  "birthTimestamp": 1686042455000,
  "links": [
    {
      "title": "Abiquo",
      "rel": "enterprise",
      "type": "application/vnd.abiquo.enterprise+json",
      "href": "https://mjsabiquo.lab.abiquo.com:443/api/admin/enterprises/1"
    },
    {
      "title": "vmapihowto2",
      "rel": "edit",
      "type": "application/vnd.abiquo.virtualmachine+json",
      "href": "https://mjsabiquo.lab.abiquo.com:443/api/cloud/virtualdatacenters/12/virtualappliances/4/virtualmachines/305"
    },
   ...
   {
      "title": "yVM",
      "rel": "virtualmachinetemplate",
      "type": "application/vnd.abiquo.virtualmachinetemplate+json",
      "href": "https://mjsabiquo.lab.abiquo.com:443/api/admin/enterprises/1/datacenterrepositories/2/virtualmachinetemplates/145"
    },
    {
      "title": "Others",
      "rel": "category",
      "type": "application/vnd.abiquo.category+json",
      "href": "https://mjsabiquo.lab.abiquo.com:443/api/config/categories/1"
    }
  ],
  "usageStatistics": []
}



Get a group of VMs with the API

To retrieve the collection of VMs in a virtual appliance, send a GET request to the virtualmachines link of the virtual appliance.

Change the Accept header of the request to the virtual machines data object to receive a collection of virtual machines.

  

√ ~ % curl --verbose 'https://mjsabiquo.lab.abiquo.com:443/api/cloud/virtualdatacenters/12/virtualappliances/4/virtualmachines' \    
        -H 'Accept: application/vnd.abiquo.virtualmachines+json; version=6.1' \
        -u user:password -k | jq .


The response contains metadata about the size of the collection and the default paging links with some paging query parameters.

When you getting a collection of objects, you can also use query parameters to filter the response, for example, the has parameter can filter names by text.

Again, to reduce the size of the example, we replaced most of the VM links with an ellipsis (...).

{
  "totalSize": 2,
  "links": [
    {
      "rel": "first",
      "href": "https://mjsabiquo.lab.abiquo.com:443/api/cloud/virtualdatacenters/12/virtualappliances/4/virtualmachines?limit=25&by=name&asc=true"
    },
    {
      "rel": "last",
      "href": "https://mjsabiquo.lab.abiquo.com:443/api/cloud/virtualdatacenters/12/virtualappliances/4/virtualmachines?startwith=0&limit=25&by=name&asc=true"
    }
  ],
  "collection": [
    {
      "id": 304,
      "uuid": "1979e77f-32b1-430d-9b92-9f6347dbd416",
      "description": "A virtual machine",
      "coresPerSocket": 1,
      "idState": 1,
      "idType": 0,
      "type": "MANAGED",
      "highDisponibility": 0,
      "monitored": false,
      "protected": false,
      "variables": {},
      "backuppolicies": [],
      "generateGuestInitialPassword": false,
      "natrules": [],
      "vdrpEnabled": true,
      "vdrpPort": 0,
      "password": "uvlgwyFx",
      "deallocated": false,
      "name": "vmapihowto",
      "ram": 48,
      "cpu": 1,
      "state": "NOT_ALLOCATED",
      "creationTimestamp": 1686039246000,
      "birthTimestamp": 1686039246000,
      "links": [
        {
          "title": "Abiquo",
          "rel": "enterprise",
          "type": "application/vnd.abiquo.enterprise+json",
          "href": "https://mjsabiquo.lab.abiquo.com:443/api/admin/enterprises/1"
        },
        {
          "title": "vmapihowto",
          "rel": "edit",
          "type": "application/vnd.abiquo.virtualmachine+json",
          "href": "https://mjsabiquo.lab.abiquo.com:443/api/cloud/virtualdatacenters/12/virtualappliances/4/virtualmachines/304"
        },
        ...
      ],
      "usageStatistics": []
    },
    {
      "id": 305,
      "uuid": "eb613c22-ffa1-4498-827a-ccaf37385c2e",
      "description": "A virtual machine",
      "coresPerSocket": 1,
      "idState": 1,
      "idType": 0,
      "type": "MANAGED",
      "highDisponibility": 0,
      "monitored": false,
      "protected": false,
      "variables": {},
      "backuppolicies": [],
      "generateGuestInitialPassword": false,
      "natrules": [],
      "vdrpEnabled": true,
      "vdrpPort": 0,
      "password": "6t51rgZ9",
      "deallocated": false,
      "name": "vmapihowto2",
      "ram": 48,
      "cpu": 1,
      "state": "NOT_ALLOCATED",
      "creationTimestamp": 1686042455000,
      "birthTimestamp": 1686042455000,
      "links": [
        {
          "title": "Abiquo",
          "rel": "enterprise",
          "type": "application/vnd.abiquo.enterprise+json",
          "href": "https://mjsabiquo.lab.abiquo.com:443/api/admin/enterprises/1"
        },
        {
          "title": "vmapihowto2",
          "rel": "edit",
          "type": "application/vnd.abiquo.virtualmachine+json",
          "href": "https://mjsabiquo.lab.abiquo.com:443/api/cloud/virtualdatacenters/12/virtualappliances/4/virtualmachines/305"
        },
        ...
        }
      ],
      "usageStatistics": []
    }
  ]
}




Deploy your VM

To deploy the VM you created, send a POST request to the deploy link of the VM.

curl --verbose -X POST 'https://mjsabiquo.lab.abiquo.com:443/api/cloud/virtualdatacenters/12/virtualappliances/4/virtualmachines/305/action/deploy' \
-u user:password -k

The API will respond with an accepted request object and a link.

{
   "message":"You can keep track of the progress in the link",
   "links":[
      {
         "title":"status",
         "rel":"status",
         "type":"application/vnd.abiquo.task+json",
         "href":"https://mjsabiquo.lab.abiquo.com:443/api/cloud/virtualdatacenters/12/virtualappliances/4/virtualmachines/305/tasks/d18178fd-6a95-494c-8257-adda5c53f26f"
      }
   ]
}

To check the progress of the deploy, send a GET request to the above link.

Of course, you can also just switch back to the UI and watch the VM deploy!



Conclusion

Congratulations, you have created a VM and deployed a VM with the API.

You have also retrieved an entity and a collection of entities, and you can apply this method to any entity, using the entity link and a GET request.

To work through how to modify and delete entities, see Get Started with the Abiquo API part 2.


Related links

  • No labels

Copyright © 2006-2024, Abiquo Holdings SL. All rights reserved