Abiquo outbound API

Outbound API

The Abiquo Outbound API (the "M" module) is a streaming API that 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 http://async-io.org/ and 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.

Open

Outbound API architecture

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:

1. Create an application in Abiquo. See Add an application for OAuth. Keep the application details to use in the next step.

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

   1. Use the same API endpoint as the '''abiquo.server.api.location''' that is set in your abiquo.properties file

   2. 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"

   
   
   

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

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

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

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.

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.

Example of how to run the queries with Atmosphere parameters:

These examples show how to use the basic subscription parameters. To run them, you should add the appropriate Atmosphere parameters.

Subscription examples

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.

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.

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 of trace entity

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:

Abiquo API Reference

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.

Trace entity attributes table

The platform streams events as trace entities. 

For example

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.