Understanding the meta.edgelq.com service APIv1alpha2, in proto package ntt.meta.v1alpha2.

Service meta.edgelq.com in version v1alpha2, proto package ntt.meta.v1alpha2

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

Deployment Resource

Deployment Resource - describes meta information about deployment of a parent Service.

Name patterns:

  • regions/{region}/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.edgelq.com/permissions/deployments.get

The equivalent REST API is:

GET /v1alpha2/{name=regions/*/deployments/*}

BatchGetDeployments Method

BatchGetDeployments

rpc BatchGetDeployments(BatchGetDeploymentsRequest) returns (BatchGetDeploymentsResponse)

with the following messages:

Required Permissions:

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

The equivalent REST API is:

GET /v1alpha2/deployments:batchGet

ListDeployments Method

ListDeployments

rpc ListDeployments(ListDeploymentsRequest) returns (ListDeploymentsResponse)

with the following messages:

Required Permissions:

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

The equivalent REST API is:

GET /v1alpha2/{parent=regions/*}/deployments

WatchDeployment Method

WatchDeployment

rpc WatchDeployment(WatchDeploymentRequest) returns (WatchDeploymentResponse)

with the following messages:

Required Permissions:

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

The equivalent REST API is:

POST /v1alpha2/{name=regions/*/deployments/*}:watch

WatchDeployments Method

WatchDeployments

rpc WatchDeployments(WatchDeploymentsRequest) returns (WatchDeploymentsResponse)

with the following messages:

Required Permissions:

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

The equivalent REST API is:

POST /v1alpha2/{parent=regions/*}/deployments:watch

Deployment Messages

Here is the list of Deployment resource messages:

Deployment Message

Name Type Description
name string (name of Deployment) Name of Deployment 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-Z0-9_.-]{1,128}
service string (reference to Service) Deployed service
metadata Meta Metadata

GetDeploymentRequest Message

A request message of the GetDeployment method.

Name Type Description
name string (name of Deployment) Name of ntt.meta.v1alpha2.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 ntt.meta.v1alpha2.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 ntt.meta.v1alpha2.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 ntt.meta.v1alpha2.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.

Region Resource

Region Resource

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.edgelq.com/permissions/regions.get

The equivalent REST API is:

GET /v1alpha2/{name=regions/*}

BatchGetRegions Method

BatchGetRegions

rpc BatchGetRegions(BatchGetRegionsRequest) returns (BatchGetRegionsResponse)

with the following messages:

Required Permissions:

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

The equivalent REST API is:

GET /v1alpha2/regions:batchGet

ListRegions Method

ListRegions

rpc ListRegions(ListRegionsRequest) returns (ListRegionsResponse)

with the following messages:

Required Permissions:

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

The equivalent REST API is:

GET /v1alpha2/regions

WatchRegion Method

WatchRegion

rpc WatchRegion(WatchRegionRequest) returns (WatchRegionResponse)

with the following messages:

Required Permissions:

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

The equivalent REST API is:

POST /v1alpha2/{name=regions/*}:watch

WatchRegions Method

WatchRegions

rpc WatchRegions(WatchRegionsRequest) returns (WatchRegionsResponse)

with the following messages:

Required Permissions:

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

The equivalent REST API is:

POST /v1alpha2/regions:watch

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]
title string Region title
domain string Region domain, for example us-west.edgelq.com
location Region.RegionLocation Region location
is_default bool Whether is default. Only one record is allowed to have this attribute on.
connectivity_scores repeated Region.RegionConnectivityPreference Hardcoded scores regarding connectivity preference.
metadata Meta Metadata

Region.RegionLocation Message

RegionLocation describes deployment location of a region.

Name Type Description
continent string
country string
agglomeration string
city string
cloud string

Region.RegionConnectivityPreference Message

RegionConnectivityPreference is a hardcoded connectivity score to other region.

Name Type Description
dest string (reference to Region) Destination region
score int32 Hardcoded score

GetRegionRequest Message

A request message of the GetRegion method.

Name Type Description
name string (name of Region) Name of ntt.meta.v1alpha2.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 ntt.meta.v1alpha2.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.

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.edgelq.com/permissions/resources.get

The equivalent REST API is:

GET /v1alpha2/{name=services/*/resources/*}

BatchGetResources Method

BatchGetResources

rpc BatchGetResources(BatchGetResourcesRequest) returns (BatchGetResourcesResponse)

with the following messages:

Required Permissions:

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

The equivalent REST API is:

GET /v1alpha2/resources:batchGet

ListResources Method

ListResources

rpc ListResources(ListResourcesRequest) returns (ListResourcesResponse)

with the following messages:

Required Permissions:

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

The equivalent REST API is:

GET /v1alpha2/{parent=services/*}/resources

WatchResource Method

WatchResource

rpc WatchResource(WatchResourceRequest) returns (WatchResourceResponse)

with the following messages:

Required Permissions:

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

The equivalent REST API is:

POST /v1alpha2/{name=services/*/resources/*}:watch

WatchResources Method

WatchResources

rpc WatchResources(WatchResourcesRequest) returns (WatchResourcesResponse)

with the following messages:

Required Permissions:

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

The equivalent REST API is:

POST /v1alpha2/{parent=services/*}/resources:watch

Resource Messages

Here is the list of Resource resource messages:

Resource Message

Name Type Description
name string (name of Resource) Name of Resource in CamelCase, for example “Device”
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.
is_regional bool Whether resource is regional
metadata Meta Metadata

GetResourceRequest Message

A request message of the GetResource method.

Name Type Description
name string (name of Resource) Name of ntt.meta.v1alpha2.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 ntt.meta.v1alpha2.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 ntt.meta.v1alpha2.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 ntt.meta.v1alpha2.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.

Service Resource

Service Resource

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.edgelq.com/permissions/services.get

The equivalent REST API is:

GET /v1alpha2/{name=services/*}

BatchGetServices Method

BatchGetServices

rpc BatchGetServices(BatchGetServicesRequest) returns (BatchGetServicesResponse)

with the following messages:

Required Permissions:

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

The equivalent REST API is:

GET /v1alpha2/services:batchGet

ListServices Method

ListServices

rpc ListServices(ListServicesRequest) returns (ListServicesResponse)

with the following messages:

Required Permissions:

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

The equivalent REST API is:

GET /v1alpha2/services

WatchService Method

WatchService

rpc WatchService(WatchServiceRequest) returns (WatchServiceResponse)

with the following messages:

Required Permissions:

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

The equivalent REST API is:

POST /v1alpha2/{name=services/*}:watch

WatchServices Method

WatchServices

rpc WatchServices(WatchServicesRequest) returns (WatchServicesResponse)

with the following messages:

Required Permissions:

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

The equivalent REST API is:

POST /v1alpha2/services:watch

Service Messages

Here is the list of Service resource messages:

Service Message

Name Type Description
name string (name of Service) Name of Service - it has form of service domain, for example devices.edgelq.com, so full reference name would be like services/devices.edgelq.com
display_name string Display name, for example “Devices” - CamelVersion
current_version string Current version of the service, for example “v1alpha2”
all_versions repeated string All version in order from newest (index 0) to oldest
metadata Meta Metadata

GetServiceRequest Message

A request message of the GetService method.

Name Type Description
name string (name of Service) Name of ntt.meta.v1alpha2.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 ntt.meta.v1alpha2.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.

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.

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.