The Event Center API

The Event Center API provides access to event data, available in the Luna Control Panel.

To implement cross-HTTP request optimistic locking, each event object sent from the server has a version stamp assigned to it. When performing an update operation (POST), the client must first load the event data from the server, perform some operation (such as allowing the user to change it), then POST it back to the server, including the same version stamp that was sent in the server response. For example, if the server sends a version of 12345, then the client must send back to the server version of 12345. If these versions do not match, then the data has been edited by another client and the server throws an error.

An event is optionally associated with a set of services. A service is any provisioned product that is part of this event. By default, the services associated with an event are not included in the response. Retrieving services can be done using the getEventWithServices method.

An event is optionally associated with tags. A tag can be user defined or global to all users. The Tag has a name and an associated account

The following is an example of an event definition in JSON format. Note that the services member is optional. This format is the same for all GET, PUT and POST methods, though certain methods require or ignore certain members (documented separately).

{
    "id": "20051",
    "customerEventId": "1234",      // See "Customer Event ID" section below.
    "version": 12,
    "name": "Test",
    "description": null,
    "eventType": "STREAMING",
    "customer": {
        "accountID": "1-7KLGH",
        "accountName": "Example Customer",
        "supportLevel": "STANDARD"
    },
    "start": 1338856200000,         // Note that all dates are in milliseconds
    "end": 1338868800000,
    "createdDate": 1338841117000,
    "createdBy": "ccare2",          // Luna username
    "modifiedDate": 1339528054000,
    "modifiedBy": "ccare2",         // Luna username
    "audienceSize": 10000,
    "audienceLocations": [],        // ISO country codes
    "coordinators": [],             // A list of usernames
    "locked": true,
    "tags": [
        { "name": "Public"        , "global": true },
        { "name": "Account Tag 3" , "global": true }
    ],
    "services": {
        "universalLiveStreams": [], // See note below for service JSON details.
        "flashLiveStreams": [],
        "siteCPCodes": [],
        "sripConfigs": [],
        "qosmReportPackIds": [],
        "smReportPackIds": [],
        "silverlightLiveStreams": []
    }
}

Query Events

To load a list of events, simply call /events/ws/api/v2/current-account/events. This returns all events on the current account.

To load a specific event, use the same URL above, but specify the event ID in the path: /events/ws/api/v2/current-account/events/{eventId}

Standard Query String Parameters

Most GET calls that load a list of events accept the following query string parameters, which can be used to limit the resulting list of events:

Parameter Description
startRange, endRange Specify a date range to only get events in that date range. Dates should be specified as epoch time, in milliseconds.
sortField The field that should be used to sort the result set. One of name, start, end, or accountName.
sortOrder The direction of the sort, either asc for ascending or desc for descending.
startIndex The zero-origin index at which this result set should start. Used for pagination.
limit The maximum number of events a GET could return.
customerEventId See Customer Event ID, below.

Creating and Updating Events

When creating and updating events, a subset of the JSON specified above should be included in the request body. The following is the minimum JSON required to create an event:

{
    "name": "Test",
    "start": 1338856200000,
    "end": 1338868800000
}

All other members are considered optional. This creates an event with no services, only with a start and end date. The server ignores the created*, modified*, customer and eventType members if sent in the request.

Note that the start and end date are specified in milliseconds, not seconds.

For example, the following cURL command creates an event:

curl -v -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -X PUT --user username:password https://luna.example.com/events/ws/api/v2/current-account/events -d "{\"name\": \"Test\",\"start\": 1361381326000,\"end\": 1361640526000}"

Be sure to replace username and password in the command with your Luna login, and luna.example.com with the correct Luna hostname, the same hostname you use when visiting Luna in the browser.

Customer Event ID

In the event JSON, use the customerEventId member to store any string up to 100 characters. Use this member to store a more meaningful identifier than the Event Center’s ID.

Beyond the 100 character limit, there is no restriction on this member’s value, however it’s best to keep the string simple. Additionally, there is no unique restriction on the field; multiple events may share the same event ID. This allows customer events to include many Event Center events.

Querying Events by Customer Event ID

Once an event has its customerEventId field populated, it’s possible to get all events with a given customerEventId value. For example, /events/ws/api/v2/current-account/events?customerEventId=abc&customerEventId=1234 gets all events with a customerEventId value of abc or 1234. One or more customerEventId query string parameters can be added.

Since customerEventId can contain any characters, be sure to URL-encode the query string value when making the request.

Mapping Customer Event ID to Event Center ID

It’s often useful to map a customer event ID to Event Center IDs. This operation returns only an array of integer Event Center IDs, which is easier to work with than loading the entire event object. Take for example, the given URL: /events/ws/api/v2/1-7KLGH/events/id?customerEventId=1234. Notice the path ends with /id. This return the Event Center IDs that have a customerEventId field with the value 1234.

{
    "status": "ok",
    "contents": [
       100100,
       103201
    ]
}

In the example above, customerEventId is mapped to two Event Center IDs, since one-to-one mappings are not enforced for customerEventId. Normally, one event ID corresponds to a unique customerEventId.


Last modified: 10/17/2016