Table of Contents

Introduction

The Event Data API provides a service to:

• Scalably collect event based data (the client submits the data)
• Consuming organized feeds of events

Event data is the fuel that drives analytics applications. Event data describes both entities and the actions performed by entities (for example, "Consume a licence"). Event data contains three key pieces of information, sometimes called behavior data:

1. Action
2. Timestamp
3. State

The action is the thing that's happening (e.g., "consume"). The timestamp is the time at which the event happened. The state refers to all of the other relevant information we know about this event, including information about entities related to the event, such as the consumer of the license, and the license type.

Typically in the context of 10Duke authentication or licensing solution, as a developer you will have access to the 10Duke Event Data API. If you’re not sure how to access the API, please contact 10Duke technical support.

System diagram

The following diagram gives a high level overview of the web APIs and their relation to surrounding components.

Introduction to Interfaces

External (public) Interfaces

Event API

Event API is the API used to submit new events.

Feed API

Feed API is used to consume feeds produced by the system. Feeds are provided based on the event source identifier. The event feed identifier is a field in events submitted via the Event API.

Authorization

The Event API uses JSON Web Signatures (JWS) for authorizing requests and to convey the data.

The JWS specification is ​https://tools.ietf.org/html/rfc7515, and ​http://jwt.io/ has more information and JWT / JWS tools.

Signing and validating tokens / signatures

JWS data is signed using a private key in the client system. The corresponding public key is configured in the Event Feed Service so that it can verify the authenticity and integrity of the client requests.

RS256 is the algorithm name to use with JWS

Resolving public keys

In order to validate a token signature the Event Feed Service must find the correct public key. The correct public key is accessed based on knowing the tenant for which the request is made. The related tenant is resolved based on hostname.

Key management and validation process

Keypair generation and management

PEM / PKCS#8 format is the key format used by the Event Feed Service.

Posting authorized events

Event API (inbound events)

Event data is expressed using JSON, enveloped in a signed JWS structure. Content-Type for sending events is:

Content-Type: application/jose

Event data can be POSTed to the inbound events API as single JSON objects, one event at a time, or as a JSON array containing multiple events. For authorizing the events, the signature of the JWS envelope is verified by the server.

Feed API

The Feed API is used for reading events stored in the service.

The HTTP call format is:

https://{tenantName}.events.10duke.com/get/{eventSourceId}

Here, {eventSourceId} refers to the feed id and {tenantName} is the tenant name. If using a customer dedicated deployment, events.10duke.com is replaced with DNS name of the deployment.

The feed requests are authorized by supplying a JWT authorization token in the Authorization header using the Bearer schema. The token body for the authorization token is:

{
    "iat": 1554379811,
    "exp": 1554379871,
    "{eventSourceId}": true
}

Here, the iat claim is optional. The {eventSourceId} can be replaced either by the event source id / feed id, or by an asterisk (*) for allowing access to any feed.

Send and read events, HTTP requests

Step 1: Send an event to the Event Data Service

    POST /put HTTP/1.1
    Host: ​{EVENT DATA SERVICE HOST}
    Content-Type application/jose

    [BASE64 Encoded JWS with event data]

Step 2: Request to feed by id my-app-events

    GET /get/my-app-events HTTP/1.1
    Host: {EVENT DATA SERVICE HOST}

Alternative that defines timestamp to start at

    GET /get/my-app-events?after={epoch nanos} HTTP/1.1
    Host: {EVENT DATA SERVICE HOST}

Alternative that defines timestamp to end at

    GET /get/my-app-events?before={epoch nanos} HTTP/1.1
    Host: {EVENT DATA SERVICE HOST}

Alternative that defines timestamp to start at and max events count

    GET /get/my-app-events?after={epoch nanos}&maxEventCount=10 HTTP/1.1
    Host: {EVENT DATA SERVICE HOST}