package cs3.gateway.v1beta1
Get desktop application:
View/edit binary Protocol Buffers messages
service GatewayAPI
gateway_api.proto:75Gateway API The Gateway API is the only API exposed directly to end-clients. It is a facade API that all clients should connect to. Other APIS like the StorageProviderAPI are internal APIS. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. The following are global requirements that apply to all methods: Any method MUST return CODE_OK on a succesful operation. Any method MAY return NOT_IMPLEMENTED. Any method MAY return INTERNAL. Any method MAY return UNKNOWN. Any method MAY return UNAUTHENTICATED.
*****************************************************************/ ************************ AUTH ******** **************************/ *****************************************************************/
rpc AcceptInvite (, )
gateway_api.proto:433Completes an invitation acceptance.
rpc AddAppProvider (, )
gateway_api.proto:363Registers a new app provider to the registry.
rpc AddLabel (, )
gateway_api.proto:280Attach a label to a resource for a user.
rpc Authenticate (, )
gateway_api.proto:81Authenticates a user.
message
gateway_api.proto:494optional opaque = 1
OPTIONAL. Opaque information.
string type = 2
REQUIRED. The type of authentication to use.
string client_id = 3
OPTIONAL. The id of the client. For basic authentication with username and password both client_id and client_secret are expected to be filled. However, for example, for OIDC only a token is necessary.
string client_secret = 4
OPTIONAL. The secret of the client.
message
gateway_api.proto:512optional status = 1
REQUIRED. The response status.
optional opaque = 2
OPTIONAL. Opaque information.
string token = 3
REQUIRED. The access token.
optional user = 4
REQUIRED. The authenticated user.
rpc CancelTransfer (, )
gateway_api.proto:478Requests to cancel a transfer.
rpc CheckPermission (, )
gateway_api.proto:488CheckPermission checks if a user or group has a certain permission.
rpc CreateContainer (, )
gateway_api.proto:104Creates a new resource of type container. MUST return CODE_FAILED_PRECONDITION if the container cannot be created at the specified reference.
rpc CreateHome (, )
gateway_api.proto:204Creates the home directory for a user.
Creates a storage space.
rpc CreateSymlink (, )
gateway_api.proto:173Creates a symlink to another resource.
rpc CreateTransfer (, )
gateway_api.proto:474Requests creation of a transfer.
rpc Delete (, )
gateway_api.proto:115Deletes a resource. If a resource specifies the non-empty container (directory, ...), then the entire directory is deleted recursively. If a resource specifies a reference or symlink type, only the reference is removed (not the target). MUST return CODE_NOT_FOUND if the reference does not exist. MUST return CODE_TOO_EARLY if some are not finished job over resource is still in process.
Delete a previously accepted remote user, that is unfriend that user.
*****************************************************************/ ******************** OCM PROVIDER AUTHORIZER ********************/ *****************************************************************/
Deletes a storage space.
Finds users who accepted invite tokens by their attributes.
rpc FindGroups (, )
gateway_api.proto:409TODO(labkode): to define the filters that make more sense. Finds groups whose names match the specified filter.
*****************************************************************/ ************************ AUTH REGISTRY **************************/ *****************************************************************/
rpc FindUsers (, )
gateway_api.proto:384Finds users by any attribute of the user. TODO(labkode): to define the filters that make more sense.
rpc ForwardInvite (, )
gateway_api.proto:431Forwards a received invite to the sync'n'share system provider.
GenerateAppPassword creates a password with specified scope to be used by third-party applications.
Generates a new token for the user with a validity of 24 hours.
rpc GetAcceptedUser (, )
gateway_api.proto:435Retrieves details about a remote user who has accepted an invite to share.
rpc GetAppPassword (, )
gateway_api.proto:96GetAppPassword retrieves the password information by the combination of username and password.
*****************************************************************/ ************************ STORAGE PROVIDER ***********************/ *****************************************************************/
rpc GetAppProviders (, )
gateway_api.proto:361Returns the app providers that are capable of handling this resource info. MUST return CODE_NOT_FOUND if no providers are available.
Returns the default app provider which serves a specified mime type.
rpc GetGroup (, )
gateway_api.proto:400Gets the information about a group by the group id.
rpc GetGroupByClaim (, )
gateway_api.proto:402Gets the information about a group based on a specified claim.
rpc GetHome (, )
gateway_api.proto:421Returns the home path for the given authenticated user. When a user has access to multiple storage providers, one of them is the home.
*****************************************************************/ ************************ OCM INVITE MANAGER *********************/ *****************************************************************/
rpc GetInfoByDomain (, )
gateway_api.proto:449Get the information of the provider identified by a specific domain. MUST return CODE_NOT_FOUND if the sync'n'share system provider does not exist.
rpc GetKey (, )
gateway_api.proto:273Returns the value associated with the requested key.
rpc GetLock (, )
gateway_api.proto:190Gets the lock metadata of a storage resource. MUST return CODE_NOT_FOUND if the reference does not exist or is not locked. The caller MUST have read permissions on the resource.
rpc GetMembers (, )
gateway_api.proto:404Gets the members of a group.
rpc GetPath (, )
gateway_api.proto:119Returns the path reference for the provided resource id reference. MUST return CODE_NOT_FOUND if the reference does not exist
rpc GetQuota (, )
gateway_api.proto:124Returns the quota available under the provided reference. MUST return CODE_NOT_FOUND if the reference does not exist MUST return CODE_RESOURCE_EXHAUSTED on exceeded quota limits.
message
gateway_api.proto:548optional opaque = 1
OPTIONAL. Opaque information.
optional ref = 2
REQUIRED. The reference to which the action should be performed.
rpc GetTenant (, )
gateway_api.proto:391Gets the information about a tenant by the tenant id.
Gets the information about a tenant based on a specified claim.
Gets the groups of a user. *****************************************************************/ ************************ GROUP PROVIDER **************************/ *****************************************************************/
Requests a transfer status.
rpc GetUser (, )
gateway_api.proto:377Gets the information about a user by the user id.
rpc GetUserByClaim (, )
gateway_api.proto:379Gets the information about a user based on a specified claim.
rpc GetUserGroups (, )
gateway_api.proto:381Gets the groups of a user.
rpc HasMember (, )
gateway_api.proto:406Tells if the group has a certain member.
Initiates the download of a file using an out-of-band data transfer mechanism.
message
gateway_api.proto:557optional status = 1
REQUIRED. The response status.
optional opaque = 2
OPTIONAL. Opaque information.
repeated protocols = 3
REQUIRED. The protocols through which data can be downloaded.
Initiates the upload of a file using an out-of-band data transfer mechanism.
message
gateway_api.proto:569optional status = 1
REQUIRED. The response status.
optional opaque = 2
OPTIONAL. Opaque information.
repeated protocols = 3
REQUIRED. The protocols through which data can be uploaded.
InvalidateAppPassword invalidates a generated password.
Check if a given system provider is registered in the mesh or not. MUST return CODE_UNAUTHENTICATED if the system is not registered
Get the information of all the providers registered in the mesh.
*****************************************************************/ **************************** OCM INCOMING ***********************/ *****************************************************************/
rpc ListAppPasswords (, )
gateway_api.proto:92ListAppPasswords lists the application passwords created by a user.
Returns a list of the available app providers known by this registry.
Returns a list of the available auth providers known by this registry.
************************ STORAGE REGISTRY ** ********************/ *****************************************************************/
message
gateway_api.proto:581optional status = 1
REQUIRED. The response status.
optional opaque = 2
OPTIONAL. Opaque information.
repeated string types = 3
REQUIRED. The list of auth types. TODO(labkode): maybe add description?
rpc ListContainer (, )
gateway_api.proto:138Returns a list of resource information for the provided reference. MUST return CODE_NOT_FOUND if the reference does not exists.
rpc ListContainerStream (, stream )
gateway_api.proto:134Returns a stream of resource informations for the provided reference. MUST return CODE_NOT_FOUND if the reference does not exists.
Returns a list of the versions for a resource of type file at the provided reference. MUST return CODE_NOT_FOUND if the reference does not exist. MUST return CODE_OK and MUST return an empty list if no versions are available. TODO: What code if resource not of type file?
Lists the valid tokens generated by the user.
rpc ListLabels (, )
gateway_api.proto:284List the unique labels that a user has attached to resources
rpc ListRecycle (, )
gateway_api.proto:149Returns a list of recycle items for this storage provider. MUST return CODE_OK and MUST return an empty list if no recycle items are available.
rpc ListRecycleStream (, stream )
gateway_api.proto:146Returns a stream of recycle items for this storage provider.
List the resources which have a given label attached for a given user
Lists storage spaces.
Returns a list of the supported mime types along with the apps which they can opened with.
rpc ListTransfers (, )
gateway_api.proto:480Requests a list of transfers received by the authenticated principle.
rpc Move (, )
gateway_api.proto:155Moves a resource from one reference to another. MUST return CODE_NOT_FOUND if any of the references do not exist. MUST return CODE_FAILED_PRECONDITION if the source reference. MUST return CODE_TOO_EARLY if some are not finished job over resource is still in process. cannot be moved to the destination reference.
rpc OpenInApp (, )
gateway_api.proto:226Returns the App URL and all necessary info to open a resource in an online editor. MUST return CODE_NOT_FOUND if the resource does not exist.
*****************************************************************/ ************************ USER SHARE PROVIDER ********************/ *****************************************************************/
message
gateway_api.proto:663optional opaque = 1
OPTIONAL. Opaque information.
optional ref = 2
REQUIRED. The resource reference. If a path is given, it will be resolved via Stat() to a ResourceInfo in case a call to the WOPI server is to be issued (cf. the provider grpc message)
OpenInAppRequest.ViewMode view_mode = 3
string app = 4
OPTIONAL. A reference to the application to be used to open the resource, should the default inferred from the resource's mimetype be overridden by user's choice. If the targeted resource is a directory, this parameter is required and in its absence the implementation MUST return INVALID_ARGUMENT.
string lock_id = 5
OPTIONAL. A lock_id: should the reference be locked and the lock type be LOCK_TYPE_EXCL, the stored lock_id MUST be equal to the given value.
rpc PurgeRecycle (, )
gateway_api.proto:159Permanently removes a recycle item from the recycle. This operation is irrevocable. MUST return CODE_NOT_FOUND if the recycle item id does not exist.
rpc RefreshLock (, )
gateway_api.proto:196Refreshes the lock metadata of a storage resource. MUST return CODE_NOT_FOUND if the reference does not exist. MUST return CODE_FAILED_PRECONDITION if the reference is not locked or if the caller does not hold the lock. The caller MUST have write permissions on the resource.
rpc RemoveLabel (, )
gateway_api.proto:282Removes a label from a resource for a user.
Restores a file version for the provided reference. MUST return CODE_NOT_FOUND if the reference does not exist. MUST return CODE_NOT_FOUND if the version does not exist.
Restores a recycle item from the recycle. MUST return CODE_NOT_FOUND if the recycle item id does not exist. MUST return CODE_FAILED_PRECONDITION if the restore_path is non-empty and the recycle item cannot be restored to the restore_path.
rpc RetryTransfer (, )
gateway_api.proto:482Requests retrying a transfer.
*****************************************************************/ ************************** Permissions **************************/ *****************************************************************/
Sets arbitrary metadata into a storage resource. Arbitrary metadata is returned in a cs3.storage.provider.v1beta1.ResourceInfo.
Sets the default app provider for a specified mime type.
*****************************************************************/ ************************ USER PROVIDER **************************/ *****************************************************************/
rpc SetImmutable (, )
gateway_api.proto:216Set the immutable attribute on a resource. Files become frozen (irreversible), containers become protected (reversible). See cs3org/cs3apis#272 for the specification.
rpc SetKey (, )
gateway_api.proto:270Maps the key-value pair.
rpc SetLock (, )
gateway_api.proto:186Locks a storage resource. MUST return CODE_NOT_FOUND if the reference does not exist. MUST return CODE_FAILED_PRECONDITION if the reference is already locked. In addition, the implementation MUST ensure atomicity when multiple users concurrently attempt to set a lock. The caller MUST have write permissions on the resource.
rpc Stat (, )
gateway_api.proto:171Returns the resource information at the provided reference. MUST return CODE_NOT_FOUND if the reference does not exist.
rpc TouchFile (, )
gateway_api.proto:108Creates a new resource of type file. MUST return CODE_FAILED_PRECONDITION if the file cannot be created at the specified reference.
rpc Unlock (, )
gateway_api.proto:202Unlocks a storage resource. MUST return CODE_NOT_FOUND if the reference does not exist. MUST return CODE_FAILED_PRECONDITION if the reference is not locked or if the caller does not hold the lock. The caller MUST have write permissions on the resource.
Unsets arbitrary metdata into a storage resource. Arbitrary metadata is returned in a cs3.storage.provider.v1beta1.ResourceInfo.
rpc UnsetImmutable (, )
gateway_api.proto:219Remove the immutable attribute from a resource. Only applicable to containers (protected). Frozen files cannot be unfrozen.
*****************************************************************/ ************************ APP PROVIDER ********************/ *****************************************************************/
Updates a storage space.
rpc WhoAmI (, )
gateway_api.proto:83WhoAmI returns the information for a user.
*****************************************************************/ ********************** APPLICATIONS AUTH ************************/ *****************************************************************/
message
gateway_api.proto:527optional opaque = 1
OPTIONAL. Opaque information.
string token = 2
REQUIRED. The access token.
message
gateway_api.proto:536optional status = 1
REQUIRED. The response status.
optional opaque = 2
OPTIONAL. Opaque information.
optional user = 3
REQUIRED. The user information.
message
resources.proto:64A file download protocol object stores information about downloading resources using a specific protocol.
Used in:
optional opaque = 1
OPTIONAL. Opaque information.
string protocol = 2
REQUIRED. The protocol to be followed.
string download_endpoint = 3
REQUIRED. The endpoint where to download the data. The value MUST be a Uniform Resource Identifier (URI) as specified in RFC 3986.
string token = 4
OPTIONAL. A token that MUST be validated by the data gateway for the download. Only makes sense for downloads passing through the data gateway.
message
resources.proto:39A file upload protocol object stores information about uploading resources using a specific protocol.
Used in:
optional opaque = 1
OPTIONAL. Opaque information.
string protocol = 2
REQUIRED. The protocol to be followed.
string upload_endpoint = 3
REQUIRED. The endpoint where to upload the data. The value MUST be a Uniform Resource Identifier (URI) as specified in RFC 3986.
repeated available_checksums = 4
REQUIRED. List of available checksums the client can use when sending the file.
string token = 5
OPTIONAL. A token that MUST be validated by the data gateway for the upload. Only makes sense for uploads passing through the data gateway.
OCMShareResourceInfo includes the sharing information and the storage-related information about an OCM share resource.
Used in:
optional opaque = 1
OPTIONAL. Opaque information.
optional ocm_share = 2
REQUIRED. The underlying share as returned by the collaboration service.
optional resource_info = 3
REQUIRED. The corresponding resource information as returned by the storage provider.
REQUIRED. View mode.
Used in:
VIEW_MODE_INVALID = 0
VIEW_MODE_VIEW_ONLY = 1
The resource can be opened but not downloaded.
VIEW_MODE_READ_ONLY = 2
The resource can be downloaded.
VIEW_MODE_READ_WRITE = 3
The resource can be downloaded and updated. The underlying application MUST be a fully capable editor to support this mode.
VIEW_MODE_PREVIEW = 4
The resource can be downloaded and updated, but must be shown in preview mode. If the underlying application does not support a preview mode, or if in a view-only mode users are not allowed to switch to edit mode, then this mode MUST fall back to READ_WRITE.
VIEW_MODE_EMBEDDED = 5
The resource can be viewed in embedded mode. Editing is disabled.
PublicShareResourceInfo includes the sharing information and the storage-related information about a public share resource.
Used in:
optional opaque = 1
OPTIONAL. Opaque information.
optional public_share = 2
REQUIRED. The underlying share as returned by the collaboration service.
optional resource_info = 3
REQUIRED. The corresponding resource information as returned by the storage provider.
ReceivedShareResourceInfo includes the sharing information and the storage-related information about a received share resource.
Used in:
optional opaque = 1
OPTIONAL. Opaque information.
optional received_share = 2
REQUIRED. The underlying share as returned by the collaboration service.
optional resource_info = 3
REQUIRED. The corresponding resource information as returned by the storage provider.
ShareResourceInfo includes the sharing information and the storage-related information about a share resource.
Used in:
optional opaque = 1
OPTIONAL. Opaque information.
optional share = 2
REQUIRED. The underlying share as returned by the collaboration service.
optional resource_info = 3
REQUIRED. The corresponding resource information as returned by the storage provider.