LimitsMixin Service APIv1

Understanding the LimitsMixin service APIv1, as known as ntt.limits.mixin.v1.

Here is the list of resources supported in LimitsMixin service APIv1:

LocalLimitTracker Resource

LocalLimitTracker Resource

This section covers the methods and messages to interact with LocalLimitTracker resource.

LocalLimitTracker Methods

Here is the list of LocalLimitTracker resource methods:

GetLocalLimitTracker Method

GetLocalLimitTracker

rpc GetLocalLimitTracker(GetLocalLimitTrackerRequest) returns (LocalLimitTracker)

with the following messages:

The equivalent REST API is:

GET /limits-mixin/v1/{name=regions/*/localLimitTrackers/*}

BatchGetLocalLimitTrackers Method

BatchGetLocalLimitTrackers

rpc BatchGetLocalLimitTrackers(BatchGetLocalLimitTrackersRequest) returns (BatchGetLocalLimitTrackersResponse)

with the following messages:

The equivalent REST API is:

GET /limits-mixin/v1/localLimitTrackers:batchGet

ListLocalLimitTrackers Method

ListLocalLimitTrackers

rpc ListLocalLimitTrackers(ListLocalLimitTrackersRequest) returns (ListLocalLimitTrackersResponse)

with the following messages:

The equivalent REST API is:

GET /limits-mixin/v1/{parent=regions/*}/localLimitTrackers

WatchLocalLimitTracker Method

WatchLocalLimitTracker

rpc WatchLocalLimitTracker(WatchLocalLimitTrackerRequest) returns (WatchLocalLimitTrackerResponse)

with the following messages:

The equivalent REST API is:

POST /limits-mixin/v1/{name=regions/*/localLimitTrackers/*}:watch

WatchLocalLimitTrackers Method

WatchLocalLimitTrackers

rpc WatchLocalLimitTrackers(WatchLocalLimitTrackersRequest) returns (WatchLocalLimitTrackersResponse)

with the following messages:

The equivalent REST API is:

POST /limits-mixin/v1/{parent=regions/*}/localLimitTrackers:watch

CreateLocalLimitTracker Method

CreateLocalLimitTracker

rpc CreateLocalLimitTracker(CreateLocalLimitTrackerRequest) returns (LocalLimitTracker)

with the following messages:

The equivalent REST API is:

POST /limits-mixin/v1/{parent=regions/*}/localLimitTrackers (BODY: local_limit_tracker)

UpdateLocalLimitTracker Method

UpdateLocalLimitTracker

rpc UpdateLocalLimitTracker(UpdateLocalLimitTrackerRequest) returns (LocalLimitTracker)

with the following messages:

The equivalent REST API is:

PUT /limits-mixin/v1/{local_limit_tracker.name=regions/*/localLimitTrackers/*} (BODY: local_limit_tracker)

DeleteLocalLimitTracker Method

DeleteLocalLimitTracker

rpc DeleteLocalLimitTracker(DeleteLocalLimitTrackerRequest) returns (Empty)

with the following messages:

The equivalent REST API is:

DELETE /limits-mixin/v1/{name=regions/*/localLimitTrackers/*}

LocalLimitTracker Messages

Here is the list of LocalLimitTracker resource messages:

LocalLimitTracker Message

Name Type Description
name string Name of LocalLimitTracker, it has following format: regions/{region}/localLimitTrackers/{projectId}/{resourceType}
metadata .goten.types.Meta Metadata is an object with information like create, update and delete time (for async deleted resources), has user labels/annotations, sharding information, multi-region syncing information and may have non-schema owners (useful for taking ownership of resources belonging to lower level services by higher ones).
service string Service to which resource belongs
resource string Tracked resource reference
project string Project associated with this tracker. The reason why its not included in resource name is because this is a (bit) “hidden” resource - and we dont want project admins being able to modify them.
project_region string Primary region ID for project this limit tracker belongs to. It may be different from region of this tracker, because Project may have presence in multiple regions. Limits (limits.edgelq.com/Limit) are managed by primary region, but their trackers are located in their final region.
limit int64 Maximum number of resources of given type
used int64 Number currently in use

GetLocalLimitTrackerRequest Message

A request message of the GetLocalLimitTracker method.

Name Type Description
name string Name of ntt.limits.mixin.v1.LocalLimitTracker
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view .goten.types.View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

BatchGetLocalLimitTrackersRequest Message

A request message of the BatchGetLocalLimitTrackers method.

Name Type Description
names repeated string Names of LocalLimitTrackers
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view .goten.types.View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

BatchGetLocalLimitTrackersResponse Message

A response message of the BatchGetLocalLimitTrackers method.

Name Type Description
local_limit_trackers repeated LocalLimitTracker found LocalLimitTrackers
missing repeated string list of not found LocalLimitTrackers

ListLocalLimitTrackersRequest Message

A request message of the ListLocalLimitTrackers method.

Name Type Description
parent string Parent name of ntt.limits.mixin.v1.LocalLimitTracker
page_size int32 Requested page size. Server may return fewer LocalLimitTrackers than requested. If unspecified, server will pick an appropriate default.
page_token string A token identifying a page of results the server should return. Typically, this is the value of ListLocalLimitTrackersResponse.next_page_token.
order_by string Order By - https://cloud.google.com/apis/design/design_patterns#list_pagination list of field path with order directive, either ‘asc’ or ‘desc’. If direction is not provided, ‘asc’ is assumed. e.g. “state.nested_field asc, state.something.else desc, theme”
filter string Filter - filter results by field criteria. Simplified SQL-like syntax with following operators: <=, >=, =, !=, <, >, LIKE, CONTAINS (aliases CONTAIN, HAS, HAVE), IN, IS [NOT] NULL
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view .goten.types.View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask
include_paging_info bool Indicates if list response should contain total count and offset (fields current_offset and total_results_count).

ListLocalLimitTrackersResponse Message

A response message of the ListLocalLimitTrackers method.

Name Type Description
local_limit_trackers repeated LocalLimitTracker The list of LocalLimitTrackers
prev_page_token string A token to retrieve previous page of results. Pass this value in the ListLocalLimitTrackersRequest.page_token.
next_page_token string A token to retrieve next page of results. Pass this value in the ListLocalLimitTrackersRequest.page_token.
current_offset int32 Current offset from the first page or 0 if no page tokens were given, paging info was not requested or there was an error while trying to get it). Page index can be computed from offset and limit provided in a request.
total_results_count int32 Number of total LocalLimitTrackers across all pages or 0, if there are no items, paging info was not requested or there was an error while trying to get it.

WatchLocalLimitTrackerRequest Message

A request message of the WatchLocalLimitTracker method.

Name Type Description
name string Name of ntt.limits.mixin.v1.LocalLimitTracker
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view .goten.types.View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

WatchLocalLimitTrackerResponse Message

A response message of the WatchLocalLimitTracker method.

Name Type Description
change LocalLimitTrackerChange

WatchLocalLimitTrackersRequest Message

A request message of the WatchLocalLimitTrackers method.

Name Type Description
type .goten.types.WatchType Type of a watch. Identifies how server stream data to a client, which fields in a request are allowed and which fields in response are relevant.
parent string Parent name of ntt.limits.mixin.v1.LocalLimitTracker
page_size int32 Requested page size. Server may return fewer LocalLimitTrackers than requested. If unspecified, server will pick an appropriate default. Can be populated only for stateful watch type.
page_token string A token identifying a page of results the server should return. Can be populated only for stateful watch type.
order_by string Order By - https://cloud.google.com/apis/design/design_patterns#list_pagination Can be populated only for stateful watch type.
resume_token string A token identifying watch resume point from previous session. Can be populated only for stateless watch type.
starting_time .google.protobuf.Timestamp Point in the time from which we want to start getting updates. This field can be populated only for stateless watch type and if resume token is not known yet. If specified, initial snapshot will NOT be provided. It is assumed client can obtain it using separate means. Watch responses will contain resume tokens which should be used to resume broken connection.
filter string Filter - filter results by field criteria. Simplified SQL-like syntax with following operators: <=, >=, =, !=, <, >, LIKE, CONTAINS (aliases CONTAIN, HAS, HAVE), IN, IS [NOT] NULL
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view Changes to LocalLimitTracker that don’t affect any of masked fields won’t be sent back.
view .goten.types.View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask Changes to LocalLimitTracker that don’t affect any of masked fields won’t be sent back.
max_chunk_size int32 Maximum amount of changes in each response message. Query result response is divided on the server side into chunks with size of a specified amount to limit memory footprint of each message. Responses will hold information whether more elements will continue for the actual change. If unspecified, server will pick an appropriate default.

WatchLocalLimitTrackersResponse Message

A response message of the WatchLocalLimitTrackers method.

Name Type Description
local_limit_tracker_changes repeated LocalLimitTrackerChange Changes of LocalLimitTrackers
is_current bool If request specified max_chunk_size (or this limit was enforced if stateless watch has been chosen), then responses with “full changeset” will be divided into chunks. Client should keep receiving messages and, once is_current has value true, combine this recent message with all previous ones where is_current is false. If this is the first is_current in a whole watch stream, then it means that client should have, at this moment, contain snapshot of the current situation (or more accurately, snapshot of situation at the moment of request). All LocalLimitTrackers will be of type Added/Current (depending on watch_type specified in the request). Further responses will be incremental - however messages may still be chunked and is_current logic still applies. is_current is always true for stateful watch if max_chunk_size was left to 0.
page_token_change WatchLocalLimitTrackersResponse.PageTokenChange When present, PageTokens used for page navigation should be updated. Present only if is_current is true (last chunk).
resume_token string Token that can be used if current connection drops and client needs to reconnect. Populated only for stateless watch type. Present only if is_current is true (last chunk).
snapshot_size int64 Server may occasionally send information how many resources should client have in its state so far (response message without any changes, but with snapshot_size field specified). If client has different value than the one sent by the server, then it should be treated by a client as an error and should reconnect. If value is smaller then 0, then client should ignore this field as unpopulated. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will be never sent together with is_current, is_soft_reset and is_hard_reset flags.
is_soft_reset bool In case of internal issue server may send response message with this flag. It indicates that client should drop all changes from recent responses where is_current is false only! If last message had is_current set to true, client should do nothing and process normally. Resume token received before is still valid. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will never be sent along with is_current, is_hard_reset or snapshot_size.
is_hard_reset bool In case of internal issue server may send response message with this flag. After receiving, client should clear whole state (drop all changes received so far) as server will send new snapshot (LocalLimitTrackers will contains changes of type Current only). Any resume tokens should be discarded as well. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will never be sent along with is_current, is_soft_reset or snapshot_size.

WatchLocalLimitTrackersResponse.PageTokenChange Message

Name Type Description
prev_page_token string New token to retrieve previous page of results.
next_page_token string New token to retrieve next page of results.

CreateLocalLimitTrackerRequest Message

A request message of the CreateLocalLimitTracker method.

Name Type Description
parent string Parent name of ntt.limits.mixin.v1.LocalLimitTracker
local_limit_tracker LocalLimitTracker LocalLimitTracker resource body
response_mask CreateLocalLimitTrackerRequest.ResponseMask Optional masking applied to response object to reduce message response size.

CreateLocalLimitTrackerRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

Name Type Description
skip_entire_response_body bool If this flag has value true, then response will contain just empty resource without any fields populated.
body_mask .google.protobuf.FieldMask If this field is populated, then resource in response will contain only specific fields.

UpdateLocalLimitTrackerRequest Message

A request message of the UpdateLocalLimitTracker method.

Name Type Description
local_limit_tracker LocalLimitTracker LocalLimitTracker resource body
update_mask .google.protobuf.FieldMask FieldMask applied to request - change will be applied only for fields in the mask
cas UpdateLocalLimitTrackerRequest.CAS Conditional update applied to request if update should be executed only for specific resource state. If this field is populated, then server will fetch existing resource, compare with the one stored in the cas field (after applying field mask) and proceed with update only and only if they match. Otherwise RPC error Aborted will be returned.
allow_missing bool If set to true, and the resource is not found, a new resource will be created. In this situation, ‘field_mask’ is ignored. https://google.aip.dev/134#create-or-update
response_mask UpdateLocalLimitTrackerRequest.ResponseMask reduce message response size.

UpdateLocalLimitTrackerRequest.CAS Message

CAS - Compare and Swap. This object is used if user wants to make update conditional based upon previous resource version.

Name Type Description
conditional_state LocalLimitTracker Conditional desired state of a resource before update.
field_mask .google.protobuf.FieldMask Field paths from conditional state of resource server should check and compare.

UpdateLocalLimitTrackerRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

Name Type Description
skip_entire_response_body bool If this flag has value true, then response will contain just empty resource without any fields populated. Field body_mask is ignored if set.
updated_fields_only bool Include all fields that were actually updated during processing. Note this may be larger than update mask if some fields were computed additionally. Name is added as well.
body_mask .google.protobuf.FieldMask If this field is populated, then resource in response will contain only specific fields. If skip_entire_response_body is true, this field is ignored.

DeleteLocalLimitTrackerRequest Message

A request message of the DeleteLocalLimitTracker method.

Name Type Description
name string Name of ntt.limits.mixin.v1.LocalLimitTracker

LimitsMixin Service Shared Methods and Messages

LimitsMixin Service Shared Messages

Here is the list of LimitsMixin service shared messages:

LocalLimitTrackerChange Message

LocalLimitTrackerChange is used by Watch notifications Responses to describe change of single LocalLimitTracker One of Added, Modified, Removed

Name Type Description
added LocalLimitTrackerChange.Added Added is returned when watched document is added, either created or enters Query view
modified LocalLimitTrackerChange.Modified Modified is returned when watched document is modified
current LocalLimitTrackerChange.Current Current is returned in stateless watch when document enters query view or is modified within.
removed LocalLimitTrackerChange.Removed Removed is returned when LocalLimitTracker is deleted or leaves Query view

LocalLimitTrackerChange.Added Message

LocalLimitTracker has been added to query view

Name Type Description
local_limit_tracker LocalLimitTracker
view_index int32 Integer describing index of added LocalLimitTracker in resulting query view.

LocalLimitTrackerChange.Current Message

LocalLimitTracker has been added or modified in a query view. Version used for stateless watching

Name Type Description
local_limit_tracker LocalLimitTracker

LocalLimitTrackerChange.Modified Message

LocalLimitTracker changed some of it’s fields - contains either full document or masked change

Name Type Description
name string Name of modified LocalLimitTracker
local_limit_tracker LocalLimitTracker New version of LocalLimitTracker or masked difference, depending on mask_changes instrumentation of issued [WatchLocalLimitTrackerRequest] or [WatchLocalLimitTrackersRequest]
field_mask .google.protobuf.FieldMask Used when mask_changes is set, contains field paths of modified properties.
previous_view_index int32 Previous view index specifies previous position of modified LocalLimitTracker. When modification doesn’t affect sorted order, value will remain identical to [view_index].
view_index int32 Integer specifying LocalLimitTracker new index in resulting query view.

LocalLimitTrackerChange.Removed Message

Removed is returned when LocalLimitTracker is deleted or leaves Query view

Name Type Description
name string
view_index int32 Integer specifying removed LocalLimitTracker index. Not populated in stateless watch type.