Alooma supports quite a few different input sources via native connections. But there are hundreds more data sources out there, with more being created all the time. One possible solution for connecting these other inputs is connecting via a REST API. For example, you can use Alooma’s REST API support to configure an input for many streaming data services.
Alooma's REST API support provides a way to connect a wide range of REST APIs that conform to a basic structure, and pull events from those endpoints directly to Alooma.
The basic procedure is to "create an Application" or some kind of credentials in the service. Then use that to add a REST API input in Alooma and configure the endpoint parameters.
Set up a REST API integration in a few simple steps:
- Add a new REST API input from Alooma's plumbing screen.
- Give your input a name. The name will appear in the plumbing screen, and will name the events that the input emits.
- Supply the entire URL of the API, including http:// or https://.
- Choose the appropriate HTTP method (GET or POST).
- Optionally, enter your username and password (the input only supports basic HTTP authentication).
- Select the pagination method that your target API requires:
- None, if your API does not require pagination.
- Simple pagination (see example), where every request includes which page the request is for, and every response includes the next page's identifier (if another page exists).
- Next Result Key - Indicates the name of the next page parameter in the response body.
- Page Parameter - Indicates the name of the parameter in the API request used to specify the next page identifier.
- Sessioned pagination, where every request includes the ID of the session, and subsequent requests are for the next page, incrementally.
- ID Key - Indicates the name of the session ID parameter in the response body of the first call to the API.
- Session Parameter - Indicates the parameter name in the subsequent API calls where the session ID should be inserted.
- Optionally, define any parameters that the API requires passed. For each parameter, specify the Parameter name, Parameter value, and Parameter type. Parameter type can be:
Add as many parameters as you want, using the "add another parameter" option.
- Text - a generic parameter passed in the URL.
- Days Past - a dynamic parameter which auto-populates with a date generated based on the number of days back from today's date. For example, if you enter "3", the API URL when called on January 5, 2017 will include the date January 2, 2017.
- Optionally, define the data field where the interesting return data resides in the response.
- If the field comes back with an array of values, a separate event will be generated for each value in the array.
- If you do not choose a field, the entire body of the response will arrive in the event.
- Under advanced options, you can also:
- Optionally, define any headers that the API requires passed. Define headers just like parameters, above. You can add as many headers as you choose using the "add another header" option.
- Choose how often you'd like Alooma to connect to the endpoint for new data (default is every 30 min).
That's it! You're ready to connect your REST APIs to Alooma!
An example of simple pagination, given the following snippet from the REST API response:
If the JSON response body contains something like:
"next_page" would go into
Next Result Key, as this is the parameter that contains the value to include in the request for the next page.
"page" would go into
Page Parameter, as this is where we need to set the value for the next page in the subsequent request. And so the next request URL would look something like this: