UDP Caliper endpoint

The UDP Caliper endpoint is a web service that captures behavior data emitted by learning applications. It runs in a Kubernetes cluster and is responsible for accepting, authenticating, and validating behavioral data that conforms with the IMS Global Caliper standard.

The UDP Caliper endpoint supports a standard method of posting behavioral event stream data to the UDP, which is described below. The UDP Caliper endpoint also supports custom event stream integrations with certain Learning Management Systems, such as the Canvas LMS, which are not described below (see our documentation on LMS data integrations to the UDP for more information).

The UDP installation process will automatically configure the web service to be exposed on the public web behind a user-friendly hostname. During the installation process, you will specify a hostname for the service.

Authentication

The UDP Caliper endpoint authenticates the identity of every message posted to its web service.

Token-based authentication

The UDP Caliper endpoint uses token-based authentication, meaning that learning tools posting events to the UDP Caliper endpoint must include a valid token in its HTTP header request. If a Caliper event envelope is posted without a valid authentication token, it will be rejected by the Caliper endpoint.

A token-based authentication method is recommended by the Caliper 1.1 specification. Per the specification, a Caliper sensor (which emits events):

Token-based authentication

SHOULD ... set the Authorization request header field using the "Bearer" authentication scheme described in RFC 6750, Section 2.1. The b64token authorization credential sent by a Sensor MUST be one the Endpoint can validate although the credential MAY be opaque to the emitting Sensor itself.

An example header for a Caliper message sent over HTTPS would therefore look like this:

POST /caliper-endpoint HTTP/1.1
Host: server.example.com
Authorization: Bearer [some_granted_token]

Every time an event is posted to the UDP Caliper endpoint, the "Authorization:" header in the request is inspected and a token is extracted. The token is then compared to a list of configured tokens, called the UDP token map, to determine if the event is valid.

Token map

The Caliper endpoint’s token map is an encrypted YAML file that is initialized during the UDP installation process. The token map is composed of key-value pairs that associate a particular token (usually a long, complex string) with a particular learning tool. It is strongly encouraged that tokens are never re-used across tools and UDP instances.

A sample token map may look like this:

tenant_tokenmap:
 edu:
 - id: iClicker
   token: LDbzS7lOirWY4FPeoT2RdHq77jfCFPNjDjcjU1JvEDr49UeL1nOI0c94Sp0kDwjR
 - id: TopHat
   token: hVZ1r3s00UM54h8pIWeXgHoCNFSBQn96zAG9hks283DqfM7zg6nAoBJotqlaDIgR
 - id: Kaltura
   token: G1CY74pifk5ngF3L35L7GltIV270UOcYGhLTwpiKUnjPRHFGcG8CdDXLM1X0uEeC

In this example token map, a UDP instance configured with a shortcode of "edu" for the academic institution is using three distinct tokens to accept event data from three distinct learning tools: Kaltura, TopHat, and Macmillan iClicker. On their side, these three applications must be configured to include their respective tokens in their Caliper event data integrations to the UDP instance. If a fourth application were added, a new token should be generated and configured in the token map.

Responses

The UDP Caliper endpoint implements a set of behaviors that enable a learning tool’s Caliper sensor to understand whether its events have been authenticated and accepted by a UDP instance. Furthermore, the UDP Caliper endpoint implements a set of debugging behaviors that can be useful for implementing your Caliper sensor.

In a production environment, we recommend that the Caliper endpoint is run without debugging mode turned on. Keeping the responses terse enables the UDP Caliper endpoint to be more performant at scale. We call these "common" responses (see below).

In a pre-production environment, it is likely useful to run the UDP Caliper endpoint in debug/verbose mode (see below). In this mode, the responses are more informative and intended to aid in debugging your Caliper event stream integration.

Finally, whether running in production or verbose mode, the UDP Caliper endpoint's response will always, if the events are authenticated, describe how an event was routed for processing.

HTTP status codes

The endpoint may return different status codes depending on the results of authentication and validation.

HTTP request errors:

• 401 - Unauthorized

• 415 - Unsupported Media Type. The JSON payload missing or malformed.

Caliper conformance errors:

• 400 - Non-conformant envelope, or all events non-conformant (distinct from 202 below).

• 422 - Non-conformant envelope dataVersion. NOTE: A bad dataVersion will always cause a 422 status.

Success:

• 200 - Success! A valid HTTP request, conformant envelope, all events conformant.

• 202 - Partial Success. Valid request, conformant envelope, but at least one non-conformant event along with other conformant events.

Failure:

• Above 500 - the error is unknown and/or the request timed out.

Response body

For any given request, the Caliper endpoint will respond in one of two styles.

Common response

When run in production mode, the Caliper endpoint will always and only return a common response. In debug mode, a common response is given if and only if there is a validation error on the HTTP request itself (e.g., an invalid authentication token is used). In such cases, the Caliper endpoint rejects the request without inspecting the Caliper envelope or its event(s).

{
  "error": "Unauthorized",
  "message": "Bearer token missing or not recognized"
}

Verbose response

In debug mode, the Caliper endpoint will always return a verbose response if the HTTP request is valid. To elicit a response from the Caliper endpoint in debug mode, include a request header called X-DEBUG and set its value to TRUE.

Enabling X-DEBUG will cause your events NOT to be accepted. The endpoint will just return a response if the request is valid.

A verbose response is divided into two sections.

The accepted_events attribute contains information about all of the conformant events that were accepted and to which processing they were routed (these are called "topics"). An errors attribute contains information about the Caliper envelope and all of the events that did not conform with Caliper.

 {
  'accepted_events': [
  {
    'id': 'urn:uuid:b46f370c-79e0-433f-9f2b-2d750155e338',
    'topics': { '': '', ... }
  }, …
  ]
  'errors': {
    'envelope': [ ],
    'events': [
      {
        'id': 'urn:uuid:b46f370c-79e0-433f-9f2b-2d750155e337',
        'index': 0,
        'errors': ['Event `actor` attribute must an object or ' 'string.'],
      }, …
    ]
  }
}

Validation

The UDP Caliper endpoint only accepts valid HTTP requests with content-type of JSON, since JSON is the format for Caliper events. The UDP Caliper endpoint will partially validate that the event payload conforms with certain parts of the IMS Global Caliper standard. The UDP Caliper endpoint does not fully validate Caliper conformance.

When a request to the UDP Caliper endpoint, a Caliper event envelope, or a Caliper event is invalid, the UDP will return error messages describing the nature of the failure. Note that these error messages are only returned if the UDP Caliper endpoint is running in debug mode.

HTTP request errors

The following validation requirements exist for the HTTP requests to the UDP Caliper endpoint. If any of them are not met, a corresponding error message is returned.

Requirement	Error message
An authentication token is present and valid.	Bearer token missing or not recognized
The content-type is JSON.	Unsupported Media Type", "message": "application/json payload expected.

Caliper envelope errors

All events posted to the Endpoint must be delivered in a Caliper envelope. Caliper envelopes must conform to the version 1.1 of the IMS Global Caliper standard. The following validation requirements exist for Caliper envelopes. If any of them are not met, a corresponding error message is returned.

Requirement	Error message
The "sensor" attribute is present.	Event envelope must include a `sensor` attribute.
The "sendTime" attribute is present and in ISO 8601 format.	Event envelope `sendTime` attribute must be an ISO 8601 time string formated like "yyyy-mm-ddThh:mm:ss.SSSZ".
The "dataVersion" attribute is present.	Event envelope `dataVersion` attribute must be a version like "http://purl.imsglobal.org/ctx/caliper/v1p1".
The "dataVersion" attribute is valid.	Event envelope `data` attribute must be an array with at least one element.

Caliper event errors

All Caliper events in a Caliper envelope must conform with the Caliper standard. The Caliper endpoint will reject any events that fail the following requirements. The following validation requirements exist for Caliper events. If any of them are not met, a corresponding error message is returned.

Requirement	Error message
The "id" attribute is present.	Event `id` must be present. Version 4 UUID is recommended.
The "@context" attribute is present and valid.	Event `@context` must be a version like "http://purl.imsglobal.org/ctx/caliper/v1p1".
The "actor" attribute" is present.	Event `actor` attribute must an object or string. Note: we recommend defining actor as a hash with an id and type attribute. Alternatively, actor may be defined as a string.
The "action" and "type" attributes are present.	"Event `type` and `action` must be present, and `action` must be valid for `type`.
The "eventTime" is present and valid ISO 8601 format.	Event `eventTime` attribute must be an ISO 8601 time string formatted like "yyyy-mm-ddThh:mm:ss.SSSZ".