API > Registration Submission
The receipt of a registration or collection of registrations is done by HTTP POST requests in a variety of supported media types. All requests containing event data to be submitted should be sent to the /registrations path hanging off of the root context of the auditing service.
The endpoints served out by this service are secured using Cerner's implementation of the OAuth 1.0a spec via the CernerCare OAuth service.
Data submitted to this endpoint is used to describe events that will eventually be submitted to the auditing service, tying them to the system key of the caller. If matching registrations do not currently exist, they are added. If a registration matching an event key in the list had previously been registered but the registration has been updated, the existing registration is updated to match the new state. The complete set of audit registrations does not need to be sent, although it is certainly acceptable to do so.
Data uploaded is expected to be in the form of the serialized RegistrationList Google protocol buffer as defined in the sentinel-protobuf library:
package com.cerner.sentinel.data.protobuf;
option optimize_for = SPEED;
message Registration {
required string event_key = 1; //Defines the form of the key
required string description = 2; // describes context for a given audit event
message Attribute {
required string name = 1; //the name of the attribute attached to an event
message Definition {
optional string description = 1; // description of the attribute
enum Type {
SIMPLE = 0; //Simple attribute type, no special meaning given to the attribute
OPEN_ID = 1; //Denotes the attribute is an Open Identifier.
SYSTEM_KEY = 2; //Denotes the attribute is a System key.
IP_ADDRESS = 3; //The attribute represents an I.P. address (either IPv4 or IPv6)
EMAIL = 4; //The attribute represents a user's email address
TIME = 5; //Denotes a time attribute, designated by the number of milliseconds since midnight on January 1, 1970 UTC
URL = 6; //The attribute represents a URL, which may potentially be visited by a consumer for additional info if properly authorized
USER_INPUT = 7; //The attribute represents user inputed data, potentially even free text
NUMERIC = 8; //The attribute is numeric, thus may be compared to other attribute numerically
}
optional Type type = 2 [default = SIMPLE]; //Defines the type of the attribute.
enum Cardinality {
SINGLE = 0; // Exactly one value will be permitted for an attribute.
MANY = 1; // An unlimited number of values will be permitted for an attribute.
}
optional Cardinality cardinality = 3 [default = SINGLE]; // Defines the cardinality (number of values) for an attribute.
}
required Definition definition = 2; //Defines the definition of a given attribute
}
optional Attribute.Definition tenant = 3; //Denotes the identifier of the tenant the item is being audited on behalf of
optional Attribute.Definition user = 4; //The user whose action triggered an event that must be audited.
repeated Attribute attributes = 5; //Definitions for the the optional attributes associated with an event.
optional bytes registration_version = 6; //Defines the version for a given registration instance. Used by the system to tie events to specific registration instances
}
message RegistrationList {
repeated Registration registration = 1;
}
If a version is specified in the request, that will be returned in the response. If none is provided, then a version will be calculated by the service and returned in the response.
Beyond the requirements inherent in the protocol buffer (e.g. required fields), the following additional requirements are imposed of registrations in the passed list:
If any of these requirements are violated, an error will be returned and the new registrations list will not be accepted.
The following are valid HTTP statuses for this POST request.
The receipt of registrations can be in any of the following media types:
Requests of this type will specify a Content-Type header of application/x-protobuf.
Data passed in the stream is expected to be the serialized RegistrationList Google protocol buffer as defined in the sentinel-protobuf library.
The returned info will be the serialized RegistrationList Google protocol buffer (again, as defined in the sentinel-protobuf library). In the event of a 400 returned by the service, the reply will be the serialized Error Google protocol buffer (once again, as defined in the sentinel-protobuf library).
Requests of this type will specify a Content-Type header of application/json.
The overall structure of the response is equivalent to the RegistrationList protocol buffer as defined in the sentinel-protobuf library.
For example, a successful submission could look similar to the following:
{
"registrations": [
{
"event_key": "CHART_ACCESS",
"attributes": [
{
"name": "RESOURCE",
"definition": {
"type": "URL",
"description": "The REST endpoint of the chart that was accessed",
"cardinality": "SINGLE"
}
}
],
"description": "Event denoting an access of a patient's chart",
"user": {
"type": "OPEN_ID",
"description": "The user identifier",
"cardinality": "SINGLE"
},
"tenant": {
"type": "SYSTEM_KEY",
"description": "System key of the tenant that owns this data",
"cardinality": "SINGLE"
},
"registration_version": "GQlKOPMNiUq4nwDEIjA63pKagKQ="
},
{
"event_key": "ANOTHER_EVENT",
"attributes": [
],
"description": "reg2 description",
"registration_version": "jrZrtkCUYfmyNh0OqtOxVNkKZ9o="
}
]
}
In the event of a 400 returned by the service, the JSON equivalent for the Error Google protocol buffer is returned:
{
"type":"GENERIC",
"message":"The service was unable to fulfill the requested action"
}
The following enumerations of attribute types (and their integer representations) are available:
The integer representations are supported for backward compatibility; consumers are encouraged to use the more meaningful and readable textual representations.
Refer to the registration data model documentation for intended uses of these types.