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
Region resource
Resource resource
Service resource

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:

Service

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:

GetDeploymentRequest request message
Deployment response message

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:

BatchGetDeploymentsRequest request message
BatchGetDeploymentsResponse response message

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:

ListDeploymentsRequest request message
ListDeploymentsResponse response message

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:

WatchDeploymentRequest request message
WatchDeploymentResponse response message

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:

WatchDeploymentsRequest request message
WatchDeploymentsResponse response message

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:

CreateDeploymentRequest request message
Deployment response message

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:

UpdateDeploymentRequest request message
Deployment response message

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:

DeleteDeploymentRequest request message
Empty response message

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:

BeginUpgradeRequest request message
Empty response message

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:

SetAvailableUpgradeRequest request message
Empty response message

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:

NotifyShardsUpgradeReadinessRequest request message
Empty response message

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:

GetOrRegisterDataUpdateTaskRequest request message
GetOrRegisterDataUpdateTaskResponse response message

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:

UpdateDataTaskUpdateRequest request message
Empty response message

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
Deployment.Location message
Deployment.UpgradeState message
Deployment.AvailableUpgrade message
Deployment.DbUpdateTaskStatus message
GetDeploymentRequest message
BatchGetDeploymentsRequest message
BatchGetDeploymentsResponse message
ListDeploymentsRequest message
ListDeploymentsResponse message
WatchDeploymentRequest message
WatchDeploymentResponse message
WatchDeploymentsRequest message
WatchDeploymentsResponse message
WatchDeploymentsResponse.PageTokenChange message
CreateDeploymentRequest message
CreateDeploymentRequest.ResponseMask message
UpdateDeploymentRequest message
UpdateDeploymentRequest.CAS message
UpdateDeploymentRequest.ResponseMask message
DeleteDeploymentRequest message
BeginUpgradeRequest message
SetAvailableUpgradeRequest message
NotifyShardsUpgradeReadinessRequest message
GetOrRegisterDataUpdateTaskRequest message
GetOrRegisterDataUpdateTaskResponse message
UpdateDataTaskUpdateRequest message

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
allow_missing	bool	If set to true, and the resource is not found, method will be successful and will not return NotFound error.

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

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
BatchGetRegions method
ListRegions method
WatchRegion method
WatchRegions method
CreateRegion method
UpdateRegion method
DeleteRegion method

GetRegion Method

GetRegion

rpc GetRegion(GetRegionRequest) returns (Region)

with the following messages:

GetRegionRequest request message
Region response message

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:

BatchGetRegionsRequest request message
BatchGetRegionsResponse response message

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:

ListRegionsRequest request message
ListRegionsResponse response message

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:

WatchRegionRequest request message
WatchRegionResponse response message

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:

WatchRegionsRequest request message
WatchRegionsResponse response message

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:

CreateRegionRequest request message
Region response message

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:

UpdateRegionRequest request message
Region response message

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:

DeleteRegionRequest request message
Empty response message

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
GetRegionRequest message
BatchGetRegionsRequest message
BatchGetRegionsResponse message
ListRegionsRequest message
ListRegionsResponse message
WatchRegionRequest message
WatchRegionResponse message
WatchRegionsRequest message
WatchRegionsResponse message
WatchRegionsResponse.PageTokenChange message
CreateRegionRequest message
CreateRegionRequest.ResponseMask message
UpdateRegionRequest message
UpdateRegionRequest.CAS message
UpdateRegionRequest.ResponseMask message
DeleteRegionRequest message

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
allow_missing	bool	If set to true, and the resource is not found, method will be successful and will not return NotFound error.

Resource Resource

Name patterns:

services/{service}/resources/{resource}

Parent resources:

Service

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:

GetResourceRequest request message
Resource response message

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:

BatchGetResourcesRequest request message
BatchGetResourcesResponse response message

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:

ListResourcesRequest request message
ListResourcesResponse response message

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:

WatchResourceRequest request message
WatchResourceResponse response message

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:

WatchResourcesRequest request message
WatchResourcesResponse response message

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:

CreateResourceRequest request message
Resource response message

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:

UpdateResourceRequest request message
Resource response message

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:

DeleteResourceRequest request message
Empty response message

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
Resource.VersionedInfo message
GetResourceRequest message
BatchGetResourcesRequest message
BatchGetResourcesResponse message
ListResourcesRequest message
ListResourcesResponse message
WatchResourceRequest message
WatchResourceResponse message
WatchResourcesRequest message
WatchResourcesResponse message
WatchResourcesResponse.PageTokenChange message
CreateResourceRequest message
CreateResourceRequest.ResponseMask message
UpdateResourceRequest message
UpdateResourceRequest.CAS message
UpdateResourceRequest.ResponseMask message
DeleteResourceRequest message

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
allow_missing	bool	If set to true, and the resource is not found, method will be successful and will not return NotFound error.

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:

GetServiceRequest request message
Service response message

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:

BatchGetServicesRequest request message
BatchGetServicesResponse response message

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:

ListServicesRequest request message
ListServicesResponse response message

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:

WatchServiceRequest request message
WatchServiceResponse response message

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:

WatchServicesRequest request message
WatchServicesResponse response message

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:

CreateServiceRequest request message
Service response message

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:

UpdateServiceRequest request message
Service response message

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:

DeleteServiceRequest request message
Empty response message

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
Service.ImportedVersions message
GetServiceRequest message
BatchGetServicesRequest message
BatchGetServicesResponse message
ListServicesRequest message
ListServicesResponse message
WatchServiceRequest message
WatchServiceResponse message
WatchServicesRequest message
WatchServicesResponse message
WatchServicesResponse.PageTokenChange message
CreateServiceRequest message
CreateServiceRequest.ResponseMask message
UpdateServiceRequest message
UpdateServiceRequest.CAS message
UpdateServiceRequest.ResponseMask message
DeleteServiceRequest message

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
allow_missing	bool	If set to true, and the resource is not found, method will be successful and will not return NotFound error.

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.