Skip to content

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);
}