The 10Duke Event Data API Developer Guide
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:
- Action
- Timestamp
- 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.
Public key algorithm | RSA, minimum key length 2048 bits |
Hash algorithm | SHA-256 |
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}