gRPC APIs#
rta-server
packages up three capabilities into a single process:
gRPC interfaces are enabled by the EnableGprc
option (default: true
) and present the same API as the individual toolkit services.
See also: Session Service gRPC API
syntax = "proto3";
package rta.toolkit.api.session_service;
import "google/protobuf/empty.proto";
import "google/protobuf/wrappers.proto";
option csharp_namespace = "MAT.OCS.RTA.Toolkit.API.SessionService";
// Manages Sessions.
//
// Sessions are a logical way to organize data - like a file system.
// This service includes support for organizing sessions into folders and searching by metadata.
service SessionStore {
// Gets session folders within a parent folder.
rpc GetSessionFolders(GetSessionFoldersRequest)
returns (GetSessionFoldersResponse);
// Updates a folder.
// Use this method to move a folder, by updating its parent.
rpc PutSessionFolder(PutSessionFolderRequest)
returns (google.protobuf.Empty);
// Deletes folders. The root folder (empty identity) cannot be deleted.
// Any sessions left orphaned by this method are reattached to the root folder.
rpc DeleteSessionFolders(DeleteSessionFoldersRequest)
returns (google.protobuf.Empty);
// Gets a summary of session properties.
// Can be scoped by folder sub-tree.
rpc GetSessionMetamodel(GetSessionMetamodelRequest)
returns (GetSessionMetamodelResponse);
// Queries the session metamodel for properties from the extended session details,
// which are not exposed in the session or metamodel by default.
rpc QuerySessionMetamodel(QuerySessionMetamodelRequest)
returns (QuerySessionMetamodelResponse);
// Lists sessions, with sorting and paging.
rpc ListSessions(ListSessionsRequest)
returns (ListSessionsResponse);
// Gets the specified session by identity.
rpc GetSession(GetSessionRequest)
returns (Session);
// Creates or updates a session.
rpc CreateOrUpdateSession(CreateOrUpdateSessionRequest)
returns (google.protobuf.Empty);
// Deletes sessions.
// Sessions that do not exist are silently ignored.
rpc DeleteSessions(DeleteSessionsRequest)
returns (google.protobuf.Empty);
}
// Request for GetSessionFolders.
message GetSessionFoldersRequest {
string parent_identity = 1;
}
// Response for GetSessionFolders.
message GetSessionFoldersResponse {
repeated SessionFolder folders = 1;
}
// Request for DeleteSessionFolders.
message DeleteSessionFoldersRequest {
repeated string folder_identities = 1;
}
// Request for PutSessionFolder.
message PutSessionFolderRequest {
string parent_identity = 1; // Parent folder identity.
string identity = 2; // Folder identity.
string label = 3; // Human-readable label.
string description = 4; // Human-readable description.
}
// Request for GetSessionMetamodel.
message GetSessionMetamodelRequest {
string folder_subtree = 1; // Identity of folder sub-tree to select sessions for the metamodel.
repeated string json_properties = 2; // Property keys to include in the JSON response.
}
// Response for GetSessionMetamodel.
message GetSessionMetamodelResponse {
string metamodel_json = 1; // JSON response matching the REST API.
}
// Request for QuerySessionMetamodel.
message QuerySessionMetamodelRequest {
string partial_match = 1; // Partial match to properties.
string folder_subtree = 2; // Identity of folder sub-tree to select sessions for the metamodel.
}
// Response for QuerySessionMetamodel.
message QuerySessionMetamodelResponse {
repeated PropertySummary property_summaries = 1;
}
// Request for GetSession.
message GetSessionRequest {
string identity = 1; // Session identity.
SessionElements elements = 2; // Session elements to include.
}
// Request for DeleteSessions.
message DeleteSessionsRequest {
repeated string identities = 1; // Session identities.
}
// Request for ListSessions.
message ListSessionsRequest {
string query = 1; // JSON query expression matching the REST API.
string folder_subtree = 2; // Identity of folder sub-tree to select sessions.
repeated string sorts = 3; // Sort directives, formatted as property:[asc|desc]..
SessionElements session_elements = 4; // Session elements to include.
bool include_sub_sessions = 5; // Include child and alternate sessions in the list. The REST API does not offer this option.
int32 page_index = 6; // Page index (zero-based).
int32 page_size = 7; // Page size.
}
// Response for ListSessions.
message ListSessionsResponse {
repeated Session sessions = 1; // Sessions.
}
// Request for CreateOrUpdateSession.
message CreateOrUpdateSessionRequest {
string identity = 1; // Session identity.
google.protobuf.Int64Value sequence = 2; // If specified, the update will be applied only if the last sequence number was lower.
CreateIfNotExists create_if_not_exists = 3; // Initial properties to apply if the session does not already exist.
repeated SessionUpdate updates = 4; // Updates to apply together as a transaction.
// Initial session definition
message CreateIfNotExists {
int32 state = 1; // Initial state (defaults to closed/4).
string timestamp = 2; // ISO 8601 timestamp (defaults to current UTC time).
string identifier = 3; // Identifier (human-readable name; defaults to identity).
}
}
// Update to apply to a session.
// Each update performs a single operation, but multiple updates can be
// specified together in a single transaction.
message SessionUpdate {
oneof op {
google.protobuf.Empty update_heartbeat = 1; // Touches the session.
int32 set_state = 2; // Sets the state.
string set_timestamp = 3; // Sets the ISO 8601 timestamp.
TimeRange set_time_range = 4; // Sets the time-range covered by data in the session.
TimeRange extend_time_range = 5; // Extends the time-range covered by data in the session.
google.protobuf.Empty clear_time_range = 6; // Clears the time-range, implying there is no data in the session.
string set_identifier = 7; // Sets the name.
DetailsMap set_details = 8; // Sets the details, which are user-facing key-value metadata.
DetailsMap update_details = 9; // Merges updates to the details, which are user-facing key-value metadata.
DetailsJson set_details_json = 10; // Sets the details from JSON.
DetailsJson update_details_json = 11; // Merges updates to details from JSON.
DetailKeysList delete_details = 12; // Deletes details.
google.protobuf.StringValue set_type = 13; // Sets the type classifier, indicating the origin or content of the session.
google.protobuf.Empty clear_type = 14; // Clears the type classifier.
double set_quality = 15; // Sets the quality indicator in the range 0.0 - 1.0 (worst - best).
google.protobuf.Empty clear_quality = 16; // Clears the quality indicator.
string set_group = 17; // Sets a group to enable the client to organize the session into groups amongst peers.
google.protobuf.Empty clear_group = 18; // Clears the group.
string set_version = 19; // Sets a SemVer-style version number, which is used together with the group when managing child sessions.
google.protobuf.Empty clear_version = 20; // Clears the version number.
MarkersMap set_markers = 21; // Sets markers, which are annotations marking up regions of the session.
MarkersMap update_markers = 22; // Merges updates to the markers.
MarkerIdsList delete_markers = 23; // Deletes markers.
ConfigBindingsList set_config_bindings = 24; // Sets config bindings, which associate Configuration with the session.
ConfigBindingsList update_config_bindings = 25; // Merges updates to config bindings.
ConfigIdentifiersList delete_config_bindings = 26; // Deletes config bindings.
DataBindingsList set_data_bindings = 27; // Sets data bindings, which bind data from Data Services to sessions.
DataBindingsList update_data_bindings = 28; // Merges updates to data bindings.
DataBindingKeysList delete_data_bindings = 29; // Deletes data bindings.
FoldersList set_folders = 30; // Sets folders the session symbolically linked to.
FoldersList update_folders = 31; // Merges updates to the folder sym-links.
FoldersList delete_folders = 32; // Deletes folder sym-links. If this results in the session being orphaned, it is linked to the root folder.
RefUrisList set_ref_anchors = 33; // Sets URIs that act as anchors for alternate and child references.
RefUrisList update_ref_anchors = 34; // Merges updates to anchor URIs.
RefUrisList delete_ref_anchors = 35; // Deletes anchor URIs.
RefUrisList set_alternate_of_refs = 36; // Sets alternate_of references pointing to anchor URIs on other sessions.
RefUrisList update_alternate_of_refs = 37; // Merges updates to alternate_of references.
RefUrisList delete_alternate_of_refs = 38; // Deletes alternate_of references.
RefUrisList set_child_of_refs = 39; // Sets child_of references pointing to anchor URIs on other sessionsthat this session is a child of.
RefUrisList update_child_of_refs = 40; // Merges updates to child_of references.
RefUrisList delete_child_of_refs = 41; // Deletes child_of references.
}
// Session details where all values are strings.
message DetailsMap {
// Category if extended details; otherwise leave blank.
string category = 1;
// Details as strings only.
// Boolean, integer and number values are also allowed: use SessionDetailsJson.
map<string, string> details = 2;
}
// Session details represented as JSON.
message DetailsJson {
// Category if extended details; otherwise leave blank.
string category = 1;
// Details JSON. Values can be string, boolean, integer, and number.
string json = 2;
}
// List of session detail keys.
message DetailKeysList {
// Category if extended details.
string category = 1;
// Detail keys.
repeated string keys = 2;
}
// List of marker ids.
message MarkerIdsList {
// Marker ids.
repeated string marker_ids = 1;
}
// Session markers, organized by category.
// A marker id can only appear in one MarkersList.
message MarkersMap {
// Markers by category.
map<string, MarkersList> markers_by_category = 1;
}
// List of markers.
message MarkersList {
// Markers.
repeated Marker markers = 1;
}
// List of config identifiers.
message ConfigIdentifiersList {
// Config identifiers.
repeated string identifiers = 1;
}
// List of config bindings.
message ConfigBindingsList {
// Config bindings.
repeated ConfigBinding config_bindings = 1;
}
// List of data binding keys.
message DataBindingKeysList {
// Data binding keys.
repeated DataBindingKey keys = 1;
}
// List of data bindings.
message DataBindingsList {
// Data bindings.
repeated DataBinding data_bindings = 1;
}
// List of folder identities.
message FoldersList {
// Folder identities.
repeated string identities = 1;
}
// List of reference URIs.
message RefUrisList {
// Reference URIs.
repeated string ref_uris = 1;
}
}
// Describes the time-range covered by data in a session.
message TimeRange {
// Start of data, in nanoseconds since the Unix epoch.
sfixed64 start_time = 1;
// End of data, in nanoseconds since the Unix epoch.
sfixed64 end_time = 2;
}
// Virtual folder for organizing sessions.
message SessionFolder {
// Unique identity; UUID recommended but not required.
string identity = 1;
// Human-readable label.
string label = 2;
// Human-readable description.
string description = 3;
// Indicates whether there are child folders.
bool has_children = 4;
}
// Describes a metamodel property.
message PropertySummary {
// Property id, which is the qualified key.
// For example, a the "Driver" session detail would be id "details.Driver".
string id = 1;
// Human-readable label.
string label = 2;
// Human-readable description.
string description = 3;
}
// Describes a point or region of data in a session.
message Marker {
// Unique id within the session.
string id = 1;
// Type.
string type = 2;
// Human-readable label.
string label = 3;
// Human-readable description.
google.protobuf.StringValue description = 4;
// Optional start time, in nanoseconds since the Unix epoch (inclusive).
// If unspecified, the start of the marker is treated as immediately after the end of the previous marker in the group,
// or the start of the session if there is no previous marker.
google.protobuf.Int64Value start_time = 5;
// Optional end time, in nanoseconds since the Unix epoch (inclusive).
// If unspecified, the end of the marker is treated as immediately before the start of the next marker in the group,
// or the end of the session if there is no next marker.
google.protobuf.Int64Value end_time = 6;
// Details object (JSON).
string details_json = 7;
}
// Binds configuration to a session.
message ConfigBinding {
// Config identifier.
// Corresponds to the identifier used to publish to the Config Service.
// A single configuration can be bound to multiple sessions.
string identifier = 1;
// Channel offset to avoid overlaps between configuration.
uint32 channel_offset = 2;
}
// Uniquely identifies the binding of data onto a session.
message DataBindingKey {
// Data source token, effectively acting as a namespace for the identity, and used by the Gateway Service to route data requests.
string source = 1;
// Data identity. Often a query expression, database key, or file path.
string identity = 2;
// Additional qualifier to create a unique key if the data is bound to a session over multiple time-ranges.
// The value is arbitrary, but when in use the obvious choice would be the start of each bound time-range.
int64 time_ref = 3;
}
// Binds data onto a session.
// This creates indirection where multiple Data Services can contribute data to a Session.
// The Gateway Service retrieves data bindings using an internal REST API call, and routes requests based on the key data source.
message DataBinding {
// Uniquely identifies the data binding relative to the session.
DataBindingKey key = 1;
// Start of time range covered in the session (inclusive), in nanoseconds relative to the Unix epoch.
// Unbounded if not specified.
google.protobuf.Int64Value session_start_time = 2;
// End of time range covered in the session (inclusive), in nanoseconds relative to the Unix epoch.
// Unbounded if not specified.
google.protobuf.Int64Value session_end_time = 3;
// Offset of session time relative to data time, in nanoseconds.
// Zero implies that the data time is the same.
sint64 session_time_offset = 4;
// Maps channels onto the session.
// If no channel bindings are specified, channel-based data requests (row, periodic, timestamped) are not bound.
repeated DataChannelBinding data_channel_bindings = 5;
}
// Represents a range of data channels bound onto a session.
message DataChannelBinding {
// Lowest numbered data channel corresponding to the lowest numbered session channel, to allow any necessary offset to be applied.
uint32 first_data_channel = 1;
// Lowest numbered channel (inclusive) in range, relative to the configuration bound to the session.
// If different from first_data_channel, this implies on-the-fly data transformation.
uint32 first_session_channel = 2;
// Highest numbered channel (inclusive) in range, relative to the configuration bound to the session.
uint32 last_session_channel = 3;
}
// Selects elements to be retrieved when calling ListSessions or GetSession.
message SessionElements {
// JSON representation of the session as served via the REST API.
bool json = 1;
// Specific JSON properties to include.
repeated string json_properties = 2;
// Last time the session was touched.
bool heartbeat_utc = 3;
// Data Bindings describing how data should be retrieved from Data Services.
bool data_bindings = 4;
// Folder membership.
bool folders = 5;
// References between sessions.
bool refs = 6;
}
// Service session: a super-set of the REST session model and the other elements modelled by the Session Service.
message Session {
// Session identity (always present).
string identity = 1;
// If selected: JSON representation of the session as served via the REST API.
string json = 2;
// If selected: Last time the session was touched.
string heartbeat_utc = 3;
// If selected: Data Bindings describing how data should be retrieved from Data Services.
repeated DataBinding data_bindings = 4;
// If selected: Folder membership.
repeated string folders = 5;
// If selected (refs element): Anchor URIs that can be targets for references from other sessions.
repeated string ref_anchors = 6;
// If selected (refs element): References to other sessions for which the session is a child.
repeated string child_of_refs = 7;
// If selected (refs element): References to other sessions for which the session is an alternate.
repeated string alternate_of_refs = 8;
}
See also: Config Service gRPC API
syntax = "proto3";
package rta.toolkit.api.config_service;
import "google/protobuf/empty.proto";
import "google/protobuf/wrappers.proto";
option csharp_namespace = "MAT.OCS.RTA.Toolkit.API.ConfigService";
// Stream message for ConfigStore.PutConfigStream and ConfigStore.GetConfigStream.
message ConfigStreamMessage {
// Message type.
oneof type {
ConfigInfo info = 1; // Metadata - must be the first message.
bytes piece = 2; // Piece of config data.
}
// Config info.
message ConfigInfo {
string identifier = 1; // Unique config identifier.
string content_type = 2; // One of "application/vnd.mat.config+json" or "application/vnd.mat.config+ffc".
}
}
// Request for ConfigStore.PutConfig.
message PutConfigRequest {
string identifier = 1; // Unique config identifier.
string content_type = 2; // One of "application/vnd.mat.config+json" or "application/vnd.mat.config+ffc".
bytes data = 3; // Config data.
}
// Request for ConfigStore.HasConfig.
message HasConfigRequest {
string identifier = 1; // Unique config identifier.
}
// Request for ConfigStore.GetConfig.
message GetConfigRequest {
string identifier = 1; // Unique config identifier.
}
// Response for ConfigStore.GetConfig.
message GetConfigResponse {
string content_type = 1; // One of "application/vnd.mat.config+json" or "application/vnd.mat.config+ffc".
bytes data = 2; // Config data.
}
// Request for ConfigStore.DeleteConfig.
message DeleteConfigRequest {
string identifier = 1; // Unique config identifier.
}
// Manages RTA Configuration.
//
// Configuration describes telemetry, in terms of parameters, events, formatting, etc.
service ConfigStore {
// Stores a config unless it already exists.
// The request is size-limited to 4 MiB by default. For large configs, call PutConfigStream.
rpc PutConfig(PutConfigRequest)
returns (google.protobuf.Empty);
// Stores a config as a stream unless it already exists.
// The first message in the stream must be info containing the config identifier and content type.
rpc PutConfigStream(stream ConfigStreamMessage)
returns (google.protobuf.Empty);
// Checks whether a config is stored.
rpc HasConfig(HasConfigRequest)
returns (google.protobuf.BoolValue);
// Gets a config.
// The response is size-limited to 4 MiB by default. For large configs, call GetRequestStream.
rpc GetConfig(GetConfigRequest)
returns (GetConfigResponse);
// Gets a config as a stream.
// The first message in the stream is info containing the config identifier and content type.
rpc GetConfigStream(GetConfigRequest)
returns (stream ConfigStreamMessage);
// Deletes a config if it exists, succeeding silently if it does not.
// Use with care. Unpublishing configuration will break any sessions that have it bound.
rpc DeleteConfig(DeleteConfigRequest)
returns (google.protobuf.Empty);
}
See also: Data Service gRPC API
The DataWriter
service is enabled by the EnableDataWriter
service option (default: true
).
syntax = "proto3";
package rta.toolkit.api.chunk_service;
import "protos/API/model_data.proto";
import "google/protobuf/wrappers.proto";
option csharp_namespace = "MAT.OCS.RTA.Toolkit.API.DataService";
// Request messages for WriteDataStream.
message WriteDataStreamMessage {
oneof type {
string data_identity = 1; // Data identity to write. Format and length is restricted based on the backing store.
string flush_marker = 2; // Requests a flush, to be acknowledged with this marker when completed. Don't flush too frequently or write and read performance will drop off.
rta.model.data.TimestampedData timestamped_data = 3; // Timestamped Data to write. Note that individual data items are written, but they are read back in lists.
rta.model.data.PeriodicData periodic_data = 4; // Periodic Data to write. Note that individual data items are written, but they are read back in lists.
rta.model.data.RowData row_data = 5; // Row Data to write. Note that individual data items are written, but they are read back in lists.
rta.model.data.Event event = 6; // Event to write. Note that individual data items are written, but they are read back in lists.
}
}
// Response messages for WriteDataStream.
message WriteDataStreamResponseMessage {
oneof type {
string flush_completed = 1; // Indicates that a requested flush is completd by echoing back the flush marker.
}
}
// Request for ReadEventsStream.
message ReadDataStreamRequest {
string data_identity = 1; // Data identity to read.
google.protobuf.Int64Value start_time = 2; // Optional start time to include in the request, in nanoseconds since the Unix epoch (inclusive). May over-read before this point.
google.protobuf.Int64Value end_time = 3; // Optional end time to include in the request, in nanoseconds since the Unix epoch (inclusive). May over-read after this point.
}
// Request for ReadTimestampedDataStream / ReadPeriodicDataStream / ReadRowDataStream.
message ReadChannelDataStreamRequest {
string data_identity = 1; // Data identity to read.
google.protobuf.Int64Value start_time = 2; // Optional start time to include in the request, in nanoseconds since the Unix epoch (inclusive). May over-read before this point.
google.protobuf.Int64Value end_time = 3; // Optional end time to include in the request, in nanoseconds since the Unix epoch (inclusive). May over-read after this point.
string channels = 4; // Channels expression, as used in the REST API - e.g. "-5,7,B-D,14-"
}
// Writes RTA data to storage.
service DataWriter {
// Writes a stream of RTA data.
rpc WriteDataStream(stream WriteDataStreamMessage)
returns (stream WriteDataStreamResponseMessage);
}
// Reads RTA data from storage.
service DataReader {
// Reads timestamped data.
rpc ReadTimestampedDataStream(ReadChannelDataStreamRequest)
returns (stream rta.model.data.TimestampedDataList);
// Reads periodic data.
rpc ReadPeriodicDataStream(ReadChannelDataStreamRequest)
returns (stream rta.model.data.PeriodicDataList);
// Reads row data.
rpc ReadRowDataStream(ReadChannelDataStreamRequest)
returns (stream rta.model.data.RowDataList);
// Reads events.
rpc ReadEventsStream(ReadDataStreamRequest)
returns (stream rta.model.data.EventsList);
}