Abiquo Outbound API

Outbound API

The Abiquo Outbound API (the "M" module) listens for events from Abiquo and broadcasts them to connected clients.

The Abiquo Outbound API aims to help third-party software providers to develop software for integration with the Abiquo platform. You can drive external systems or processes based on activity on the Abiquo platform. For example, you could set up a notification when a user deploys a VM, in order to update an asset management register. Users can subscribe to a specific event, a set of events, or all events. Users will need to have access to the Abiquo API and privileges to access events. Abiquo customers and their cloud customers can subscribe to the events they have permission to access.

Specifications

EVENT_TYPES:
- INFO
- WARNING
- ERROR
Event scope allows you to filter by error type, etc:
- Platform error
- DC error
- VDC error
Events published with Atmosphere streaming . See also https://github.com/Atmosphere/atmosphere/wiki
Tracer information
Different integration examples can be provided in major programming languages

The following diagram shows the basic architecture of the Outbound API.

Authentication

You can use the streaming method with any authentication method supported for login to Abiquo. See Authentication

Authenticate with OAuth

This section describes how to use OAuth. When using OAuth, M redirects the client authorization header to the API to check if it is valid to login.

To create the OAuth signature, do these steps:

Create an application in Abiquo. See Add an application for OAuth(https://wiki.abiquo.com/display/doc/Add+an+application+for+OAuth). Keep the application details to use in the next step.

Use the Abiquo oauth-utils.jar (https://github.com/abiquo/tools/tree/master/oauth#example-sensible-info-password-and-api-secret-interactive) to authorize the application. Contact Abiquo Support to obtain this tool.

Use the same API endpoint as the '''abiquo.server.api.location''' that is set in your abiquo.properties file
Create the signature to access ''endpoint/api/login?expand=privileges''

java -jar oauth-utils.jar authorize -url "https://abiquo.example.com/api" -u "admin"  -k "72c2c13b-a1b5-4ed8-a61b-f2eed5fd390f" -s "UBkwTbN5jeBaYA8u7yOJOXLGC8RYQPsrY8FCfatM" -p "xabiquo"

The authorization response will be something like this

Authorising the application...
Access token: 2588502d-eecf-4726-84ba-f05fdcc41850
Access token secret: QQuMEtiMopzLb460aJh6gGm3w4B07tYB9shIA+Kkxjwz+cdzyYcTXE+N1cypaHP1mr14CkypMZF2fL1cupqx9RywPGimERzqc7/6XUP9hAM=
Example signature to login: OAuth oauth_nonce="228300125", oauth_signature="72qeAJmR%2FTIASXqJ1X%2BEdJHK9R0%3D", oauth_token="2588502d-eecf-4726-84ba-f05fdcc41850", oauth_consumer_key="72c2c13b-a1b5-4ed8-a61b-f2eed5fd390f", oauth_timestamp="1573046648", oauth_signature_method="HMAC-SHA1", oauth_version="1.0"

From the last line of the response, get the Example signature to login to the Abiquo API, starting with "OAuth "

Add it to your requests to M as part of the header with a key of "Authorization: "

Authorising the application...
Access token: 2588502d-eecf-4726-84ba-f05fdcc41850
Access token secret: QQuMEtiMopzLb460aJh6gGm3w4B07tYB9shIA+Kkxjwz+cdzyYcTXE+N1cypaHP1mr14CkypMZF2fL1cupqx9RywPGimERzqc7/6XUP9hAM=
Example signature to login: OAuth oauth_nonce="228300125", oauth_signature="72qeAJmR%2FTIASXqJ1X%2BEdJHK9R0%3D", oauth_token="2588502d-eecf-4726-84ba-f05fdcc41850", oauth_consumer_key="72c2c13b-a1b5-4ed8-a61b-f2eed5fd390f", oauth_timestamp="1573046648", oauth_signature_method="HMAC-SHA1", oauth_version="1.0"

Subscribe to all events from the streaming API

You can subscribe to a set of Events from the streaming API, so you can receive all events that interest you in "real time".

To test the streaming API, you can use the following cURL request with Atmosphere query parameters. You may also need to use the "-k" insecure option for cURL in your test environment.

For a complete reference of Atmosphere query parameters, please see the Atmosphere documentation.

When you run this cURL request in a shell, the stream of events from your Abiquo platform will display below as "data" elements.

Streaming API example

curl --verbose -uuser:password -XGET "https://abiquo.example.com/m/stream?X-Atmosphere-Framework=1.0&X-Atmosphere-Transport=sse"

data:{"action":"CREATE","context":"024c42a6-a9a2-4fd8-906f-cf7df3f02371","enterpriseName":"Abiquo","enterpriseURI":"/api/admin/enterprises/1","entity":"VIRTUAL_DATACENTER","entityEnterpriseName":"Abiquo","entityEnterpriseURI":"/api/admin/enterprises/1","entityMediaType":"application/vnd.abiquo.virtualdatacenter+json","entityName":"vmware_vdc","entityURI":"/api/cloud/virtualdatacenters/4","errorCode":null,"errorMessage":null,"exception":null,"message":"Virtual datacenter 'vmware_vdc' has been created.","severity":"INFO","tags":["virtualdatacenter:4","user:1","enterprise:1"],"timestamp":1573130105514,"userName":"admin","userURI":"/api/admin/enterprises/1/users/1"}

data:{"action":"CREATE","context":"640bada2-4dab-4d39-96da-d6f200ec4f89","enterpriseName":"Abiquo","enterpriseURI":"/api/admin/enterprises/1","entity":"VIRTUAL_APPLIANCE","entityEnterpriseName":"Abiquo","entityEnterpriseURI":"/api/admin/enterprises/1","entityMediaType":"application/vnd.abiquo.virtualappliance+json","entityName":"vmware_vapp","entityURI":"/api/cloud/virtualdatacenters/4/virtualappliances/4","errorCode":null,"errorMessage":null,"exception":null,"message":"Virtual appliance 'vmware_vapp' has been created.","severity":"INFO","tags":["virtualdatacenter:4","virtualappliance:4","user:1","enterprise:1"],"timestamp":1573130121886,"userName":"admin","userURI":"/api/admin/enterprises/1/users/1"}

data:{"action":"CREATE","context":"d33900c0-76ce-410f-92f5-b4163cadc008","enterpriseName":"Abiquo","enterpriseURI":"/api/admin/enterprises/1","entity":"VIRTUAL_MACHINE","entityEnterpriseName":"Abiquo","entityEnterpriseURI":"/api/admin/enterprises/1","entityMediaType":"application/vnd.abiquo.virtualmachine+json","entityName":"ABQ_551250b8-08d9-48ae-b384-fe4634a3bee2","entityURI":"/api/cloud/virtualdatacenters/4/virtualappliances/4/virtualmachines/177","errorCode":null,"errorMessage":null,"exception":null,"message":"The virtual machine 'ABQ_551250b8-08d9-48ae-b384-fe4634a3bee2' was created successfully.","severity":"INFO","tags":["virtualmachine:177","virtualdatacenter:4","virtualappliance:4","user:1","enterprise:1"],"timestamp":1573130133360,"userName":"admin","userURI":"/api/admin/enterprises/1/users/1"}

data:{"action":"DEPLOY","context":"a2d4e23c-b287-47f6-8e3f-cb6d382cc924","enterpriseName":"Abiquo","enterpriseURI":"/api/admin/enterprises/1","entity":"VIRTUAL_APPLIANCE","entityEnterpriseName":"Abiquo","entityEnterpriseURI":"/api/admin/enterprises/1","entityMediaType":"application/vnd.abiquo.virtualappliance+json","entityName":"vmware_vapp","entityURI":"/api/cloud/virtualdatacenters/4/virtualappliances/4","errorCode":null,"errorMessage":null,"exception":null,"message":"Virtual appliance 'vmware_vapp' is being deployed.","severity":"INFO","tags":["virtualdatacenter:4","virtualappliance:4","user:1","enterprise:1"],"timestamp":1573130145216,"userName":"admin","userURI":"/api/admin/enterprises/1/users/1"}

data:{"action":"ASSIGN","context":"a2d4e23c-b287-47f6-8e3f-cb6d382cc924","enterpriseName":"Abiquo","enterpriseURI":"/api/admin/enterprises/1","entity":"VLAN_TAG","entityEnterpriseName":"Abiquo","entityEnterpriseURI":"/api/admin/enterprises/1","entityMediaType":null,"entityName":null,"entityURI":null,"errorCode":null,"errorMessage":null,"exception":null,"message":"VLAN tag '2' has been assigned to VLAN network 'default_private_network' from virtual datacenter 'vmware_vdc'.","severity":"INFO","tags":["user:1","enterprise:1"],"timestamp":1573130147488,"userName":"admin","userURI":"/api/admin/enterprises/1/users/1"}

data:{"action":"DEPLOY_FINISH","context":"a2d4e23c-b287-47f6-8e3f-cb6d382cc924","enterpriseName":"Abiquo","enterpriseURI":"/api/admin/enterprises/1","entity":"VIRTUAL_MACHINE","entityEnterpriseName":"Abiquo","entityEnterpriseURI":"/api/admin/enterprises/1","entityMediaType":"application/vnd.abiquo.virtualmachine+json","entityName":"ABQ_551250b8-08d9-48ae-b384-fe4634a3bee2","entityURI":"/api/cloud/virtualdatacenters/4/virtualappliances/4/virtualmachines/177","errorCode":null,"errorMessage":null,"exception":null,"message":"Deploy on virtual machine 'ABQ_551250b8-08d9-48ae-b384-fe4634a3bee2' completed. Scheduled in hypervisor '10.60.2.43' ('VMware vCenter') at IP '10.60.2.43'.","severity":"INFO","tags":["virtualmachine:177","virtualdatacenter:4","virtualappliance:4","user:1","enterprise:1"],"timestamp":1573130228944,"userName":"admin","userURI":"/api/admin/enterprises/1/users/1"}

data:{"action":"ALLOCATE_NICS","context":"a2d4e23c-b287-47f6-8e3f-cb6d382cc924","enterpriseName":"Abiquo","enterpriseURI":"/api/admin/enterprises/1","entity":"VIRTUAL_MACHINE","entityEnterpriseName":"Abiquo","entityEnterpriseURI":"/api/admin/enterprises/1","entityMediaType":"application/vnd.abiquo.virtualmachine+json","entityName":"ABQ_551250b8-08d9-48ae-b384-fe4634a3bee2","entityURI":"/api/cloud/virtualdatacenters/4/virtualappliances/4/virtualmachines/177","errorCode":null,"errorMessage":null,"exception":null,"message":"Virtual machine 'ABQ_551250b8-08d9-48ae-b384-fe4634a3bee2' has attached the NIC associated with IP Address '192.168.0.2' in VLAN 'default_private_network'.","severity":"INFO","tags":["virtualmachine:177","virtualdatacenter:4","virtualappliance:4","user:1","enterprise:1"],"timestamp":1573130228948,"userName":"admin","userURI":"/api/admin/enterprises/1/users/1"}

data:{"action":"ALLOCATE_HD","context":"a2d4e23c-b287-47f6-8e3f-cb6d382cc924","enterpriseName":"Abiquo","enterpriseURI":"/api/admin/enterprises/1","entity":"VIRTUAL_MACHINE","entityEnterpriseName":"Abiquo","entityEnterpriseURI":"/api/admin/enterprises/1","entityMediaType":"application/vnd.abiquo.virtualmachine+json","entityName":"ABQ_551250b8-08d9-48ae-b384-fe4634a3bee2","entityURI":"/api/cloud/virtualdatacenters/4/virtualappliances/4/virtualmachines/177","errorCode":null,"errorMessage":null,"exception":null,"message":"The hard disk resource of '64' MB has been assigned to virtual machine 'ABQ_551250b8-08d9-48ae-b384-fe4634a3bee2'.","severity":"INFO","tags":["virtualmachine:177","virtualdatacenter:4","virtualappliance:4","user:1","enterprise:1"],"timestamp":1573130228952,"userName":"admin","userURI":"/api/admin/enterprises/1/users/1"}

data:{"action":"VSM_CHANGE_STATE","context":"b1b17027-e262-4ce5-bb93-b72176d6e5c5","enterpriseName":null,"enterpriseURI":null,"entity":"VIRTUAL_MACHINE","entityEnterpriseName":"Abiquo","entityEnterpriseURI":"/api/admin/enterprises/1","entityMediaType":"application/vnd.abiquo.virtualmachine+json","entityName":"ABQ_551250b8-08d9-48ae-b384-fe4634a3bee2","entityURI":"/api/cloud/virtualdatacenters/4/virtualappliances/4/virtualmachines/177","errorCode":null,"errorMessage":null,"exception":null,"message":"State of virtual machine 'ABQ_551250b8-08d9-48ae-b384-fe4634a3bee2' updated to 'ON'.","severity":"INFO","tags":["virtualmachine:177","virtualdatacenter:4","virtualappliance:4","enterprise:1"],"timestamp":1573130232206,"userName":null,"userURI":null}

When the subscription was active and streaming events, the users created a virtual datacenter and deployed a VM!

The above example shows a subscription request using Server-Side Events as the streaming transport ("sse").

The subscription does not specify a filter, so by default all Events were received in "real time".

Filter your event subscription

Abiquo can generate over 800 events for more than 80 entities! We publish a general guide to events in the Events Table, which we update for each major version of the platform.

You can filter your subscriptions to receive only the events you are interested in using query parameters.

Name	Description	Example values
severity	The severity of the events	INFO, WARN, ERROR
entity	The entity that originated the event	DATACENTER, RACK, VIRTUAL_MACHINE, etc. To obtain a full list of current entities, list event types from the Events Resource in the Abiquo API.
action	The action performed on the "entity"	CREATE, DEPLOY, DELETE, etc. To obtain a full list of current actions, list event types from the Events Resource in the Abiquo API.
user	The "id" of the user who generated the event	1, 2, 25, system, etc.
enterprise	The "id" of the enterprise generating the event	1, 2, 25, etc.
scope	The scope of the event	VIRTUALDATACENTER, ENTERPRISE, DATACENTER, PLATFORM

Notes about filters using query parameters:

When you combine filters, the platform separates them with an AND operator
To add multiple values for a filter, separate the values with a comma

Events also create traces in the Abiquo Logs. In the Events Table, the "Tracer" column contains the messages created by the tracers that are also registered in the catalina.out log.

Examples of event subscriptions

The following examples show several subscriptions to receive a subset of events in real time.

These examples won't work directly! To make the examples easier to read, we removed the required Atmosphere query parameters.
To test the examples, remember to add the Atmosphere parameters again, for example, the first example could be run as follows.

curl -u <user>:<password> -X GET "https://<abiquo.example.com>/m/stream?severity=info&X-Atmosphere-Framework=1.0&X-Atmosphere-Transport=sse" -k

Here we also used the "-k" insecure option for test systems.

These examples show how to use the basic subscription parameters.

Subscription examples

# Subscribe to all info messages
curl -u <user>:<password> -X GET "https://localhost/m/stream?severity=info"

# Subscribe to all warn and error messages
curl -u <user>:<password> -X GET "https://localhost/m/stream?severity=warn,error"

# Subscribe to all info messages related to virtual machines
curl -u <user>:<password> -X GET "https://localhost/m/stream?severity=info,entity=VIRTUAL_MACHINE"

# Subscribe to all warning and error messages originated by deploy actions in enterprise 3
curl -u <user>:<password> -X GET "https://localhost/m/stream?severity=warn,enterprise=3,action=DEPLOY"

# Subscribe to all error messages with virtual datacenter scope
curl -u <user>:<password> -X GET "https://localhost/m/stream?scope=virtualdatacenter"

To subscribe to all messages for enterprise creation, you could run the following query. When you create an enterprise the platform will generate a message with data as shown in this example.

curl -u <user>:<password> -X GET "https://<abiquo.example.com>/m/stream?entity=ENTERPRISE&action=CREATE&X-Atmosphere-Framework=1.0&X-Atmosphere-Transport=sse" -k

data:{"action":"CREATE","context":"9a328d11-1856-41b0-9b81-a1ddd9d971b4","enterpriseName":"Google Susana","enterpriseURI":"/api/admin/enterprises/16","entity":"ENTERPRISE","entityEnterpriseName":"MJenterprise2","entityEnterpriseURI":"/api/admin/enterprises/28","entityMediaType":"application/vnd.abiquo.enterprise+json","entityName":"MJenterprise2","entityURI":"/api/admin/enterprises/28","errorCode":null,"errorMessage":null,"exception":null,"message":"Enterprise 'MJenterprise2' has been created.","severity":"INFO","tags":["user:10","enterprise:16","enterprise:28"],"timestamp":1622065295935,"userName":"cloudadmin","userURI":"/api/admin/enterprises/16/users/10","idDatacenter":null}

Note that this event may be a little confusing because "enterpriseName" refers to the enterprise that the user is logged into ("Google Susana"), and the entity is the enterprise that the user created, which is referred to as "entityEnterpriseName" with a value of "MJenterprise2".

User Access to Events

A user can display the events for which their role has privileges, as listed in the Events Table. This access is combined with the User event privileges from Abiquo as described in the following table.

Privilege and Scope	Outbound API	Default roles
No event privileges	User events only
Display all events for current enterprise	All enterprise events, including Infrastructure events. For example, if cloud admin creates a rack while using (switched to) this enterprise, then the enterprise admin will see this event	Cloud admin, Ent Admin, Ent User
Display all events + global scope	All events including SYSTEM events	Cloud admin
Display all events + limited scope	All events for the locations and enterprises in scope

Recovering Missed Events

If the third-party system goes down, customers can recover any events lost during downtime by retrieving events using the REST API and filtering them by time stamp. See EventsResource

Event Format

The Trace entity is a JSON object that has the same format as the events returned by the Abiquo API with the Event Media Type.

Changes to this media type will be documented in the API changelog. To go directly to the changelog between versions, enter the from and to versions in the URL as shown in the following example:

https://wiki.abiquo.com/api/changelog/4.7.0_to_5.1.0.html

The format of events in the Abiquo UI is also described in Events View and the events are described in the Events Table, which is updated for major versions of Abiquo.

Click here to show/hide the Trace entity description

Trace entity attributes table

Attribute	Description
action	The action performed. To obtain a full list of current actions, list event types from the Events Resource in the Abiquo API.
context	The tracer context that the event belongs to. The platform assigns a single context ID to related events
enterpriseName	Name of the current enterprise of the user who performed the action
enterpriseURI	URI of the current enterprise of the user who performed the action
entity	Entity type. To obtain a full list of current entities, list event types from the Events Resource in the Abiquo API.
entityEnterpriseName	Name of the enterprise that the entity belongs to
entityEnterpriseURI	URI of the enterprise that the entity belongs to
entityMediaType	Entity media type. See media types in the API documentation at https://wiki.abiquo.com/api/latest
entityName	Entity name
entityURI	Entity URI
errorCode	If the severity is ERROR or WARNING, then this optionally contains an Abiquo API error code, see API Error Code List
errorMessage	If the severity is ERROR or WARNING, then this optionally contains an Abiquo API error message, see API Error Code List
exception	If the severity is ERROR, then this optionally contains the Java exception
message	The message
severity	The severity
tags	Collection of tags that describes the entity
timestamp	The timestamp of the time when the event took place. Expressed in the number of milliseconds since the epoch of 1970-01-01T00:00:00Z
userName	Name of the user who performed the action
userURI	URI of the user who performed the action

The platform streams events as trace entities.

For example

{
   "action":"CREATE",
   "context":"024c42a6-a9a2-4fd8-906f-cf7df3f02371",
   "enterpriseName":"Abiquo",
   "enterpriseURI":"/api/admin/enterprises/1",
   "entity":"VIRTUAL_DATACENTER",
   "entityEnterpriseName":"Abiquo",
   "entityEnterpriseURI":"/api/admin/enterprises/1",
   "entityMediaType":"application/vnd.abiquo.virtualdatacenter+json",
   "entityName":"vmware_vdc",
   "entityURI":"/api/cloud/virtualdatacenters/4",
   "errorCode":null,
   "errorMessage":null,
   "exception":null,
   "message":"Virtual datacenter 'vmware_vdc' has been created.",
   "severity":"INFO",
   "tags":[
      "virtualdatacenter:4",
      "user:1",
      "enterprise:1"
   ],
   "timestamp":1573130105514,
   "userName":"admin",
   "userURI":"/api/admin/enterprises/1/users/1"
}

Java Stream Client

The Abiquo Java Stream Client is available with the API Java Client to help developers build integrations with the Outbound API. The API Stream Client supports OAuth authentication to enable secure connections. The Java Stream Client will enable developers to build event-based integrations and it complements the API Java Client.