Abiquo 5.0

Skip to end of metadata
Go to start of metadata

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

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:

NameDescriptionExample values
severityThe severity of the eventsINFO, WARN, ERROR
entityThe entity that originated the eventDATACENTER, RACK, VIRTUAL_MACHINE, etc.
actionThe action performed on the "entity"CREATE, DEPLOY, DELETE, etc.
userThe "id" of the user who generated the event1, 2, 25, system, etc.
enterpriseThe "id" of the enterprise generating the event

1, 2, 25, etc. 

scopeThe scope of the eventVIRTUALDATACENTER, 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 ScopeOutbound APIDefault roles
No event privilegesUser 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 scopeAll events including SYSTEM eventsCloud admin
Display all events + limited scopeAll 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 with attributes as described in the table below. The format of events in the stream is also the same as the events returned by the Abiquo API with the Event Media Type.

The format of events in the Abiquo UI is also described at Events View

 Click here to expand...

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

userURIURI 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.