Correcting a bunch of incorrect documentation for the different API services and resources. (#494)

This commit is contained in:
Todd Knight authored and GitHub committed 2020-09-29 13:17:59 -07:00
1 parent 1c2dd7d0fc
commit 0eb35f49d5
61 files changed
+2030 -2366

No files matched your search

@@ -13,37 +13,37 @@ import "controller/api/resources/accounts/v1/account.proto";
service AccountService {
// GetAccount returns a stored Account if present. The provided request must
// include the scope for the group being retrieved. If any of those ids are
// missing, malformed or reference a non existing resource an error is
// returned.
// include the id for the Account be retrieved. If missing, malformed or
// referencing a non existing Account an error is returned.
rpc GetAccount(GetAccountRequest) returns (GetAccountResponse) {
option (google.api.http) = {
get: "/v1/accounts/{id}"
response_body: "item"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Gets a single Account"
summary: "Gets a single Account."
};
}
// ListAccounts returns a list of stored accounts which exist inside the
// auth method referenced inside the request. The request must include the
// auth method for the account being retrieved. If the auth method is missing,
// malformed, or references a non-existing auth method, an error is returned.
// ListAccounts returns a list of stored Accounts which exist inside the
// provided Auth Method. The request must include the Auth Method id which
// contains the Accounts being listed. If missing or malformed an error
// is returned.
rpc ListAccounts(ListAccountsRequest) returns (ListAccountsResponse) {
option (google.api.http) = {
get: "/v1/accounts"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Lists all accounts in a specific auth method."
summary: "Lists all Accounts in a specific Auth Method."
};
}
// CreateAccount creates and stores an account in boundary. The provided
// request must include the auth method id in which the account will be created.
// If the auth method id is missing, malformed or references a non existing
// auth method, an error is returned. If a name is provided that is in
// use in another account in the same auth method, an error is returned.
// CreateAccount creates and stores an Account in boundary. The provided
// request must include the Auth Method ID in which the Account will be
// created. If the Auth Method ID is missing, malformed, or references a non
// existing resource an error is returned. If a name or login_name is
// provided that is in use in another Account in the same Auth Method an
// error is returned.
rpc CreateAccount(CreateAccountRequest) returns (CreateAccountResponse) {
option (google.api.http) = {
post: "/v1/accounts"
@@ -51,18 +51,18 @@ service AccountService {
response_body: "item"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Creates a single account in the provided auth method."
summary: "Creates a single Account in the provided Auth Method."
};
}
// UpdateAccount updates an existing account in boundary. The provided account
// UpdateAccount updates an existing Account in boundary. The provided Account
// must not have any read only fields set. The update mask must be included in
// the request and contain at least 1 mutable field. To unset a field's value,
// include the field in the update mask and don't set it in the provided
// account. An error is returned if either the auth method or account ids are
// missing or reference a non-existing resource. An error is also returned if the
// request attempts to update the name to one that is already in use in this
// auth method.
// Account. An error is returned if the Account id is missing or references a
// non-existing resource. An error is also returned if the request attempts
// to update the name or login_name to one that is already in use in the
// containing Auth Method.
rpc UpdateAccount(UpdateAccountRequest) returns (UpdateAccountResponse) {
option (google.api.http) = {
patch: "/v1/accounts/{id}"
@@ -70,25 +70,22 @@ service AccountService {
response_body: "item"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Updates an account."
summary: "Updates an Account."
};
}
// DeleteAccount removes an account from Boundary. If the provided auth mehtod
// or account ids are malformed or not provided an error is returned. No error is
// returned if either ids reference resources that do not exist as the
// response itself specifies if the resource existed before the DeleteAccount
// request was received.
// DeleteAccount removes an Account from Boundary. If the provided Account Id
// is malformed or not provided an error is returned.
rpc DeleteAccount(DeleteAccountRequest) returns (DeleteAccountResponse) {
option (google.api.http) = {
delete: "/v1/accounts/{id}"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Deletes an account."
summary: "Deletes an Account."
};
}
// SetPassword sets the account's password to the one provided in the
// SetPassword sets the Account's password to the one provided in the
// request. This method is intended for administration purpose and as such
// does not require the old password.
rpc SetPassword(SetPasswordRequest) returns (SetPasswordResponse) {
@@ -98,11 +95,11 @@ service AccountService {
response_body: "item"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Sets the password for the provided account."
summary: "Sets the password for the provided Account."
};
}
// ChangePassword changes the account's password to the one provided in the
// ChangePassword changes the Account's password to the one provided in the
// request. This method is intended for end users and requires the existing
// password to be provided for authentication purposes.
rpc ChangePassword(ChangePasswordRequest) returns (ChangePasswordResponse) {
@@ -112,7 +109,7 @@ service AccountService {
response_body: "item"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Sets the password for the provided account."
summary: "Sets the password for the provided Account."
};
}
}
@@ -160,6 +157,8 @@ message DeleteAccountResponse {}
message SetPasswordRequest {
string id = 1;
// Version is used to ensure this resource has not changed.
// The mutation will fail if the version does not match the latest known good version.
uint32 version = 2;
string password = 3;
}
@@ -170,6 +169,8 @@ message SetPasswordResponse {
message ChangePasswordRequest {
string id = 1;
// Version is used to ensure this resource has not changed.
// The mutation will fail if the version does not match the latest known good version.
uint32 version = 2;
string current_password = 3 [json_name="current_password"];
string new_password = 4 [json_name="new_password"];
@@ -10,38 +10,36 @@ import "google/protobuf/field_mask.proto";
import "controller/api/resources/authmethods/v1/auth_method.proto";
service AuthMethodService {
// GetAuthMethod returns a stored AuthMethod if present. The provided request
// must include the org and auth method id for the auth method being retrieved. If
// any of those ids are missing, malformed or reference a non existing
// resource an error is returned.
// GetAuthMethod returns a stored Auth Method if present. The provided request
// must include the Auth Method id. If missing, malformed or referencing a
// non existing resource an error is returned.
rpc GetAuthMethod(GetAuthMethodRequest) returns (GetAuthMethodResponse) {
option (google.api.http) = {
get: "/v1/auth-methods/{id}"
response_body: "item"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Gets a single AuthMethod"
summary: "Gets a single Auth Method."
};
}
// ListAuthMethods returns a list of stored auth methods which exist inside the org
// referenced inside the request. The request must include the org id for
// the auth methods being retrieved. If the org id is missing, malformed, or
// reference a non existing organization, an error is returned.
// ListAuthMethods returns a list of stored Auth Methods which are in the
// provided scope. The request must include the scope id and if missing,
// malformed, or referencing a non existing scope, an error is returned.
rpc ListAuthMethods(ListAuthMethodsRequest) returns (ListAuthMethodsResponse) {
option (google.api.http) = {
get: "/v1/auth-methods"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Lists all AuthMethods"
summary: "Lists all Auth Methods."
};
}
// CreateAuthMethod creates and stores a user in boundary. The provided
// request must include the org id in which the user will be created.
// If the org id is missing, malformed or references a non existing
// org, an error is returned. If a name is provided that is in
// use in another user in the same org, an error is returned.
// CreateAuthMethod creates and stores an Auth Method in boundary. The
// provided request must include the scope in which the Auth Method will be
// created. If the scope id is missing, malformed or referencing a
// non existing resource an error is returned. If a name is provided that is
// in use in another Auth Method in the same scope, an error is returned.
rpc CreateAuthMethod(CreateAuthMethodRequest) returns (CreateAuthMethodResponse) {
option (google.api.http) = {
post: "/v1/auth-methods"
@@ -49,18 +47,18 @@ service AuthMethodService {
response_body: "item"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Creates a single AuthMethod"
summary: "Creates a single Auth Method."
};
}
// UpdateAuthMethod updates an existing user in boundary. The provided
// user must not have any read only fields set. The update mask must be
// UpdateAuthMethod updates an existing Auth Method in boundary. The provided
// Auth Method must not have any read only fields set. The update mask must be
// included in the request and contain at least 1 mutable field. To unset
// a field's value, include the field in the update mask and don't set it
// in the provided user. An error is returned if either the org
// or user ids are missing or reference a non existing resource. An error
// is also returned if the request attempts to update the name to one that is
// already in use in this org.
// in the provided user. An error is returned if the Auth Method id is missing
// or reference a non existing resource. An error is also returned if the
// request attempts to update the name to one that is already in use by
// another Auth Method in the parent scope.
rpc UpdateAuthMethod(UpdateAuthMethodRequest) returns (UpdateAuthMethodResponse) {
option (google.api.http) = {
patch: "/v1/auth-methods/{id}"
@@ -68,15 +66,12 @@ service AuthMethodService {
response_body: "item"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Updates an AuthMethod"
summary: "Updates an Auth Method."
};
}
// DeleteAuthMethod removes a user from Boundary. If the provided org or user ids
// are malformed or not provided an error is returned. No error is returned
// if either ids reference resources that do not exist as the response itself
// specifies if the resource existed before the DeleteAuthMethod request was
// received.
// DeleteAuthMethod removes an Auth Method from Boundary. If the Auth Method id
// is malformed or not provided an error is returned.
rpc DeleteAuthMethod(DeleteAuthMethodRequest) returns (DeleteAuthMethodResponse) {
option (google.api.http) = {
delete: "/v1/auth-methods/{id}"
@@ -9,6 +9,14 @@ import "google/api/annotations.proto";
import "google/protobuf/struct.proto";
import "controller/api/resources/authtokens/v1/authtoken.proto";
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
info: {
title: "Controller API"
}
schemes: HTTPS
schemes: HTTP
};
service AuthenticationService {
// Authenticate validates credentials provided and returns an Auth Token.
rpc Authenticate(AuthenticateRequest) returns (AuthenticateResponse) {
@@ -10,44 +10,40 @@ import "controller/api/resources/authtokens/v1/authtoken.proto";
service AuthTokenService {
// GetAuthToken returns a stored auth token if present. The provided request
// must include the org and auth token id for the auth token being retrieved. If
// any of those ids are missing, malformed or reference a non existing
// resource an error is returned.
// GetAuthToken returns a stored Auth Token if present. The provided request
// must include the Auth Token id and if it is missing, malformed or
// referencing a non existing resource an error is returned.
rpc GetAuthToken(GetAuthTokenRequest) returns (GetAuthTokenResponse) {
option (google.api.http) = {
get: "/v1/auth-tokens/{id}"
response_body: "item"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Gets a single AuthToken"
summary: "Gets a single Auth Token."
};
}
// ListAuthTokens returns a list of stored auth tokens which exist inside the org
// referenced inside the request. The request must include the org id for
// the auth token being retrieved. If the org id is missing, malformed, or
// reference a non existing organization, an error is returned.
// ListAuthTokens returns a list of stored Auth Tokens which exist inside
// the provided scope. The request must include the scope ids for
// the Auth Tokens being listed. If the scope id is missing, malformed, or
// referencing a non existing resource, an error is returned.
rpc ListAuthTokens(ListAuthTokensRequest) returns (ListAuthTokensResponse) {
option (google.api.http) = {
get: "/v1/auth-tokens"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Lists all AuthTokens"
summary: "Lists all Auth Tokens."
};
}
// DeleteAuthToken removes a auth token from Boundary. If the provided org or
// auth token ids are malformed or not provided an error is returned. No error is returned
// if either ids reference resources that do not exist as the response itself
// specifies if the resource existed before the DeleteAuthToken request was
// received.
// DeleteAuthToken removes a Auth Token from Boundary. If the provided
// Auth Token id is malformed or not provided an error is returned.
rpc DeleteAuthToken(DeleteAuthTokenRequest) returns (DeleteAuthTokenResponse) {
option (google.api.http) = {
delete: "/v1/auth-tokens/{id}"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Deletes an AuthTokens"
summary: "Deletes an Auth Token."
};
}
}
@@ -14,37 +14,35 @@ import "controller/api/resources/scopes/v1/scope.proto";
service GroupService {
// GetGroup returns a stored Group if present. The provided request must
// include the scope for the group being retrieved. If any of those ids are
// missing, malformed or reference a non existing resource an error is
// returned.
// include the Group id and if it is missing, malformed or referencing a
// non existing resource an error is returned.
rpc GetGroup(GetGroupRequest) returns (GetGroupResponse) {
option (google.api.http) = {
get: "/v1/groups/{id}"
response_body: "item"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Gets a single Group"
summary: "Gets a single Group."
};
}
// ListGroups returns a list of stored groups which exist inside the org
// referenced inside the request. The request must include the scope for
// the groups being retrieved. If the scope is missing, malformed, or
// ListGroups returns a list of stored Groups which exist inside the
// provided scope id. If that id is missing, malformed, or
// references a non-existing scope, an error is returned.
rpc ListGroups(ListGroupsRequest) returns (ListGroupsResponse) {
option (google.api.http) = {
get: "/v1/groups"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Lists all Groups"
summary: "Lists all Groups."
};
}
// CreateGroup creates and stores a group in boundary. The provided
// request must include the scope ID in which the group will be created.
// CreateGroup creates and stores a Group in boundary. The provided
// request must include the scope ID in which the Group will be created.
// If the scope ID is missing, malformed or references a non existing
// org, an error is returned. If a name is provided that is in
// use in another group in the same scope, an error is returned.
// resource, an error is returned. If a name is provided that is in
// use in another Group in the same scope, an error is returned.
rpc CreateGroup(CreateGroupRequest) returns (CreateGroupResponse) {
option (google.api.http) = {
post: "/v1/groups"
@@ -52,18 +50,18 @@ service GroupService {
response_body: "item"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Creates a single Group"
summary: "Creates a single Group."
};
}
// UpdateGroup updates an existing group in boundary. The provided group
// UpdateGroup updates an existing Group in boundary. The provided Group
// must not have any read only fields set. The update mask must be included in
// the request and contain at least 1 mutable field. To unset a field's value,
// include the field in the update mask and don't set it in the provided
// group. An error is returned if either the scope or group ids are missing or
// reference a non-existing resource. An error is also returned if the
// request attempts to update the name to one that is already in use in this
// scope.
// Group. An error is returned if the Group id is missing or reference a
// non-existing resource. An error is also returned if the request attempts
// to update the name to one that is already used by another Group in the
// same scope.
rpc UpdateGroup(UpdateGroupRequest) returns (UpdateGroupResponse) {
option (google.api.http) = {
patch: "/v1/groups/{id}"
@@ -71,28 +69,25 @@ service GroupService {
response_body: "item"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Updates a Group"
summary: "Updates a Group."
};
}
// DeleteGroup removes a group from Boundary. If the provided scope or group
// IDs are malformed or not provided an error is returned. No error is
// returned if either IDs reference resources that do not exist as the
// response itself specifies if the resource existed before the DeleteGroup
// request was received.
// DeleteGroup removes a Group from Boundary. If the provided Group
// ID is malformed or not provided an error is returned.
rpc DeleteGroup(DeleteGroupRequest) returns (DeleteGroupResponse) {
option (google.api.http) = {
delete: "/v1/groups/{id}"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Deletes a Group"
summary: "Deletes a Group."
};
}
// AddGroupMembers adds users as members to a group. The provided
// request must include the scope id and the group id which the users
// will be set to. If the any of the ids are missing, malformed or references a non
// existing resource, an error is returned.
// AddGroupMembers adds members to a Group. The provided request must include
// the scope id and the Group id which the members will be added to.
// An error is returned if any provided id is missing, malformed or
// references a non-existing resource.
rpc AddGroupMembers(AddGroupMembersRequest) returns (AddGroupMembersResponse) {
option (google.api.http) = {
post: "/v1/groups/{id}:add-members"
@@ -100,15 +95,15 @@ service GroupService {
response_body: "item"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Adds Users as members to a Group"
summary: "Adds members to a Group."
};
}
// SetGroupMembers sets the group's members. Any existing members on
// the group are deleted if they are not included in this request. The provided
// request must include the scope id and the group id which the users
// will be set to. If the any of the ids are missing, malformed or references a non
// existing resource, an error is returned.
// SetGroupMembers sets the Group's members. Any existing members on
// the Group are deleted if they are not included in this request. The provided
// request must include the Group id which the members will be set to.
// An error is returned if any provided id is missing, malformed or
// references a non-existing resource.
rpc SetGroupMembers(SetGroupMembersRequest) returns (SetGroupMembersResponse) {
option (google.api.http) = {
post: "/v1/groups/{id}:set-members"
@@ -120,10 +115,11 @@ service GroupService {
};
}
// RemoveGroupMembers removes members from the specified group.
// The provided request must include the scope id and the group id which the users
// will be set to. If the any of the ids are missing, malformed or references a non
// existing resource, an error is returned.
// RemoveGroupMembers removes members from the specified Group.
// The provided request must include the the Group id to which the members
// will be set.
// An error is returned if any provided id is missing, malformed or
// references a non-existing resource.
rpc RemoveGroupMembers(RemoveGroupMembersRequest) returns (RemoveGroupMembersResponse) {
option (google.api.http) = {
post: "/v1/groups/{id}:remove-members"
@@ -179,7 +175,8 @@ message DeleteGroupResponse {}
message AddGroupMembersRequest {
string id = 1;
// The version ensures the group hasn't changed since it was last retrieved and if it has the request will fail.
// Version is used to ensure this resource has not changed.
// The mutation will fail if the version does not match the latest known good version.
uint32 version = 2;
repeated string member_ids = 3 [json_name="member_ids"];
}
@@ -190,7 +187,8 @@ message AddGroupMembersResponse {
message SetGroupMembersRequest {
string id = 1;
// The version ensures the group hasn't changed since it was last retrieved and if it has the request will fail.
// Version is used to ensure this resource has not changed.
// The mutation will fail if the version does not match the latest known good version.
uint32 version = 2;
repeated string member_ids = 3 [json_name="member_ids"];
}
@@ -201,7 +199,8 @@ message SetGroupMembersResponse {
message RemoveGroupMembersRequest {
string id = 1;
// The version ensures the group hasn't changed since it was last retrieved and if it has the request will fail.
// Version is used to ensure this resource has not changed.
// The mutation will fail if the version does not match the latest known good version.
uint32 version = 2;
repeated string member_ids = 3 [json_name="member_ids"];
}
@@ -10,43 +10,37 @@ import "google/protobuf/field_mask.proto";
import "controller/api/resources/hostcatalogs/v1/host_catalog.proto";
service HostCatalogService {
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_tag) = {
description: "The host catalog service allows you to get/mutate Host catalogs of every type."
};
// GetHostCatalog returns a stored Host Catalog if present. The provided
// request must include the scope and catalog IDs for the host catalog being
// retrieved. If any of those IDs are missing, malformed, or reference a
// non-existing resource an error is returned.
// request must include the Catalog IDs for the Host Catalog being retrieved.
// If missing, malformed, or referencing a non-existing resource an error is
// returned.
rpc GetHostCatalog(GetHostCatalogRequest) returns (GetHostCatalogResponse) {
// Gets the host as specified in the url.
option (google.api.http) = {
get: "/v1/host-catalogs/{id}"
response_body: "item"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Gets a single HostCatalog"
description: "Gets a single Host Catalog with the provided identifier."
summary: "Gets a single Host Catalog."
};
}
// ListHostCatalogs returns a list of stored HostCatalogs which exist inside
// the project referenced in the request. The request must include the scope
// ID for the HostCatalogs being retrieved. If any of those ids are missing,
// malformed, or reference a non-existing parent resource an error is
// returned.
// ListHostCatalogs returns a list of stored Host Catalogs which exist inside
// the scope referenced in the request. The request must include the scope
// ID and if it is missing, malformed, or references a non-existing resource
// an error is returned.
rpc ListHostCatalogs(ListHostCatalogsRequest) returns (ListHostCatalogsResponse) {
option (google.api.http) = {
get: "/v1/host-catalogs"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Gets a list of HostCatalogs"
summary: "Gets a list of Host Catalogs."
};
}
// CreateHostCatalog creates and stores a HostCatalog in boundary. The
// provided request must include the scope ID in which the catalog will be
// created and the catalog type to be created. If any of these required fields
// CreateHostCatalog creates and stores a Host Catalog in boundary. The
// provided request must include the scope ID in which the Catalog will be
// created and the Catalog type to be created. If any of these required fields
// are missing, malformed, or reference a non-existing parent resource an
// error is returned.
rpc CreateHostCatalog(CreateHostCatalogRequest) returns (CreateHostCatalogResponse) {
@@ -56,16 +50,15 @@ service HostCatalogService {
response_body: "item"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Creates a HostCatalog"
description: "Creates a single host catalog under the specified scope"
summary: "Creates a Host Catalog"
};
}
// UpdateHostCatalog updates an existing HostCatalog in Boundary. The
// provided HostCatalog must not have any read only fields set. The update
// UpdateHostCatalog updates an existing Host Catalog in Boundary. The
// provided Host Catalog must not have any read only fields set. The update
// mask must be provided and include at least 1 mutable field. To unset a
// field's value include that field name in the update mask and don't set the
// field in the HostCatalog.
// field in the Host Catalog.
rpc UpdateHostCatalog(UpdateHostCatalogRequest) returns (UpdateHostCatalogResponse) {
option (google.api.http) = {
patch: "/v1/host-catalogs/{id}"
@@ -73,21 +66,19 @@ service HostCatalogService {
response_body: "item"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Updates a HostCatalog"
summary: "Updates a Host Catalog"
};
}
// DeleteHostCatalog removes a HostCatalog and all associated hosts and host
// sets from Boundary. If the provided scope or HostCatalog IDs are
// malformed or not provided DeleteHostCatalog returns an error. It is not an
// error to call DeleteHostCatalog for an scope or HostCatalog that does not
// exist as the response indicates if it existed or not.
// DeleteHostCatalog removes a Host Catalog and all associated Hosts and Host
// sets from Boundary. If the provided Host Catalog IDs is malformed or not
// provided DeleteHostCatalog returns an error.
rpc DeleteHostCatalog(DeleteHostCatalogRequest) returns (DeleteHostCatalogResponse) {
option (google.api.http) = {
delete: "/v1/host-catalogs/{id}"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Deletes a HostCatalog"
summary: "Deletes a Host Catalog"
};
}
}
@@ -11,38 +11,37 @@ import "controller/api/resources/hosts/v1/host.proto";
service HostService {
// GetHost returns a stored Host if present. The provided request
// must include the host catalog and host ID for the resource being
// retrieved. If any of those IDs are missing, malformed or reference a
// non existing resource an error is returned.
// must include the host ID for the resource being retrieved. If the ID is
// missing, malformed or referencing anon existing resource an error is
// returned.
rpc GetHost(GetHostRequest) returns (GetHostResponse) {
option (google.api.http) = {
get: "/v1/hosts/{id}"
response_body: "item"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Gets a single Host"
summary: "Gets a single Host."
};
}
// ListHosts returns a list of stored hosts which exist inside the scope
// referenced inside the request. The request must include the scope ID and
// the host catalog id for the hosts being retrieved. If the any of those
// are missing, malformed, or reference a non existing scope, an error is
// returned.
// ListHosts returns a list of stored hosts which exist inside the provided
// Host Catalog. The request must include the Host Catalog id containing the
// Hosts being listed. If the id is missing, malformed, or reference a
// non-existing resource, an error is returned.
rpc ListHosts(ListHostsRequest) returns (ListHostsResponse) {
option (google.api.http) = {
get: "/v1/hosts"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "List all Hosts for the specified catalog"
summary: "List all Hosts for the specified Catalog."
};
}
// CreateHost creates and stores a host in boundary. The provided
// request must include the scope and host catalog ids in which the host
// will be created. If the scope or catalog id is missing, malformed or references a
// non existing resource, an error is returned. If a name is provided that
// is in use by another host in the same host catalog, an error is returned.
// CreateHost creates and stores a Host in boundary. The provided
// request must include the Host Catalog id in which the Host
// will be created. If the Catalog id is missing, malformed or references a
// non-existing resource, an error is returned. If a name is provided that
// is in use by another Host in the same Host Catalog, an error is returned.
rpc CreateHost(CreateHostRequest) returns (CreateHostResponse) {
option (google.api.http) = {
post: "/v1/hosts"
@@ -50,18 +49,18 @@ service HostService {
response_body: "item"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Create a single Host"
summary: "Create a single Host."
};
}
// UpdateHost updates an existing host in boundary. The provided
// host must not have any read only fields set. The update mask must be
// UpdateHost updates an existing Host in boundary. The provided
// Host must not have any read only fields set. The update mask must be
// included in the request and contain at least 1 mutable field. To unset
// a field's value, include the field in the update mask and don't set it
// in the provided host. An error is returned if either the scope
// or host catalog or host ids are missing or reference a non existing
// resource. An error is also returned if the request attempts to update the
// name to one that is already in use in this host catalog.
// in the provided Host. An error is returned if the Host id is missing or
// reference a non-existing resource. An error is also returned if the
// request attempts to update the name to one that is already in use in
// the same Host Catalog.
rpc UpdateHost(UpdateHostRequest) returns (UpdateHostResponse) {
option (google.api.http) = {
patch: "/v1/hosts/{id}"
@@ -69,21 +68,18 @@ service HostService {
response_body: "item"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Update a Host"
summary: "Update a Host."
};
}
// DeleteHost removes a host from Boundary. If the provided scope,
// host catalog, or host ids are malformed or not provided an error is
// returned. No error is returned if any of the ids reference resources that
// do not exist since the response itself specifies if the resource existed
// before the DeleteHost request was received.
// DeleteHost removes a Host from Boundary. If the provided Host ID
// is malformed or not provided an error is returned.
rpc DeleteHost(DeleteHostRequest) returns (DeleteHostResponse) {
option (google.api.http) = {
delete: "/v1/hosts/{id}"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Delete a Host"
summary: "Delete a Host."
};
}
}
@@ -9,50 +9,37 @@ import "google/api/annotations.proto";
import "google/protobuf/field_mask.proto";
import "controller/api/resources/hostsets/v1/host_set.proto";
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
info: {
title: "Controller API"
version: "0.0.1"
description: "API for managing resources associated with Controllers."
}
schemes: HTTPS
schemes: HTTP
};
service HostSetService {
// GetHostSet returns a stored Host Set if present. The provided request
// must include the host catalog and host set ID for the resource being
// retrieved. If any of those IDs are missing, malformed or reference a
// non existing resource an error is returned.
// must include the Host Set ID for the resource being retrieved. If missing,
// malformed or reference a non existing resource an error is returned.
rpc GetHostSet(GetHostSetRequest) returns (GetHostSetResponse) {
option (google.api.http) = {
get: "/v1/host-sets/{id}"
response_body: "item"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Get a single HostSet"
summary: "Get a single Host Set."
};
}
// ListHostSets returns a list of stored host sets which exist inside the scope
// referenced inside the request. The request must include the scope ID and
// the host catalog id for the host sets being retrieved. If the any of those
// are missing, malformed, or reference a non existing scope, an error is
// returned.
// ListHostSets returns a list of stored Host Sets which exist inside the
// Host Catalog provided. The request must include a properly formatted
// Host Catalog id or an error is returned.
rpc ListHostSets(ListHostSetsRequest) returns (ListHostSetsResponse) {
option (google.api.http) = {
get: "/v1/host-sets"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "List all HostSets under the specific catalog"
summary: "List all Host Sets under the specific Catalog."
};
}
// CreateHostSet creates and stores a host set in boundary. The provided
// request must include the scope and host catalog ids in which the host set
// will be created. If the scope or catalog id are missing, malformed or
// CreateHostSet creates and stores a Host Set in boundary. The provided
// request must include the Host Catalog id in which the Host Set
// will be created. If the Host Catalog id is missing, malformed or
// references a non existing resource, an error is returned. If a name is
// provided that is in use by another host set in the same host catalog, an
// provided that is in use by another Host Set in the same Host Catalog, an
// error is returned.
rpc CreateHostSet(CreateHostSetRequest) returns (CreateHostSetResponse) {
option (google.api.http) = {
@@ -61,18 +48,18 @@ service HostSetService {
response_body: "item"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Create a HostSet"
summary: "Create a Host Set."
};
}
// UpdateHostSet updates an existing host set in boundary. The provided
// host set must not have any read only fields set. The update mask must be
// UpdateHostSet updates an existing Host Set in boundary. The provided
// Host Set must not have any read only fields set. The update mask must be
// included in the request and contain at least 1 mutable field. To unset
// a field's value, include the field in the update mask and don't set it
// in the provided host set. An error is returned if either the scope
// or host catalog or host set ids are missing or reference a non existing
// resource. An error is also returned if the request attempts to update the
// name to one that is already in use in this host catalog.
// in the provided Host Set. An error is returned if the Host Set id is
// missing or reference a non-existing resource.
// An error is also returned if the request attempts to update the name to
// one that is already in use in this Host Catalog.
rpc UpdateHostSet(UpdateHostSetRequest) returns (UpdateHostSetResponse) {
option (google.api.http) = {
patch: "/v1/host-sets/{id}"
@@ -80,30 +67,28 @@ service HostSetService {
response_body: "item"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Update a HostSet"
summary: "Update a Host Set."
};
}
// DeleteHostSet removes a host set from Boundary. If the provided scope,
// host catalog, or host set ids are malformed or not provided an error is
// returned. No error is returned if any of the ids reference resources that
// do not exist since the response itself specifies if the resource existed
// before the DeleteHostSet request was received.
// DeleteHostSet removes a Host Set from Boundary. If the provided
// Host Set id is malformed or not provided an error is returned.
rpc DeleteHostSet(DeleteHostSetRequest) returns (DeleteHostSetResponse) {
option (google.api.http) = {
delete: "/v1/host-sets/{id}"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Delete a HostSet"
summary: "Delete a Host Set."
};
}
// AddHostSetHosts adds a host to a host set. The provided request must
// include the scope ID and the host set ID to which the host will be added.
// All hosts added to the provided host set must be a child of the same
// catalog that this host set is a child of. If the scope or host set IDs are
// AddHostSetHosts adds a Host to a Host Set. The provided request must
// include the Host Set ID to which the Host will be added.
// All hosts added to the provided Host Set must be a child of the same
// Catalog that this Host Set is a child of. If the Host Set IDs is
// missing, malformed, or reference non-existing resources, an error is
// returned.
// returned. It is an error to add a Host which already exists in the
// Host Set.
rpc AddHostSetHosts(AddHostSetHostsRequest) returns (AddHostSetHostsResponse) {
option (google.api.http) = {
post: "/v1/host-sets/{id}:add-hosts"
@@ -115,13 +100,12 @@ service HostSetService {
};
}
// SetHostSetHosts sets the host set's hosts. Any existing hosts on the
// host set are deleted if they are not included in this request. The
// provided request must include the scope, host catalog, and the host set
// ID on which the hosts will be set. All hosts in the request must be a
// child of the same catalog that the provided host set is. If any of those
// IDs are missing, malformed, or references a non-existing resource, an
// error is returned.
// SetHostSetHosts sets the Host Set's hosts. Any existing hosts on the
// Host Set are deleted if they are not included in this request. The
// provided request must include the Host Set ID on which the hosts will be
// set. All Hosts in the request must be a child of the same Catalog that
// the provided Host Set is. An error is returned if any of the provided
// ids are malformed or references a non-existing resource.
rpc SetHostSetHosts(SetHostSetHostsRequest) returns (SetHostSetHostsResponse) {
option (google.api.http) = {
post: "/v1/host-sets/{id}:set-hosts"
@@ -133,11 +117,11 @@ service HostSetService {
};
}
// RemoveHostSetHosts removes the hosts from the specified host set. The
// provided request must include the scope, host catalog, and the host set
// IDs for the host set from which the host will be removed. If any of the
// IDs are missing, malformed, or references a non-existing scope or catalog,
// an error is returned.
// RemoveHostSetHosts removes the Hosts from the specified Host Set. The
// provided request must include the Host Set ID which the Host will be
// removed. An error is a returned if any of the provided IDs are malformed,
// or references a non-existing scope or catalog, or if a Host id is included
// which is not in the provided Host Set.
rpc RemoveHostSetHosts(RemoveHostSetHostsRequest) returns (RemoveHostSetHostsResponse) {
option (google.api.http) = {
post: "/v1/host-sets/{id}:remove-hosts"
@@ -193,6 +177,8 @@ message DeleteHostSetResponse {}
message AddHostSetHostsRequest {
string id = 1;
// Version is used to ensure this resource has not changed.
// The mutation will fail if the version does not match the latest known good version.
uint32 version = 2;
// A list of Host IDs which will be added to this Host Set. Each Host referenced here must be a child of the same Host Catalog of which this Host Set is a child.
@@ -205,6 +191,8 @@ message AddHostSetHostsResponse {
message SetHostSetHostsRequest {
string id = 1;
// Version is used to ensure this resource has not changed.
// The mutation will fail if the version does not match the latest known good version.
uint32 version = 2;
// A list of Host IDs which will be set on this Host Set. Each Host referenced here must be a child of the same Host Catalog of which this Host Set is a child.
@@ -217,6 +205,8 @@ message SetHostSetHostsResponse {
message RemoveHostSetHostsRequest {
string id = 1;
// Version is used to ensure this resource has not changed.
// The mutation will fail if the version does not match the latest known good version.
uint32 version = 2;
// A list of Host IDs which will be removed from this Host Set.
@@ -13,7 +13,7 @@ import "controller/api/resources/roles/v1/role.proto";
service RoleService {
// GetRole returns a stored Role if present. The provided request must include
// the role ID for the role being retrieved. If the ID is missing, malformed
// the Role ID for the Role being retrieved. If the ID is missing, malformed
// or reference a non-existing resource an error is returned.
rpc GetRole(GetRoleRequest) returns (GetRoleResponse) {
option (google.api.http) = {
@@ -21,27 +21,27 @@ service RoleService {
response_body: "item"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Gets a single Role"
summary: "Gets a single Role."
};
}
// ListRoles returns a list of stored roles which exist inside the scope
// ListRoles returns a list of stored Roles which exist inside the scope
// referenced inside the request. The request must include the scope ID for
// the roles being retrieved. If the scope ID is missing, malformed, or
// the Roles being retrieved. If the scope ID is missing, malformed, or
// reference a non-existing scope, an error is returned.
rpc ListRoles(ListRolesRequest) returns (ListRolesResponse) {
option (google.api.http) = {
get: "/v1/roles"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Lists all Roles"
summary: "Lists all Roles."
};
}
// CreateRole creates and stores a role. The provided request must include the
// scope ID in which the role will be created. If the scope ID is missing,
// CreateRole creates and stores a Role. The provided request must include the
// scope ID in which the Role will be created. If the scope ID is missing,
// malformed, or references a non-existing scope, an error is returned. If a
// name is provided that is in use in another role in the same scope, an error
// name is provided that is in use in another Role in the same scope, an error
// is returned.
rpc CreateRole(CreateRoleRequest) returns (CreateRoleResponse) {
option (google.api.http) = {
@@ -50,18 +50,18 @@ service RoleService {
response_body: "item"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Creates a single Role"
summary: "Creates a single Role."
};
}
// UpdateRole updates an existing role in boundary. The provided
// role must not have any read-only fields set. The update mask must be
// UpdateRole updates an existing Role in boundary. The provided
// Role must not have any read-only fields set. The update mask must be
// included in the request and contain at least 1 mutable field. To unset
// a field's value, include the field in the update mask and don't set it
// in the provided role. An error is returned if either the scope
// or role IDs are missing or reference a non-existing resource. An error
// in the provided Role. An error is returned if either the scope
// or Role IDs are missing or reference a non-existing resource. An error
// is also returned if the request attempts to update the name to one that is
// already in use in this org.
// already in use in the same scope.
rpc UpdateRole(UpdateRoleRequest) returns (UpdateRoleResponse) {
option (google.api.http) = {
patch: "/v1/roles/{id}"
@@ -69,28 +69,26 @@ service RoleService {
response_body: "item"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Updates a Role"
summary: "Updates a Role."
};
}
// DeleteRole removes a role from Boundary. If the provided scope or role IDs
// are malformed, or not provided an error is returned. No error is returned
// if either IDs reference resources that do not exist as the response itself
// specifies if the resource existed before the DeleteRole request was
// received.
// DeleteRole removes a Role from Boundary. If the provided scope or Role IDs
// are malformed, or not provided an error is returned.
rpc DeleteRole(DeleteRoleRequest) returns (DeleteRoleResponse) {
option (google.api.http) = {
delete: "/v1/roles/{id}"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Deletes a Role"
summary: "Deletes a Role."
};
}
// AddRolePrincipals adds users and/or groups to a role. The provided request
// must include the scope ID and the role ID to which the users and/or groups
// will be added. If the scope or role IDs are missing, malformed, or reference
// non-existing resources, an error is returned.
// AddRolePrincipals adds users and/or groups to a Role. The provided request
// must include the Role ID to which the users and/or groups will be added.
// If the Role ID is missing, malformed, or reference non-existing resources,
// an error is returned. An error is also returned if the request attempts to
// add a principal that is already part of the role.
rpc AddRolePrincipals(AddRolePrincipalsRequest) returns (AddRolePrincipalsResponse) {
option (google.api.http) = {
post: "/v1/roles/{id}:add-principals"
@@ -98,15 +96,15 @@ service RoleService {
response_body: "item"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Adds Users and/or Groups to a Role"
summary: "Adds Users and/or Groups to a Role."
};
}
// SetRolePrincipals sets the role's users and/or groups. Any existing
// principals on the role are deleted if they are not included in this
// request. The provided request must include the scope ID and the role ID on
// which the users and/or groups will be set. If the scope or role IDs are
// missing, malformed, or reference non-existing resources, an error is
// SetRolePrincipals sets the Role's users and/or groups. Any existing
// principals on the Role are deleted if they are not included in this
// request. The provided request must include the Role ID on
// which the users and/or groups will be set. If the Role ID is
// missing, malformed, or referencing a non-existing resource, an error is
// returned.
rpc SetRolePrincipals(SetRolePrincipalsRequest) returns (SetRolePrincipalsResponse) {
option (google.api.http) = {
@@ -120,10 +118,11 @@ service RoleService {
}
// RemoveRolePrincipals removes the users and/or groups from the specified
// role. The provided request must include the scope ID and the role ID from
// which the users and/or groups will be removed. If either ID is missing,
// malformed, or reference a non-existing resource, an error is returned. It
// is not an error to have duplicate user/group ids.
// Role. The provided request must include the Role ID from
// which the users and/or groups will be removed. If that ID is missing,
// malformed, or reference a non-existing resource, an error is returned.
// An error is returned if a remove is called for a principal that is not
// part of the role.
rpc RemoveRolePrincipals(RemoveRolePrincipalsRequest) returns (RemoveRolePrincipalsResponse) {
option (google.api.http) = {
post: "/v1/roles/{id}:remove-principals"
@@ -135,10 +134,9 @@ service RoleService {
};
}
// AddRoleGrants adds grants to a role. The provided request must include
// the org id and the role id which the grants will be added to. If the
// org id is missing, malformed, or references a non-existing org,
// an error is returned. It is not an error to have duplicate grants.
// AddRoleGrants adds grants to a Role. The provided request must include
// the Role id which the grants will be added to. An error is returned
// if the provided id is malformed or references a non-existing resource.
rpc AddRoleGrants(AddRoleGrantsRequest) returns (AddRoleGrantsResponse) {
option (google.api.http) = {
post: "/v1/roles/{id}:add-grants"
@@ -146,15 +144,14 @@ service RoleService {
response_body: "item"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Adds grants to a role"
summary: "Adds grants to a Role"
};
}
// SetRoleGrants sets the role's grants. Any existing grants on the role are
// SetRoleGrants sets the Role's grants. Any existing grants on the Role are
// deleted if they are not included in this request. The provided request must
// include the scope ID and the role ID on which the grants will be set. If either
// ID is missing, malformed, or references a non-existing resource, an
// error is returned. It is not an error to have duplicate grants.
// include the Role ID on which the grants will be set. If missing, malformed,
// or referencing a non-existing resource, an error is returned.
rpc SetRoleGrants(SetRoleGrantsRequest) returns (SetRoleGrantsResponse) {
option (google.api.http) = {
post: "/v1/roles/{id}:set-grants"
@@ -162,15 +159,14 @@ service RoleService {
response_body: "item"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Set grants for a role, removing any grants that are not specified in the request."
summary: "Set grants for a Role, removing any grants that are not specified in the request."
};
}
// RemoveRoleGrants removes the grants from the specified role.
// The provided request must include the scope and the role IDs from which the
// grants will be removed. If either ID is missing, malformed, or
// references a non-existing scope, an error is returned. It is not an error to
// have duplicate grants.
// RemoveRoleGrants removes the grants from the specified Role.
// The provided request must include the Role IDs from which the
// grants will be removed. If missing, malformed, or references a non-existing
// resource, an error is returned.
rpc RemoveRoleGrants(RemoveRoleGrantsRequest) returns (RemoveRoleGrantsResponse) {
option (google.api.http) = {
post: "/v1/roles/{id}:remove-grants"
@@ -178,7 +174,7 @@ service RoleService {
response_body: "item"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Removes grants from a role."
summary: "Removes grants from a Role."
};
}
@@ -227,7 +223,8 @@ message DeleteRoleResponse {}
message AddRolePrincipalsRequest {
string id = 1;
// The version ensures the role hasn't changed since it was last retrieved and if it has the request will fail.
// Version is used to ensure this resource has not changed.
// The mutation will fail if the version does not match the latest known good version.
uint32 version = 2;
repeated string principal_ids = 3 [json_name="principal_ids"];
}
@@ -238,7 +235,8 @@ message AddRolePrincipalsResponse {
message SetRolePrincipalsRequest {
string id = 1;
// The version ensures the role hasn't changed since it was last retrieved and if it has the request will fail.
// Version is used to ensure this resource has not changed.
// The mutation will fail if the version does not match the latest known good version.
uint32 version = 2;
repeated string principal_ids = 3 [json_name="principal_ids"];
}
@@ -249,7 +247,8 @@ message SetRolePrincipalsResponse {
message RemoveRolePrincipalsRequest {
string id = 1;
// The version ensures the role hasn't changed since it was last retrieved and if it has the request will fail.
// Version is used to ensure this resource has not changed.
// The mutation will fail if the version does not match the latest known good version.
uint32 version = 2;
repeated string principal_ids = 3 [json_name="principal_ids"];
}
@@ -260,7 +259,8 @@ message RemoveRolePrincipalsResponse {
message AddRoleGrantsRequest {
string id = 1;
// The version ensures the role hasn't changed since it was last retrieved and if it has the request will fail.
// Version is used to ensure this resource has not changed.
// The mutation will fail if the version does not match the latest known good version.
uint32 version = 2;
repeated string grant_strings = 3 [json_name="grant_strings"];
}
@@ -271,7 +271,8 @@ message AddRoleGrantsResponse {
message SetRoleGrantsRequest {
string id = 1;
// The version ensures the role hasn't changed since it was last retrieved and if it has the request will fail.
// Version is used to ensure this resource has not changed.
// The mutation will fail if the version does not match the latest known good version.
uint32 version = 2;
repeated string grant_strings = 3 [json_name="grant_strings"];
}
@@ -282,7 +283,8 @@ message SetRoleGrantsResponse {
message RemoveRoleGrantsRequest {
string id = 1;
// The version ensures the role hasn't changed since it was last retrieved and if it has the request will fail.
// Version is used to ensure this resource has not changed.
// The mutation will fail if the version does not match the latest known good version.
uint32 version = 2;
repeated string grant_strings = 3 [json_name="grant_strings"];
}
@@ -13,7 +13,7 @@ service ScopeService {
// GetScope returns a stored Scope if present. The provided request
// must include the scope ID for the scope being retrieved. If
// any of those IDs are missing, malformed or reference a non existing
// that ID is missing, malformed or references a non existing
// resource an error is returned.
rpc GetScope(GetScopeRequest) returns (GetScopeResponse) {
option (google.api.http) = {
@@ -21,25 +21,25 @@ service ScopeService {
response_body: "item"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Gets a single Scope"
summary: "Gets a single Scope."
};
}
// ListScopes returns a list of stored scopes which exist inside the scope of
// the token making the request.
// ListScopes returns a list of stored Scopes which exist inside the provided
// parent Scope id.
rpc ListScopes(ListScopesRequest) returns (ListScopesResponse) {
option (google.api.http) = {
get: "/v1/scopes"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Lists all Scopes within the scope of the token making the request"
summary: "Lists all Scopes within the Scope provided in the request."
};
}
// CreateScope creates and stores a scope in boundary. The provided request
// must include the scope ID in which the scope will be created. If the scope
// CreateScope creates and stores a Scope in boundary. The provided request
// must include the Scope ID in which the new scope will be created. If the Scope
// ID is missing, malformed or references a non existing scope, an error is
// returned. If a name is provided that is in use in another scope in the same
// returned. If a name is provided that is in use in another Scope in the same
// parent scope, an error is returned.
rpc CreateScope(CreateScopeRequest) returns (CreateScopeResponse) {
option (google.api.http) = {
@@ -48,18 +48,18 @@ service ScopeService {
response_body: "item"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Creates a single Scope"
summary: "Creates a single Scope."
};
}
// UpdateScope updates an existing scope in boundary. The provided
// scope must not have any read only fields set. The update mask must be
// UpdateScope updates an existing Scope in boundary. The provided
// Scope must not have any read only fields set. The update mask must be
// included in the request and contain at least 1 mutable field. To unset
// a field's value, include the field in the update mask and don't set it
// in the provided scope. An error is returned if either the org
// or scope ids are missing or reference a non existing resource. An error
// in the provided scope. An error is returned if the Scope Id is
// missing or reference a non-existing resource. An error
// is also returned if the request attempts to update the name to one that is
// already in use in this org.
// already in use by another scope in the parent scope.
rpc UpdateScope(UpdateScopeRequest) returns (UpdateScopeResponse) {
option (google.api.http) = {
patch: "/v1/scopes/{id}"
@@ -67,21 +67,18 @@ service ScopeService {
response_body: "item"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Updates a Scope"
summary: "Updates a Scope."
};
}
// DeleteScope remotes a scope and all child resources from Boundary. If the
// provided scope IDs are malformed or not provided an error is returned. No
// error is returned if the ID references a resource that does not exist as
// the response itself specifies if the resource existed before the
// DeleteScope request was received.
// DeleteScope remotes a Scope and all child resources from Boundary. If the
// provided Scope IDs are malformed or not provided an error is returned.
rpc DeleteScope(DeleteScopeRequest) returns (DeleteScopeResponse) {
option (google.api.http) = {
delete: "/v1/scopes/{id}"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Deletes a Scope"
summary: "Deletes a Scope."
};
}
}
@@ -11,8 +11,8 @@ import "controller/api/resources/sessions/v1/session.proto";
service SessionService {
// GetSession returns a stored Session if present. The provided request
// must include the scope and session ID for the session being retrieved. If
// any of those IDs are missing, malformed or reference a non existing
// must include the Session ID for the Session being retrieved. If
// any that ID is missing, malformed or reference a non existing
// resource an error is returned.
rpc GetSession(GetSessionRequest) returns (GetSessionResponse) {
option (google.api.http) = {
@@ -20,25 +20,25 @@ service SessionService {
response_body: "item"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Gets a single Session"
summary: "Gets a single Session."
};
}
// ListSessions returns a list of stored sessions which exist inside the project
// ListSessions returns a list of stored Sessions which exist inside the scope
// referenced inside the request. The request must include the scope ID for
// the sessions being retrieved. If the scope ID is missing, malformed, or
// the Sessions being retrieved. If the scope ID is missing, malformed, or
// reference a non existing scope, an error is returned.
rpc ListSessions(ListSessionsRequest) returns (ListSessionsResponse) {
option (google.api.http) = {
get: "/v1/sessions"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Lists all Sessions"
summary: "Lists all Sessions."
};
}
// CancelSession cancels an existing session in boundary. An error
// is returned if the request attempts to cancel a session that does
// CancelSession cancels an existing Session in boundary. An error
// is returned if the request attempts to cancel a Session that does
// not exist.
rpc CancelSession(CancelSessionRequest) returns (CancelSessionResponse) {
option (google.api.http) = {
@@ -47,7 +47,7 @@ service SessionService {
response_body: "item"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Cancels a Session"
summary: "Cancels a Session."
};
}
}
@@ -12,8 +12,8 @@ import "controller/api/resources/targets/v1/target.proto";
service TargetService {
// GetTarget returns a stored Target if present. The provided request
// must include the scope and target ID for the target being retrieved. If
// any of those IDs are missing, malformed or reference a non existing
// must include the Target ID for the Target being retrieved. If
// that ID is missing, malformed or reference a non existing
// resource an error is returned.
rpc GetTarget(GetTargetRequest) returns (GetTargetResponse) {
option (google.api.http) = {
@@ -21,28 +21,28 @@ service TargetService {
response_body: "item"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Gets a single Target"
summary: "Gets a single Target."
};
}
// ListTargets returns a list of stored targets which exist inside the project
// ListTargets returns a list of stored Targets which exist inside the project
// referenced inside the request. The request must include the scope ID for
// the targets being retrieved. If the scope ID is missing, malformed, or
// the Targets being retrieved. If the scope ID is missing, malformed, or
// reference a non existing scope, an error is returned.
rpc ListTargets(ListTargetsRequest) returns (ListTargetsResponse) {
option (google.api.http) = {
get: "/v1/targets"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Lists all Targets"
summary: "Lists all Targets."
};
}
// CreateTarget creates and stores a target in boundary. The provided
// request must include the scope id in which the target will be created.
// CreateTarget creates and stores a Target in boundary. The provided
// request must include the scope id in which the Target will be created.
// If the scope id is missing, malformed or references a non existing
// scope, an error is returned. If a name is provided that is in
// use in another target in the same scope, an error is returned.
// use in another Target in the same scope, an error is returned.
rpc CreateTarget(CreateTargetRequest) returns (CreateTargetResponse) {
option (google.api.http) = {
post: "/v1/targets"
@@ -50,18 +50,18 @@ service TargetService {
response_body: "item"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Creates a single Target"
summary: "Creates a single Target."
};
}
// UpdateTarget updates an existing target in boundary. The provided
// target must not have any read only fields set. The update mask must be
// UpdateTarget updates an existing Target in boundary. The provided
// Target must not have any read only fields set. The update mask must be
// included in the request and contain at least 1 mutable field. To unset
// a field's value, include the field in the update mask and don't set it
// in the provided target. An error is returned if either the scope
// or target ids are missing or reference a non existing resource. An error
// is also returned if the request attempts to update the name to one that is
// already in use in this scope.
// in the provided Target. An error is returned if the Target ID is missing
// or reference a non-existing resource. An error is also returned if the
// request attempts to update the name to one that is already in use in
// this scope.
rpc UpdateTarget(UpdateTargetRequest) returns (UpdateTargetResponse) {
option (google.api.http) = {
patch: "/v1/targets/{id}"
@@ -69,25 +69,22 @@ service TargetService {
response_body: "item"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Updates a Target"
summary: "Updates a Target."
};
}
// DeleteTarget removes a target from Boundary. If the provided scope or target ids
// are malformed or not provided an error is returned. No error is returned
// if either ids reference resources that do not exist as the response itself
// specifies if the resource existed before the DeleteTarget request was
// received.
// DeleteTarget removes a Target from Boundary. If the provided Target ID
// is malformed or not provided an error is returned.
rpc DeleteTarget(DeleteTargetRequest) returns (DeleteTargetResponse) {
option (google.api.http) = {
delete: "/v1/targets/{id}"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Deletes a Target"
summary: "Deletes a Target."
};
}
// AuthorizeSession creates authorization information from a given target.
// AuthorizeSession creates authorization information from a given Target.
rpc AuthorizeSession(AuthorizeSessionRequest) returns (AuthorizeSessionResponse) {
option (google.api.http) = {
post: "/v1/targets/{id}:authorize"
@@ -95,16 +92,17 @@ service TargetService {
response_body: "item"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Authorizes a Session"
summary: "Authorizes a Session."
};
}
// AddTargetHostSets adds host sets to this target. The provided request must
// include the scope ID and the target ID to which the host sets will be added.
// All host sets added to the provided target must be a child of a catalog that
// is a child of the same scope as this target. If the scope or target IDs are
// AddTargetHostSets adds Host Sets to this Target. The provided request must
// include the Target ID to which the Host Sets will be added.
// All Host Sets added to the provided Target must be a child of a Catalog that
// is a child of the same scope as this Target. If the scope or Target IDs are
// missing, malformed, or reference non-existing resources, an error is
// returned.
// returned. An error is returned if a Host Set is attempted to be added
// to a target that is already present on the Target.
rpc AddTargetHostSets(AddTargetHostSetsRequest) returns (AddTargetHostSetsResponse) {
option (google.api.http) = {
post: "/v1/targets/{id}:add-host-sets"
@@ -116,11 +114,11 @@ service TargetService {
};
}
// SetTargetHostSets sets the target's host sets. Any existing host sets on the
// target are deleted if they are not included in this request. The
// provided request must include the scope, and the target ID on which the
// host sets will be set. All host sets in the request must be a child of
// a catalog that is in the same scope as the provided target. If any
// SetTargetHostSets sets the Target's Host Sets. Any existing Host Sets on the
// Target are deleted if they are not included in this request. The
// provided request must include the scope, and the Target ID on which the
// Host Sets will be set. All Host Sets in the request must be a child of
// a Catalog that is in the same scope as the provided Target. If any
// IDs are missing, malformed, or references a non-existing resource, an
// error is returned.
rpc SetTargetHostSets(SetTargetHostSetsRequest) returns (SetTargetHostSetsResponse) {
@@ -134,11 +132,12 @@ service TargetService {
};
}
// RemoveTargetHostSets removes the host sets from the specified target. The
// provided request must include the scope and the target IDs for the target
// from which the host sets will be removed. If any of the IDs are missing,
// malformed, or references a non-existing scope or catalog, an error is
// returned.
// RemoveTargetHostSets removes the Host Sets from the specified Target. The
// provided request must include the Target ID for the Target
// from which the Host Sets will be removed. If the ID is missing,
// malformed, or references a non-existing scope or Catalog, an error is
// returned. An error is returned if a Host Set is attempted to be
// removed from the Target when the Target does not have the Host Set.
rpc RemoveTargetHostSets(RemoveTargetHostSetsRequest) returns (RemoveTargetHostSetsResponse) {
option (google.api.http) = {
post: "/v1/targets/{id}:remove-host-sets"
@@ -195,9 +194,9 @@ message DeleteTargetResponse {}
message AddTargetHostSetsRequest {
string id = 1;
// Version is used to ensure this resource has not changed.
// The mutation will fail if the version does not match the latest known good version.
uint32 version = 2;
// A list of Host Set IDs which will be added to this target. Each Host Set referenced here must be a child of a Host Catalog in the same Scope as this Target.
repeated string host_set_ids = 3 [json_name="host_set_ids"];
}
@@ -207,9 +206,9 @@ message AddTargetHostSetsResponse {
message SetTargetHostSetsRequest {
string id = 1;
// Version is used to ensure this resource has not changed.
// The mutation will fail if the version does not match the latest known good version.
uint32 version = 2;
// A list of Host Set IDs which will be set on this target. Each Host Set referenced here must be a child of a Host Catalog in the same Scope as this Target.
repeated string host_set_ids = 3 [json_name="host_set_ids"];
}
@@ -219,9 +218,9 @@ message SetTargetHostSetsResponse {
message RemoveTargetHostSetsRequest {
string id = 1;
// Version is used to ensure this resource has not changed.
// The mutation will fail if the version does not match the latest known good version.
uint32 version = 2;
// A list of Host Set IDs which will be removed from this target.
repeated string host_set_ids = 3 [json_name="host_set_ids"];
}
@@ -12,8 +12,8 @@ import "controller/api/resources/users/v1/user.proto";
service UserService {
// GetUser returns a stored User if present. The provided request
// must include the scope and user ID for the user being retrieved. If
// any of those IDs are missing, malformed or reference a non existing
// must include the User ID for the User being retrieved. If
// that ID is missing, malformed or reference a non existing
// resource an error is returned.
rpc GetUser(GetUserRequest) returns (GetUserResponse) {
option (google.api.http) = {
@@ -21,28 +21,28 @@ service UserService {
response_body: "item"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Gets a single User"
summary: "Gets a single User."
};
}
// ListUsers returns a list of stored users which exist inside the org
// referenced inside the request. The request must include the scope ID for
// the users being retrieved. If the scope ID is missing, malformed, or
// reference a non existing scope, an error is returned.
// ListUsers returns a list of stored Users which exist inside the provided
// scope. The request must include the scope ID for the Users being listed.
// If the scope ID is missing, malformed, or reference a non existing scope,
// an error is returned.
rpc ListUsers(ListUsersRequest) returns (ListUsersResponse) {
option (google.api.http) = {
get: "/v1/users"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Lists all Users"
summary: "Lists all Users."
};
}
// CreateUser creates and stores a user in boundary. The provided
// request must include the scope id in which the user will be created.
// If the scope id is missing, malformed or references a non existing
// scope, an error is returned. If a name is provided that is in
// use in another user in the same scope, an error is returned.
// CreateUser creates and stores a User in boundary. The provided
// request must include the Scope id in which the User will be created.
// If the Scope id is missing, malformed or references a non existing
// resource, an error is returned. If a name is provided that is in
// use in another User in the same scope, an error is returned.
rpc CreateUser(CreateUserRequest) returns (CreateUserResponse) {
option (google.api.http) = {
post: "/v1/users"
@@ -50,18 +50,18 @@ service UserService {
response_body: "item"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Creates a single User"
summary: "Creates a single User."
};
}
// UpdateUser updates an existing user in boundary. The provided
// user must not have any read only fields set. The update mask must be
// UpdateUser updates an existing User in boundary. The provided
// User must not have any read only fields set. The update mask must be
// included in the request and contain at least 1 mutable field. To unset
// a field's value, include the field in the update mask and don't set it
// in the provided user. An error is returned if either the scope
// or user ids are missing or reference a non existing resource. An error
// is also returned if the request attempts to update the name to one that is
// already in use in this scope.
// in the provided User. An error is returned if either the User id is
// missing or reference a non existing resource. An error is also returned
// if the request attempts to update the name to one that is already in use
// in this Scope.
rpc UpdateUser(UpdateUserRequest) returns (UpdateUserResponse) {
option (google.api.http) = {
patch: "/v1/users/{id}"
@@ -69,29 +69,26 @@ service UserService {
response_body: "item"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Updates a User"
summary: "Updates a User."
};
}
// DeleteUser removes a user from Boundary. If the provided scope or user ids
// are malformed or not provided an error is returned. No error is returned
// if either ids reference resources that do not exist as the response itself
// specifies if the resource existed before the DeleteUser request was
// received.
// DeleteUser removes a User from Boundary. If the provided User ID
// is malformed or not provided an error is returned.
rpc DeleteUser(DeleteUserRequest) returns (DeleteUserResponse) {
option (google.api.http) = {
delete: "/v1/users/{id}"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
summary: "Deletes a User"
summary: "Deletes a User."
};
}
// AddUserAccounts adds users as members to a group. The provided request
// must include the user id which the account will be added to. If the any
// of the ids are missing, malformed or references a non
// existing resource, an error is returned. If any of the accounts are
// associated with another user an error is returned.
// AddUserAccounts adds Users as members to a group. The provided request
// must include the User id which the Account will be added to. If that id is
// missing, malformed or references a non existing resource, an error is
// returned. If any of the Accounts are associated with another User an
// error is returned.
rpc AddUserAccounts(AddUserAccountsRequest) returns (AddUserAccountsResponse) {
option (google.api.http) = {
post: "/v1/users/{id}:add-accounts"
@@ -103,12 +100,14 @@ service UserService {
};
}
// SetUserAccounts sets the group's members. Any existing accounts are
// removed if they are not included in this request. The provided request
// must include the user ids which the account will be set to. If the user
// id is missing, malformed or references a non existing resource, an error
// is returned. If any of the accounts are associated with another
// user an error is returned.
// SetUserAccounts sets the Accounts associated with this User.
// Any existing Accounts are removed if they are not included in this request.
// The provided request must include the User ID which the Accounts will be
// associated with. Any Accounts not included in this request but previously
// associated with this user will be disassociated.
// If the User ID is missing, malformed or references a non existing resource,
// an error is returned.
// If any of the Accounts are associated with another User an error is returned.
rpc SetUserAccounts(SetUserAccountsRequest) returns (SetUserAccountsResponse) {
option (google.api.http) = {
post: "/v1/users/{id}:set-accounts"
@@ -120,10 +119,10 @@ service UserService {
};
}
// RemoveUserAccounts removes accounts from the specified user.
// The provided request must include the user id which the accounts
// will be removed from. If the provided account id is not associated with the
// provided user, an error is returned.
// RemoveUserAccounts removes Accounts from the specified User.
// The provided request must include the User id which the Accounts
// will be removed from. If the provided Account ids is not associated with the
// provided User, an error is returned.
rpc RemoveUserAccounts(RemoveUserAccountsRequest) returns (RemoveUserAccountsResponse) {
option (google.api.http) = {
post: "/v1/users/{id}:remove-accounts"
@@ -179,7 +178,7 @@ message DeleteUserResponse {}
message AddUserAccountsRequest {
string id = 1;
// The version ensures the user hasn't changed since it was last retrieved and if it has the request will fail.
// The version ensures the User hasn't changed since it was last retrieved and if it has the request will fail.
uint32 version = 2;
repeated string account_ids = 3 [json_name="account_ids"];
}
@@ -190,7 +189,7 @@ message AddUserAccountsResponse {
message SetUserAccountsRequest {
string id = 1;
// The version ensures the user hasn't changed since it was last retrieved and if it has the request will fail.
// The version ensures the User hasn't changed since it was last retrieved and if it has the request will fail.
uint32 version = 2;
repeated string account_ids = 3 [json_name="account_ids"];
}
@@ -201,7 +200,7 @@ message SetUserAccountsResponse {
message RemoveUserAccountsRequest {
string id = 1;
// The version ensures the user hasn't changed since it was last retrieved and if it has the request will fail.
// The version ensures the User hasn't changed since it was last retrieved and if it has the request will fail.
uint32 version = 2;
repeated string account_ids = 3 [json_name="account_ids"];
}