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

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

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

Project Resource

Project Resource

Name patterns:

  • projects/{project}

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

Project Methods

Here is the list of Project resource methods:

Connect Method

Connect

rpc Connect(ConnectRequest) returns (ConnectResponse)

with the following messages:

Required Permissions:

  • services/proxies.edgelq.com/permissions/projects.connect

The equivalent REST API is:

POST /v1alpha2:connect

Listen Method

Listen

rpc Listen(ListenRequest) returns (ListenResponse)

with the following messages:

Required Permissions:

  • services/proxies.edgelq.com/permissions/projects.listen

The equivalent REST API is:

POST /v1alpha2:listen

Accept Method

Accept

rpc Accept(AcceptRequest) returns (AcceptResponse)

with the following messages:

Required Permissions:

  • services/proxies.edgelq.com/permissions/projects.accept

The equivalent REST API is:

POST /v1alpha2:accept

GetProject Method

GetProject

rpc GetProject(GetProjectRequest) returns (Project)

with the following messages:

Required Permissions:

  • services/proxies.edgelq.com/permissions/projects.get

The equivalent REST API is:

GET /v1alpha2/{name=projects/*}

BatchGetProjects Method

BatchGetProjects

rpc BatchGetProjects(BatchGetProjectsRequest) returns (BatchGetProjectsResponse)

with the following messages:

Required Permissions:

  • services/proxies.edgelq.com/permissions/projects.batchGet

The equivalent REST API is:

GET /v1alpha2/projects:batchGet

ListProjects Method

ListProjects

rpc ListProjects(ListProjectsRequest) returns (ListProjectsResponse)

with the following messages:

Required Permissions:

  • services/proxies.edgelq.com/permissions/projects.list

The equivalent REST API is:

GET /v1alpha2/projects

WatchProject Method

WatchProject

rpc WatchProject(WatchProjectRequest) returns (WatchProjectResponse)

with the following messages:

Required Permissions:

  • services/proxies.edgelq.com/permissions/projects.watch

The equivalent REST API is:

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

WatchProjects Method

WatchProjects

rpc WatchProjects(WatchProjectsRequest) returns (WatchProjectsResponse)

with the following messages:

Required Permissions:

  • services/proxies.edgelq.com/permissions/projects.watch

The equivalent REST API is:

POST /v1alpha2/projects:watch

CreateProject Method

CreateProject

rpc CreateProject(CreateProjectRequest) returns (Project)

with the following messages:

Required Permissions:

  • services/proxies.edgelq.com/permissions/projects.create

The equivalent REST API is:

POST /v1alpha2/projects (BODY: project)

UpdateProject Method

UpdateProject

rpc UpdateProject(UpdateProjectRequest) returns (Project)

with the following messages:

Required Permissions:

  • services/proxies.edgelq.com/permissions/projects.update

The equivalent REST API is:

PUT /v1alpha2/{project.name=projects/*} (BODY: project)

DeleteProject Method

DeleteProject

rpc DeleteProject(DeleteProjectRequest) returns (Empty)

with the following messages:

Required Permissions:

  • services/proxies.edgelq.com/permissions/projects.delete

The equivalent REST API is:

DELETE /v1alpha2/{name=projects/*}

Project Messages

Here is the list of Project resource messages:

Project Message

Name Type Description
name string (name of Project) Name of Project 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
multi_region_policy MultiRegionPolicy Multi region policy

ConnectRequest Message

Request message for method [Connect][ntt.proxies.v1alpha2.Connect]

Name Type Description
open_request ConnectRequest.OpenRequest The initiation message to open a channel to a device.
resume_request ConnectRequest.ResumeRequest Attempt to resume stream of data
ack Ack ACK message
data Data Any data sent to the device through the endpoint.
close Close
error Error
ping Ping

ConnectRequest.OpenRequest Message

Name Type Description
project string (name of Project)
region_id string
name string
provider_name string name to connect.
service string Device service
arg bytes Initial argument (optional)

ConnectRequest.ResumeRequest Message

Name Type Description
project string (name of Project)
region_id string
name string
provider_name string name to connect.
session_id uint64
channel_id uint64
last_message_id uint64

ConnectResponse Message

Response message for method [Connect][ntt.proxies.v1alpha2.Connect]

Name Type Description
open_response ConnectResponse.OpenResponse Notification from the agent (endpoint) to the channel has been opened.
resume_response ConnectResponse.ResumeResponse
channel_open_error ConnectResponse.ChannelOpenError
ack Ack ACK message
data Data Any data from the device (endpoint) to the client.
close Close
error Error
pong Pong

ConnectResponse.OpenResponse Message

Name Type Description
session_id uint64
channel_id uint64

ConnectResponse.ResumeResponse Message

Name Type Description
session_id uint64
channel_id uint64
last_message_id uint64

ConnectResponse.ChannelOpenError Message

Name Type Description
channel_id uint64 ID of the channel failed to open.
message string Error message.

ListenRequest Message

Request message for method [Listen][ntt.proxies.v1alpha2.Listen]

Name Type Description
open_request ListenRequest.OpenRequest This is a hello message from the agent with its name.
resume_request ListenRequest.ResumeRequest
channel_open_error ListenRequest.ChannelOpenError When the agent failed to open a requested channel, this message will be sent from the agent to the endpoint.
ping Ping

ListenRequest.OpenRequest Message

Name Type Description
project string (name of Project)
region_id string
name string The self-declared device name, used for authentication/authorization.

ListenRequest.ResumeRequest Message

Name Type Description
project string (name of Project)
region_id string
name string The self-declared device name, used for authentication/authorization.
session_id uint64

ListenRequest.ChannelOpenError Message

Name Type Description
channel_id uint64 ID of the channel failed to open.
message string Error message.

ListenResponse Message

Response message for method [Listen][ntt.proxies.v1alpha2.Listen]

Name Type Description
listening ListenResponse.Listening
open_channel_response ListenResponse.OpenChannelResponse Notifies a new channel has been requested by a client.
resume_channel_response ListenResponse.ResumeChannelResponse Notifies a channel was asked to be resumed by a client
pong Pong

ListenResponse.Listening Message

Name Type Description
session_id uint64

ListenResponse.OpenChannelResponse Message

Name Type Description
channel_id uint64 Channel ID
service string Device service;
arg bytes Initial argument (optional)

ListenResponse.ResumeChannelResponse Message

Name Type Description
channel_id uint64 Channel ID
service string Device service;
arg bytes Initial argument (optional)
last_message_id uint64

AcceptRequest Message

Request message for method [Accept][ntt.proxies.v1alpha2.Accept]

Name Type Description
open_request AcceptRequest.OpenRequest Registers a new socket on the endpoint.
resume_request AcceptRequest.ResumeRequest
data Data Data from the agent to the endpoint (client).
ack Ack ACK message
close Close
error Error
ping Ping

AcceptRequest.OpenRequest Message

Name Type Description
project string (name of Project)
region_id string
name string Name, to be authenticated/authorized.
session_id uint64
channel_id uint64 Channel ID, requested by the endpoint in the ChannelRequested message.

AcceptRequest.ResumeRequest Message

Name Type Description
project string (name of Project)
region_id string
name string Name, to be authenticated/authorized.
session_id uint64
channel_id uint64 Channel ID, requested by the endpoint in the ChannelRequested message.
last_message_id uint64

AcceptResponse Message

Response message for method [Accept][ntt.proxies.v1alpha2.Accept]

Name Type Description
data Data Data from the endpoint (client) to the agent.
ack Ack ACK message
close Close
error Error
pong Pong

GetProjectRequest Message

A request message of the GetProject method.

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

BatchGetProjectsRequest Message

A request message of the BatchGetProjects method.

Name Type Description
names repeated string (name of Project) Names of Projects
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

BatchGetProjectsResponse Message

A response message of the BatchGetProjects method.

Name Type Description
projects repeated Project found Projects
missing repeated string (name of Project) list of not found Projects

ListProjectsRequest Message

A request message of the ListProjects method.

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

ListProjectsResponse Message

A response message of the ListProjects method.

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

WatchProjectRequest Message

A request message of the WatchProject method.

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

WatchProjectResponse Message

A response message of the WatchProject method.

Name Type Description
change ProjectChange

WatchProjectsRequest Message

A request message of the WatchProjects 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 Projects than requested. If unspecified, server will pick an appropriate default. Can be populated only for stateful watch type.
page_token string (cursor of Project) A token identifying a page of results the server should return. Can be populated only for stateful watch type.
order_by string (orderBy of Project) 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 Project) 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 Project 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 Project 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.

WatchProjectsResponse Message

A response message of the WatchProjects method.

Name Type Description
project_changes repeated ProjectChange Changes of Projects
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 Projects 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 WatchProjectsResponse.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 (Projects 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.

WatchProjectsResponse.PageTokenChange Message

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

CreateProjectRequest Message

A request message of the CreateProject method.

Name Type Description
project Project Project resource body
response_mask CreateProjectRequest.ResponseMask Optional masking applied to response object to reduce message response size.

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

UpdateProjectRequest Message

A request message of the UpdateProject method.

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

UpdateProjectRequest.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 Project 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.

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

DeleteProjectRequest Message

A request message of the DeleteProject method.

Name Type Description
name string (name of Project) Name of ntt.proxies.v1alpha2.Project

Proxies Service Shared Methods and Messages

Proxies Service Shared Messages

Here is the list of Proxies service shared messages:

Ack Message

Name Type Description
id uint64

Close Message

Name Type Description
id uint64

Data Message

Name Type Description
id uint64
bytes bytes
ack_required bool

Error Message

Name Type Description
id uint64
message string

Ping Message

Name Type Description
none none none

Pong Message

Name Type Description
none none none

ProjectChange Message

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

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

ProjectChange.Added Message

Project has been added to query view

Name Type Description
project Project
view_index int32 Integer describing index of added Project in resulting query view.

ProjectChange.Current Message

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

Name Type Description
project Project

ProjectChange.Modified Message

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

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

ProjectChange.Removed Message

Removed is returned when Project is deleted or leaves Query view

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