Understanding the meta.goten.com service APIv1, in proto package goten.meta.v1.

Service meta.goten.com in version v1, proto package goten.meta.v1

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

Deployment Resource

Deployment Resource describes deployment of service in specific regional cluster (may be multi-zonal). It contains accessibility details.

Name patterns:

  • services/{service}/deployments/{deployment}

Parent resources:

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

Deployment Methods

Here is the list of Deployment resource methods:

GetDeployment Method

GetDeployment

rpc GetDeployment(GetDeploymentRequest) returns (Deployment)

with the following messages:

Required Permissions:

  • services/meta.goten.com/permissions/deployments.get

The equivalent REST API is:

GET /meta/v1/{name=services/*/deployments/*}

BatchGetDeployments Method

BatchGetDeployments

rpc BatchGetDeployments(BatchGetDeploymentsRequest) returns (BatchGetDeploymentsResponse)

with the following messages:

Required Permissions:

  • services/meta.goten.com/permissions/deployments.batchGet

The equivalent REST API is:

GET /meta/v1/deployments:batchGet

ListDeployments Method

ListDeployments

rpc ListDeployments(ListDeploymentsRequest) returns (ListDeploymentsResponse)

with the following messages:

Required Permissions:

  • services/meta.goten.com/permissions/deployments.list

The equivalent REST API is:

GET /meta/v1/{parent=services/*}/deployments

WatchDeployment Method

WatchDeployment

rpc WatchDeployment(WatchDeploymentRequest) returns (WatchDeploymentResponse)

with the following messages:

Required Permissions:

  • services/meta.goten.com/permissions/deployments.watch

The equivalent REST API is:

POST /meta/v1/{name=services/*/deployments/*}:watch

WatchDeployments Method

WatchDeployments

rpc WatchDeployments(WatchDeploymentsRequest) returns (WatchDeploymentsResponse)

with the following messages:

Required Permissions:

  • services/meta.goten.com/permissions/deployments.watch

The equivalent REST API is:

POST /meta/v1/{parent=services/*}/deployments:watch

CreateDeployment Method

CreateDeployment

rpc CreateDeployment(CreateDeploymentRequest) returns (Deployment)

with the following messages:

Required Permissions:

  • services/meta.goten.com/permissions/deployments.create

The equivalent REST API is:

POST /meta/v1/{parent=services/*}/deployments (BODY: deployment)

UpdateDeployment Method

UpdateDeployment

rpc UpdateDeployment(UpdateDeploymentRequest) returns (Deployment)

with the following messages:

Required Permissions:

  • services/meta.goten.com/permissions/deployments.update

The equivalent REST API is:

PUT /meta/v1/{deployment.name=services/*/deployments/*} (BODY: deployment)

DeleteDeployment Method

DeleteDeployment

rpc DeleteDeployment(DeleteDeploymentRequest) returns (Empty)

with the following messages:

Required Permissions:

  • services/meta.goten.com/permissions/deployments.delete

The equivalent REST API is:

DELETE /meta/v1/{name=services/*/deployments/*}

BeginUpgrade Method

BeginUpgrade

rpc BeginUpgrade(BeginUpgradeRequest) returns (Empty)

with the following messages:

Required Permissions:

  • services/meta.goten.com/permissions/deployments.beginUpgrade

The equivalent REST API is:

POST /meta/v1/{name=services/*/deployments/*}:beginUpgrade

SetAvailableUpgrade Method

SetAvailableUpgrade

rpc SetAvailableUpgrade(SetAvailableUpgradeRequest) returns (Empty)

with the following messages:

Required Permissions:

  • services/meta.goten.com/permissions/deployments.setAvailableUpgrade

The equivalent REST API is:

POST /meta/v1/{name=services/*/deployments/*}:setAvailableUpgrade

NotifyShardsUpgradeReadiness Method

NotifyShardsUpgradeReadiness

rpc NotifyShardsUpgradeReadiness(NotifyShardsUpgradeReadinessRequest) returns (Empty)

with the following messages:

Required Permissions:

  • services/meta.goten.com/permissions/deployments.notifyShardsUpgradeReadiness

The equivalent REST API is:

POST /meta/v1/{name=services/*/deployments/*}:notifyShardsUpgradeReadiness

GetOrRegisterDataUpdateTask Method

GetOrRegisterDataUpdateTask

rpc GetOrRegisterDataUpdateTask(GetOrRegisterDataUpdateTaskRequest) returns (GetOrRegisterDataUpdateTaskResponse)

with the following messages:

Required Permissions:

  • services/meta.goten.com/permissions/deployments.getOrRegisterDataUpdateTask

The equivalent REST API is:

POST /meta/v1/{name=services/*/deployments/*}:getOrRegisterDataUpdateTask

UpdateDataTaskUpdate Method

UpdateDataTaskUpdate

rpc UpdateDataTaskUpdate(UpdateDataTaskUpdateRequest) returns (Empty)

with the following messages:

Required Permissions:

  • services/meta.goten.com/permissions/deployments.updateDataTaskUpdate

The equivalent REST API is:

POST /meta/v1/{name=services/*/deployments/*}:updateDataTaskUpdate

Deployment Messages

Here is the list of Deployment resource messages:

Deployment Message

Name Type Description
name string (name of Deployment) Name of Deployment ID must be exactly same as region ID it belongs to - it is populated automatically by Goten components.
metadata 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_name string Service display name - it is lowerCamelCase of service name, but not domain. It is taken from api-skeleton file, under “service.name” path.
region string (reference to Region) Informs in which region cluster running this deployment is located.
public_domain string Public domain indicates under which public address service in this particular region can be accessed.
private_domain string Private domain indicates how to access this service within local private network. However, this address should not be available for anyone outside network. It is only to be used by other service deployments that run within same private network for better performance purposes (less hops). It should be used in conjunction with field local_network_id.
labelled_domains repeated LabelledDomain Additional regional domains with labels where Deployment can be accessed.
local_network_id string Local network identifier - it can be mostly anything, however if two deployments for different services hold same value in same region, then Goten components will try to optimize access by using private_domain field instead of public_domain.
location Deployment.Location Location of given deployment. This value is likely to be equal for all deployments using same underlying cluster. It may be used by Goten to optimize multi-region routing.
is_disabled bool Whether this deployment is disabled. It does not trigger any deployment deletion - it will just notify others (in different regions) that its no longer available and no request should be routed there. It can be used as first step to delete deployment.
env_registry_generation int32 Generation number used by EnvRegistry config to generate this resource.
current_version string The current version of the service. Note this MAY not be the newest version! At the very least, if there was a fresh db upgrade, it will be old version till automatic upgrade finishes (or manual switch happens).
db_data_version string Current version of data in the database, it must follow convention v<Number>.<Number>… (may be more numbers). When deployment is created first time, value is set to the current value. If non-empty lower value is detected, db-controller may run update task locally. Do not confuse this field with “current_version”, which describes API version. If not populated, then “current”/“newest” should be assumed. current_version signals main API version by deployment, while db_data_version indicates underlying database data. It can be used for internal upgrades, database migrations, or simple in-place updates.
db_location_tag string Arbitrary database location tag. This should be used if database migration is needed (different endpoint, backend, namespace…).
automatic_version_switch bool If true, then switch to the new version will be automatic (if there is newer), once db upgrade finishes. Otherwise it will require manual call from operator.
available_upgrade Deployment.AvailableUpgrade
upgrade_state Deployment.UpgradeState Current state of the upgrade task.
data_update_statuses repeated Deployment.DbUpdateTaskStatus Tagged update statuses.

Deployment.Location Message

Location describes deployment location of this deployment. It may be used for multi-region routing to help determine closest deployment.

Name Type Description
continent string Continent
country string Country
agglomeration string Agglomeration
city string City
cloud string Cloud provider (like GCP, Azure, AWS…)

Deployment.UpgradeState Message

UpgradeState describes current state of database major upgrade. This corresponds to database migrations, API upgrades, other internal updates (if needed).

Name Type Description
target_version string
ready_shards repeated int64
pending_shards repeated int64
stage Deployment.UpgradeState.Stage
db_data_target_version string Value to switch once update is completed for db_data_version value.
db_target_location_tag string

Deployment.AvailableUpgrade Message

Name Type Description
api_version string
db_data_version string
db_location_tag string
total_shards_count int64

Deployment.DbUpdateTaskStatus Message

Name Type Description
task_tag string Identifying tag
shards_count int64 Shards count
ready_shards repeated int64 List of completed shards
target_version string Target data version
progress_bar repeated .google.protobuf.Struct Optional generic data submitted by task handler, in case of resharding/controller reboot.

GetDeploymentRequest Message

A request message of the GetDeployment method.

Name Type Description
name string (name of Deployment) Name of goten.meta.v1.Deployment
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 View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

BatchGetDeploymentsRequest Message

A request message of the BatchGetDeployments method.

Name Type Description
names repeated string (name of Deployment) Names of Deployments
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 View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

BatchGetDeploymentsResponse Message

A response message of the BatchGetDeployments method.

Name Type Description
deployments repeated Deployment found Deployments
missing repeated string (name of Deployment) list of not found Deployments

ListDeploymentsRequest Message

A request message of the ListDeployments method.

Name Type Description
parent string (parent name of Deployment) Parent name of goten.meta.v1.Deployment
page_size int32 Requested page size. Server may return fewer Deployments than requested. If unspecified, server will pick an appropriate default.
page_token string (cursor of Deployment) A token identifying a page of results the server should return. Typically, this is the value of ListDeploymentsResponse.next_page_token.
order_by string (orderBy of Deployment) 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 of Deployment) 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 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).

ListDeploymentsResponse Message

A response message of the ListDeployments method.

Name Type Description
deployments repeated Deployment The list of Deployments
prev_page_token string (cursor of Deployment) A token to retrieve previous page of results. Pass this value in the ListDeploymentsRequest.page_token.
next_page_token string (cursor of Deployment) A token to retrieve next page of results. Pass this value in the ListDeploymentsRequest.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 Deployments 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.

WatchDeploymentRequest Message

A request message of the WatchDeployment method.

Name Type Description
name string (name of Deployment) Name of goten.meta.v1.Deployment
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 View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

WatchDeploymentResponse Message

A response message of the WatchDeployment method.

Name Type Description
change DeploymentChange

WatchDeploymentsRequest Message

A request message of the WatchDeployments method.

Name Type Description
type 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 Deployment) Parent name of goten.meta.v1.Deployment
page_size int32 Requested page size. Server may return fewer Deployments than requested. If unspecified, server will pick an appropriate default. Can be populated only for stateful watch type.
page_token string (cursor of Deployment) A token identifying a page of results the server should return. Can be populated only for stateful watch type.
order_by string (orderBy of Deployment) 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 of Deployment) 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 Deployment that don’t affect any of masked fields won’t be sent back.
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask Changes to Deployment 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.

WatchDeploymentsResponse Message

A response message of the WatchDeployments method.

Name Type Description
deployment_changes repeated DeploymentChange Changes of Deployments
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 Deployments 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 WatchDeploymentsResponse.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 (Deployments 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.

WatchDeploymentsResponse.PageTokenChange Message

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

CreateDeploymentRequest Message

A request message of the CreateDeployment method.

Name Type Description
parent string (parent name of Deployment) Parent name of goten.meta.v1.Deployment
deployment Deployment Deployment resource body
response_mask CreateDeploymentRequest.ResponseMask Optional masking applied to response object to reduce message response size.

CreateDeploymentRequest.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.

UpdateDeploymentRequest Message

A request message of the UpdateDeployment method.

Name Type Description
deployment Deployment Deployment resource body
update_mask .google.protobuf.FieldMask FieldMask applied to request - change will be applied only for fields in the mask
cas UpdateDeploymentRequest.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 UpdateDeploymentRequest.ResponseMask reduce message response size.

UpdateDeploymentRequest.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 Deployment 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.

UpdateDeploymentRequest.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.

DeleteDeploymentRequest Message

A request message of the DeleteDeployment method.

Name Type Description
name string (name of Deployment) Name of goten.meta.v1.Deployment

BeginUpgradeRequest Message

Request message for method [BeginUpgrade][goten.meta.v1.BeginUpgrade]

Name Type Description
name string (name of Deployment) name of goten.meta.v1.Deployment

SetAvailableUpgradeRequest Message

Request message for method [SetAvailableUpgrade][goten.meta.v1.SetAvailableUpgrade]

Name Type Description
name string (name of Deployment) name of goten.meta.v1.Deployment
target_api_version string
total_shards_count int64
target_db_data_version string
target_db_location_tag string

NotifyShardsUpgradeReadinessRequest Message

Request message for method [NotifyShardsUpgradeReadiness][goten.meta.v1.NotifyShardsUpgradeReadiness]

Name Type Description
name string (name of Deployment) name of goten.meta.v1.Deployment
shards_from int64
shards_to int64
ready bool
total_shards_count int64

GetOrRegisterDataUpdateTaskRequest Message

Request message for method [GetOrRegisterDataUpdateTask][goten.meta.v1.GetOrRegisterDataUpdateTask]

Name Type Description
name string (name of Deployment) name of goten.meta.v1.Deployment
tag string Data task tag
shards_count int64 Number of shards
db_data_target_version string Db data target version

GetOrRegisterDataUpdateTaskResponse Message

Response message for method [GetOrRegisterDataUpdateTask][goten.meta.v1.GetOrRegisterDataUpdateTask]

Name Type Description
status Deployment.DbUpdateTaskStatus

UpdateDataTaskUpdateRequest Message

Request message for method [UpdateDataTaskUpdate][goten.meta.v1.UpdateDataTaskUpdate]

Name Type Description
name string (name of Deployment) name of goten.meta.v1.Deployment
tag string Data task tag
shard int64 Number of shards
done bool Whether it is completed
progress_status .google.protobuf.Struct Information about progress
db_data_target_version string Db data target version

Deployment Enumerations

Here is the list of Deployment resource enumerations:

Deployment.UpgradeState.Stage Enumeration

Name Description
READY
INITIAL_SYNCING
SWITCHING

Region Resource

Region Resource is an auxiliary resource that provides geographic scope to resources in Goten services, ideally should point to narrow geographic location but Goten is not strict about it. This allows case where in single physical location we have multiple clusters using different virtual networks hosting different deployments. Goten uses regions to aid in global scaling, but otherwise tries to abstract from running hardware focusing on services instead.

Name patterns:

  • regions/{region}

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

Region Methods

Here is the list of Region resource methods:

GetRegion Method

GetRegion

rpc GetRegion(GetRegionRequest) returns (Region)

with the following messages:

Required Permissions:

  • services/meta.goten.com/permissions/regions.get

The equivalent REST API is:

GET /meta/v1/{name=regions/*}

BatchGetRegions Method

BatchGetRegions

rpc BatchGetRegions(BatchGetRegionsRequest) returns (BatchGetRegionsResponse)

with the following messages:

Required Permissions:

  • services/meta.goten.com/permissions/regions.batchGet

The equivalent REST API is:

GET /meta/v1/regions:batchGet

ListRegions Method

ListRegions

rpc ListRegions(ListRegionsRequest) returns (ListRegionsResponse)

with the following messages:

Required Permissions:

  • services/meta.goten.com/permissions/regions.list

The equivalent REST API is:

GET /meta/v1/regions

WatchRegion Method

WatchRegion

rpc WatchRegion(WatchRegionRequest) returns (WatchRegionResponse)

with the following messages:

Required Permissions:

  • services/meta.goten.com/permissions/regions.watch

The equivalent REST API is:

POST /meta/v1/{name=regions/*}:watch

WatchRegions Method

WatchRegions

rpc WatchRegions(WatchRegionsRequest) returns (WatchRegionsResponse)

with the following messages:

Required Permissions:

  • services/meta.goten.com/permissions/regions.watch

The equivalent REST API is:

POST /meta/v1/regions:watch

CreateRegion Method

CreateRegion

rpc CreateRegion(CreateRegionRequest) returns (Region)

with the following messages:

Required Permissions:

  • services/meta.goten.com/permissions/regions.create

The equivalent REST API is:

POST /meta/v1/regions (BODY: region)

UpdateRegion Method

UpdateRegion

rpc UpdateRegion(UpdateRegionRequest) returns (Region)

with the following messages:

Required Permissions:

  • services/meta.goten.com/permissions/regions.update

The equivalent REST API is:

PUT /meta/v1/{region.name=regions/*} (BODY: region)

DeleteRegion Method

DeleteRegion

rpc DeleteRegion(DeleteRegionRequest) returns (Empty)

with the following messages:

Required Permissions:

  • services/meta.goten.com/permissions/regions.delete

The equivalent REST API is:

DELETE /meta/v1/{name=regions/*}

Region Messages

Here is the list of Region resource messages:

Region Message

Name Type Description
name string (name of Region) Name of Region When creating a new instance, this field is optional and if not provided, it will be generated automatically. Last ID segment must conform to the following regex: [a-z][a-z0-9\-]{0,28}[a-z0-9]
metadata 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).
title string Region title

GetRegionRequest Message

A request message of the GetRegion method.

Name Type Description
name string (name of Region) Name of goten.meta.v1.Region
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 View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

BatchGetRegionsRequest Message

A request message of the BatchGetRegions method.

Name Type Description
names repeated string (name of Region) Names of Regions
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 View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

BatchGetRegionsResponse Message

A response message of the BatchGetRegions method.

Name Type Description
regions repeated Region found Regions
missing repeated string (name of Region) list of not found Regions

ListRegionsRequest Message

A request message of the ListRegions method.

Name Type Description
page_size int32 Requested page size. Server may return fewer Regions than requested. If unspecified, server will pick an appropriate default.
page_token string (cursor of Region) A token identifying a page of results the server should return. Typically, this is the value of ListRegionsResponse.next_page_token.
order_by string (orderBy of Region) 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 of Region) 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 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).

ListRegionsResponse Message

A response message of the ListRegions method.

Name Type Description
regions repeated Region The list of Regions
prev_page_token string (cursor of Region) A token to retrieve previous page of results. Pass this value in the ListRegionsRequest.page_token.
next_page_token string (cursor of Region) A token to retrieve next page of results. Pass this value in the ListRegionsRequest.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 Regions 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.

WatchRegionRequest Message

A request message of the WatchRegion method.

Name Type Description
name string (name of Region) Name of goten.meta.v1.Region
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 View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

WatchRegionResponse Message

A response message of the WatchRegion method.

Name Type Description
change RegionChange

WatchRegionsRequest Message

A request message of the WatchRegions method.

Name Type Description
type 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.
page_size int32 Requested page size. Server may return fewer Regions than requested. If unspecified, server will pick an appropriate default. Can be populated only for stateful watch type.
page_token string (cursor of Region) A token identifying a page of results the server should return. Can be populated only for stateful watch type.
order_by string (orderBy of Region) 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 of Region) 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 Region that don’t affect any of masked fields won’t be sent back.
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask Changes to Region 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.

WatchRegionsResponse Message

A response message of the WatchRegions method.

Name Type Description
region_changes repeated RegionChange Changes of Regions
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 Regions 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 WatchRegionsResponse.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 (Regions 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.

WatchRegionsResponse.PageTokenChange Message

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

CreateRegionRequest Message

A request message of the CreateRegion method.

Name Type Description
region Region Region resource body
response_mask CreateRegionRequest.ResponseMask Optional masking applied to response object to reduce message response size.

CreateRegionRequest.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.

UpdateRegionRequest Message

A request message of the UpdateRegion method.

Name Type Description
region Region Region resource body
update_mask .google.protobuf.FieldMask FieldMask applied to request - change will be applied only for fields in the mask
cas UpdateRegionRequest.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 UpdateRegionRequest.ResponseMask reduce message response size.

UpdateRegionRequest.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 Region 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.

UpdateRegionRequest.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.

DeleteRegionRequest Message

A request message of the DeleteRegion method.

Name Type Description
name string (name of Region) Name of goten.meta.v1.Region

Resource Resource

Resource Resource

Name patterns:

  • services/{service}/resources/{resource}

Parent resources:

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

Resource Methods

Here is the list of Resource resource methods:

GetResource Method

GetResource

rpc GetResource(GetResourceRequest) returns (Resource)

with the following messages:

Required Permissions:

  • services/meta.goten.com/permissions/resources.get

The equivalent REST API is:

GET /meta/v1/{name=services/*/resources/*}

BatchGetResources Method

BatchGetResources

rpc BatchGetResources(BatchGetResourcesRequest) returns (BatchGetResourcesResponse)

with the following messages:

Required Permissions:

  • services/meta.goten.com/permissions/resources.batchGet

The equivalent REST API is:

GET /meta/v1/resources:batchGet

ListResources Method

ListResources

rpc ListResources(ListResourcesRequest) returns (ListResourcesResponse)

with the following messages:

Required Permissions:

  • services/meta.goten.com/permissions/resources.list

The equivalent REST API is:

GET /meta/v1/{parent=services/*}/resources

WatchResource Method

WatchResource

rpc WatchResource(WatchResourceRequest) returns (WatchResourceResponse)

with the following messages:

Required Permissions:

  • services/meta.goten.com/permissions/resources.watch

The equivalent REST API is:

POST /meta/v1/{name=services/*/resources/*}:watch

WatchResources Method

WatchResources

rpc WatchResources(WatchResourcesRequest) returns (WatchResourcesResponse)

with the following messages:

Required Permissions:

  • services/meta.goten.com/permissions/resources.watch

The equivalent REST API is:

POST /meta/v1/{parent=services/*}/resources:watch

CreateResource Method

CreateResource

rpc CreateResource(CreateResourceRequest) returns (Resource)

with the following messages:

Required Permissions:

  • services/meta.goten.com/permissions/resources.create

The equivalent REST API is:

POST /meta/v1/{parent=services/*}/resources (BODY: resource)

UpdateResource Method

UpdateResource

rpc UpdateResource(UpdateResourceRequest) returns (Resource)

with the following messages:

Required Permissions:

  • services/meta.goten.com/permissions/resources.update

The equivalent REST API is:

PUT /meta/v1/{resource.name=services/*/resources/*} (BODY: resource)

DeleteResource Method

DeleteResource

rpc DeleteResource(DeleteResourceRequest) returns (Empty)

with the following messages:

Required Permissions:

  • services/meta.goten.com/permissions/resources.delete

The equivalent REST API is:

DELETE /meta/v1/{name=services/*/resources/*}

Resource Messages

Here is the list of Resource resource messages:

Resource Message

Name Type Description
name string (name of Resource) Name of Resource When creating a new instance, this field is optional and if not provided, it will be generated automatically. Last ID segment must conform to the following regex: [a-zA-Z]{1,128}
metadata 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).
plural_name string Plural name of resource in CamelForm, for example “Devices”
fqn string Fully qualified name, for example devices.edgelq.com/Device. It can also be derived from name too.
versions repeated string List of service versions where this resource is known. This list will be sorted if created by meta service provided by Goten. The newest version is first, the oldest last.
versioned_infos repeated Resource.VersionedInfo Versioned information holds values that may be valid for specific versions only. Sorted exactly like versions list.

Resource.VersionedInfo Message

VersionedInfo contains specification part that is versioned.

Name Type Description
version string Resource version this information applies to.
is_regional bool Whether resource is regional.

GetResourceRequest Message

A request message of the GetResource method.

Name Type Description
name string (name of Resource) Name of goten.meta.v1.Resource
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 View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

BatchGetResourcesRequest Message

A request message of the BatchGetResources method.

Name Type Description
names repeated string (name of Resource) Names of Resources
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 View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

BatchGetResourcesResponse Message

A response message of the BatchGetResources method.

Name Type Description
resources repeated Resource found Resources
missing repeated string (name of Resource) list of not found Resources

ListResourcesRequest Message

A request message of the ListResources method.

Name Type Description
parent string (parent name of Resource) Parent name of goten.meta.v1.Resource
page_size int32 Requested page size. Server may return fewer Resources than requested. If unspecified, server will pick an appropriate default.
page_token string (cursor of Resource) A token identifying a page of results the server should return. Typically, this is the value of ListResourcesResponse.next_page_token.
order_by string (orderBy of Resource) 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 of Resource) 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 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).

ListResourcesResponse Message

A response message of the ListResources method.

Name Type Description
resources repeated Resource The list of Resources
prev_page_token string (cursor of Resource) A token to retrieve previous page of results. Pass this value in the ListResourcesRequest.page_token.
next_page_token string (cursor of Resource) A token to retrieve next page of results. Pass this value in the ListResourcesRequest.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 Resources 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.

WatchResourceRequest Message

A request message of the WatchResource method.

Name Type Description
name string (name of Resource) Name of goten.meta.v1.Resource
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 View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

WatchResourceResponse Message

A response message of the WatchResource method.

Name Type Description
change ResourceChange

WatchResourcesRequest Message

A request message of the WatchResources method.

Name Type Description
type 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 Resource) Parent name of goten.meta.v1.Resource
page_size int32 Requested page size. Server may return fewer Resources than requested. If unspecified, server will pick an appropriate default. Can be populated only for stateful watch type.
page_token string (cursor of Resource) A token identifying a page of results the server should return. Can be populated only for stateful watch type.
order_by string (orderBy of Resource) 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 of Resource) 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 Resource that don’t affect any of masked fields won’t be sent back.
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask Changes to Resource 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.

WatchResourcesResponse Message

A response message of the WatchResources method.

Name Type Description
resource_changes repeated ResourceChange Changes of Resources
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 Resources 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 WatchResourcesResponse.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 (Resources 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.

WatchResourcesResponse.PageTokenChange Message

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

CreateResourceRequest Message

A request message of the CreateResource method.

Name Type Description
parent string (parent name of Resource) Parent name of goten.meta.v1.Resource
resource Resource Resource resource body
response_mask CreateResourceRequest.ResponseMask Optional masking applied to response object to reduce message response size.

CreateResourceRequest.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.

UpdateResourceRequest Message

A request message of the UpdateResource method.

Name Type Description
resource Resource Resource resource body
update_mask .google.protobuf.FieldMask FieldMask applied to request - change will be applied only for fields in the mask
cas UpdateResourceRequest.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 UpdateResourceRequest.ResponseMask reduce message response size.

UpdateResourceRequest.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 Resource 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.

UpdateResourceRequest.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.

DeleteResourceRequest Message

A request message of the DeleteResource method.

Name Type Description
name string (name of Resource) Name of goten.meta.v1.Resource

Service Resource

Service Resource contains service description like domain under which it can be accessed, versions, imported services and their versions.

Name patterns:

  • services/{service}

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

Service Methods

Here is the list of Service resource methods:

GetService Method

GetService

rpc GetService(GetServiceRequest) returns (Service)

with the following messages:

Required Permissions:

  • services/meta.goten.com/permissions/services.get

The equivalent REST API is:

GET /meta/v1/{name=services/*}

BatchGetServices Method

BatchGetServices

rpc BatchGetServices(BatchGetServicesRequest) returns (BatchGetServicesResponse)

with the following messages:

Required Permissions:

  • services/meta.goten.com/permissions/services.batchGet

The equivalent REST API is:

GET /meta/v1/services:batchGet

ListServices Method

ListServices

rpc ListServices(ListServicesRequest) returns (ListServicesResponse)

with the following messages:

Required Permissions:

  • services/meta.goten.com/permissions/services.list

The equivalent REST API is:

GET /meta/v1/services

WatchService Method

WatchService

rpc WatchService(WatchServiceRequest) returns (WatchServiceResponse)

with the following messages:

Required Permissions:

  • services/meta.goten.com/permissions/services.watch

The equivalent REST API is:

POST /meta/v1/{name=services/*}:watch

WatchServices Method

WatchServices

rpc WatchServices(WatchServicesRequest) returns (WatchServicesResponse)

with the following messages:

Required Permissions:

  • services/meta.goten.com/permissions/services.watch

The equivalent REST API is:

POST /meta/v1/services:watch

CreateService Method

CreateService

rpc CreateService(CreateServiceRequest) returns (Service)

with the following messages:

Required Permissions:

  • services/meta.goten.com/permissions/services.create

The equivalent REST API is:

POST /meta/v1/services (BODY: service)

UpdateService Method

UpdateService

rpc UpdateService(UpdateServiceRequest) returns (Service)

with the following messages:

Required Permissions:

  • services/meta.goten.com/permissions/services.update

The equivalent REST API is:

PUT /meta/v1/{service.name=services/*} (BODY: service)

DeleteService Method

DeleteService

rpc DeleteService(DeleteServiceRequest) returns (Empty)

with the following messages:

Required Permissions:

  • services/meta.goten.com/permissions/services.delete

The equivalent REST API is:

DELETE /meta/v1/{name=services/*}

Service Messages

Here is the list of Service resource messages:

Service Message

Name Type Description
name string (name of Service) Name of Service When creating a new instance, this field is optional and if not provided, it will be generated automatically. Last ID segment must conform to the following regex: [a-z][a-z0-9\-.]{0,28}[a-z0-9]
metadata 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).
multi_region_policy MultiRegionPolicy Multi region policy defines in which region all kid resources (and their kids) will by default belong and cross-region syncing policies.
display_name string Service display name - it is lowerCamelCase of service name, but not domain. It is taken from api-skeleton file, under “service.name” path.
all_versions repeated string All supported versions. This list will be sorted if created by meta service provided by Goten. The newest version is first, the oldest last.
global_domain string Globally available domain for this service. Requests to it should direct to most suitable (usually the nearest/healthy/most performant) region.
labelled_domains repeated LabelledDomain Additional global domains with labels.
leading_service string (name of Service) If given service is part of service group, this value points to the leading service.
imported_services repeated string (reference to Service) All imported on schema-level services. This list declares that resources in those services can be referenced by this service.
used_services repeated string (reference to Service) All used services. Unlike imported, they are not imported on schema level. Its just a declaration that given service may access other services, but does not try to establish any references.
imported_versions repeated Service.ImportedVersions Information containing which imported service version is used by current service version. This does not include any used services.
env_registry_generation int32 Generation number used by EnvRegistry config to generate this resource.
automatic_version_switch bool If true, then switch to the new version will be automatic (if there is newer), once db upgrade finishes. Otherwise it will require manual call from operator.

Service.ImportedVersions Message

ImportedVersions contains information which version of the imported service is used by current service in specific version.

Name Type Description
target_service string (reference to Service) Imported service reference
target_service_version string Version of the imported service
current_service_version string Version of the current service that imports target service in its version.

GetServiceRequest Message

A request message of the GetService method.

Name Type Description
name string (name of Service) Name of goten.meta.v1.Service
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 View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

BatchGetServicesRequest Message

A request message of the BatchGetServices method.

Name Type Description
names repeated string (name of Service) Names of Services
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 View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

BatchGetServicesResponse Message

A response message of the BatchGetServices method.

Name Type Description
services repeated Service found Services
missing repeated string (name of Service) list of not found Services

ListServicesRequest Message

A request message of the ListServices method.

Name Type Description
page_size int32 Requested page size. Server may return fewer Services than requested. If unspecified, server will pick an appropriate default.
page_token string (cursor of Service) A token identifying a page of results the server should return. Typically, this is the value of ListServicesResponse.next_page_token.
order_by string (orderBy of Service) 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 of Service) 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 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).

ListServicesResponse Message

A response message of the ListServices method.

Name Type Description
services repeated Service The list of Services
prev_page_token string (cursor of Service) A token to retrieve previous page of results. Pass this value in the ListServicesRequest.page_token.
next_page_token string (cursor of Service) A token to retrieve next page of results. Pass this value in the ListServicesRequest.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 Services 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.

WatchServiceRequest Message

A request message of the WatchService method.

Name Type Description
name string (name of Service) Name of goten.meta.v1.Service
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 View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

WatchServiceResponse Message

A response message of the WatchService method.

Name Type Description
change ServiceChange

WatchServicesRequest Message

A request message of the WatchServices method.

Name Type Description
type 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.
page_size int32 Requested page size. Server may return fewer Services than requested. If unspecified, server will pick an appropriate default. Can be populated only for stateful watch type.
page_token string (cursor of Service) A token identifying a page of results the server should return. Can be populated only for stateful watch type.
order_by string (orderBy of Service) 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 of Service) 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 Service that don’t affect any of masked fields won’t be sent back.
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask Changes to Service 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.

WatchServicesResponse Message

A response message of the WatchServices method.

Name Type Description
service_changes repeated ServiceChange Changes of Services
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 Services 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 WatchServicesResponse.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 (Services 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.

WatchServicesResponse.PageTokenChange Message

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

CreateServiceRequest Message

A request message of the CreateService method.

Name Type Description
service Service Service resource body
response_mask CreateServiceRequest.ResponseMask Optional masking applied to response object to reduce message response size.

CreateServiceRequest.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.

UpdateServiceRequest Message

A request message of the UpdateService method.

Name Type Description
service Service Service resource body
update_mask .google.protobuf.FieldMask FieldMask applied to request - change will be applied only for fields in the mask
cas UpdateServiceRequest.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 UpdateServiceRequest.ResponseMask reduce message response size.

UpdateServiceRequest.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 Service 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.

UpdateServiceRequest.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.

DeleteServiceRequest Message

A request message of the DeleteService method.

Name Type Description
name string (name of Service) Name of goten.meta.v1.Service

Meta Service Shared Methods and Messages

Meta Service Shared Messages

Here is the list of Meta service shared messages:

DeploymentChange Message

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

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

DeploymentChange.Added Message

Deployment has been added to query view

Name Type Description
deployment Deployment
view_index int32 Integer describing index of added Deployment in resulting query view.

DeploymentChange.Current Message

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

Name Type Description
deployment Deployment

DeploymentChange.Modified Message

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

Name Type Description
name string (name of Deployment) Name of modified Deployment
deployment Deployment New version of Deployment or masked difference, depending on mask_changes instrumentation of issued [WatchDeploymentRequest] or [WatchDeploymentsRequest]
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 Deployment. When modification doesn’t affect sorted order, value will remain identical to [view_index].
view_index int32 Integer specifying Deployment new index in resulting query view.

DeploymentChange.Removed Message

Removed is returned when Deployment is deleted or leaves Query view

Name Type Description
name string (name of Deployment)
view_index int32 Integer specifying removed Deployment index. Not populated in stateless watch type.

LabelledDomain Message

LabelledDomain provides connectivity information in a context of Service and specific label. Service/Deployment may provide multiple addresses, for example offering different quality class, like optimized for high/low throughput.

Name Type Description
label string
domain string
available_mixins repeated string
web_grpc_available bool
rest_api_available bool
is_private bool

RegionChange Message

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

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

RegionChange.Added Message

Region has been added to query view

Name Type Description
region Region
view_index int32 Integer describing index of added Region in resulting query view.

RegionChange.Current Message

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

Name Type Description
region Region

RegionChange.Modified Message

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

Name Type Description
name string (name of Region) Name of modified Region
region Region New version of Region or masked difference, depending on mask_changes instrumentation of issued [WatchRegionRequest] or [WatchRegionsRequest]
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 Region. When modification doesn’t affect sorted order, value will remain identical to [view_index].
view_index int32 Integer specifying Region new index in resulting query view.

RegionChange.Removed Message

Removed is returned when Region is deleted or leaves Query view

Name Type Description
name string (name of Region)
view_index int32 Integer specifying removed Region index. Not populated in stateless watch type.

ResourceChange Message

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

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

ResourceChange.Added Message

Resource has been added to query view

Name Type Description
resource Resource
view_index int32 Integer describing index of added Resource in resulting query view.

ResourceChange.Current Message

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

Name Type Description
resource Resource

ResourceChange.Modified Message

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

Name Type Description
name string (name of Resource) Name of modified Resource
resource Resource New version of Resource or masked difference, depending on mask_changes instrumentation of issued [WatchResourceRequest] or [WatchResourcesRequest]
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 Resource. When modification doesn’t affect sorted order, value will remain identical to [view_index].
view_index int32 Integer specifying Resource new index in resulting query view.

ResourceChange.Removed Message

Removed is returned when Resource is deleted or leaves Query view

Name Type Description
name string (name of Resource)
view_index int32 Integer specifying removed Resource index. Not populated in stateless watch type.

ServiceChange Message

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

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

ServiceChange.Added Message

Service has been added to query view

Name Type Description
service Service
view_index int32 Integer describing index of added Service in resulting query view.

ServiceChange.Current Message

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

Name Type Description
service Service

ServiceChange.Modified Message

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

Name Type Description
name string (name of Service) Name of modified Service
service Service New version of Service or masked difference, depending on mask_changes instrumentation of issued [WatchServiceRequest] or [WatchServicesRequest]
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 Service. When modification doesn’t affect sorted order, value will remain identical to [view_index].
view_index int32 Integer specifying Service new index in resulting query view.

ServiceChange.Removed Message

Removed is returned when Service is deleted or leaves Query view

Name Type Description
name string (name of Service)
view_index int32 Integer specifying removed Service index. Not populated in stateless watch type.