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. It allows customers to drive external systems or processes based on activity on the Abiquo platform. For example, you may want to be notified when a new VM is deployed 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

Abiquo supports OAuth authentication to the streaming API. You should sign a request to ''endpoint/api/login'' and use this header in the request to M.

Consuming the streaming API

The streaming API can be used to subscribe to a set of Events, so you can receive all events that interest you in "real time".

The following example shows a subscription request using Server-Side Events as the streaming transport. The subscription does not specify any filter, so by default all Events will be received in "real time".

Note that there are also specific Atmosphere query parameters in the request. Please see the Atmosphere documentation for a complete reference of all available parameters used to configure the streaming connection.

Streaming API example

curl -u user:password -X GET "https://abiquo.example.com/m/stream?X-Atmosphere-tracking-id=e24de98c-6624-c552-5572-6edbffd270e3&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}

During the subscription, a virtual datacenter was created and a VM was deployed, and all events were received in real-time on the client side.

You can refine your subscriptions to receive only the events you are interested in. The following query parameters are available:

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.
action	The action performed on the "entity"	CREATE, DEPLOY, DELETE, etc.
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

For a full list of all entities and actions that will generate events in Abiquo, see Events Table

Traces related to events on the platform can be found in the Abiquo Logs

The Events Table contains all events including the Trace column that contains the messages created by the tracers and registered in the catalina.out log.

The following examples show several subscriptions to receive a subset of events in real time. Atmosphere query parameters are needed but have been removed from the examples to make them easier to read. Remember to configure all the parameters if you are going to test the examples, and you may also require the insecure option for test systems:

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"

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.

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

Click here to show/hide the Trace entity description

Trace entity attributes table

Attribute	Description
action	The action performed. See Events Table
context	The tracer context that the event belongs too. 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. See Events Table
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.