Protocol Documentation

Table of Contents

cs3/gateway/v1beta1/gateway_api.proto

Top

AuthenticateRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

type string

REQUIRED. The type of authentication to use.

client_id string

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.

client_secret string

OPTIONAL. The secret of the client.

AuthenticateResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

token string

REQUIRED. The access token.

user cs3.identity.user.v1beta1.User

REQUIRED. The authenticated user.

GetQuotaRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref cs3.storage.provider.v1beta1.Reference

REQUIRED. The reference to which the action should be performed.

InitiateFileDownloadResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

protocols FileDownloadProtocol repeated

REQUIRED. The protocols through which data can be downloaded.

InitiateFileUploadResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

protocols FileUploadProtocol repeated

REQUIRED. The protocols through which data can be uploaded.

ListAuthProvidersResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

types string repeated

REQUIRED. The list of auth types. TODO(labkode): maybe add description?

OpenInAppRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref cs3.storage.provider.v1beta1.Reference

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)

view_mode OpenInAppRequest.ViewMode

app string

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.

lock_id string

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.

WhoAmIRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

token string

REQUIRED. The access token.

WhoAmIResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

user cs3.identity.user.v1beta1.User

REQUIRED. The user information.

OpenInAppRequest.ViewMode

REQUIRED.

View mode.

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

GatewayAPI

Gateway API

The Gateway API is the only API exposed direclty 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 ******** **************************/

*****************************************************************/

Method NameRequest TypeResponse TypeDescription
Authenticate AuthenticateRequest AuthenticateResponse

Authenticates a user.

WhoAmI WhoAmIRequest WhoAmIResponse

WhoAmI returns the information for a user. *****************************************************************/ ********************** APPLICATIONS AUTH ************************/ *****************************************************************/

GenerateAppPassword .cs3.auth.applications.v1beta1.GenerateAppPasswordRequest .cs3.auth.applications.v1beta1.GenerateAppPasswordResponse

GenerateAppPassword creates a password with specified scope to be used by third-party applications.

ListAppPasswords .cs3.auth.applications.v1beta1.ListAppPasswordsRequest .cs3.auth.applications.v1beta1.ListAppPasswordsResponse

ListAppPasswords lists the application passwords created by a user.

InvalidateAppPassword .cs3.auth.applications.v1beta1.InvalidateAppPasswordRequest .cs3.auth.applications.v1beta1.InvalidateAppPasswordResponse

InvalidateAppPassword invalidates a generated password.

GetAppPassword .cs3.auth.applications.v1beta1.GetAppPasswordRequest .cs3.auth.applications.v1beta1.GetAppPasswordResponse

GetAppPassword retrieves the password information by the combination of username and password. *****************************************************************/ ************************ STORAGE PROVIDER ***********************/ *****************************************************************/

CreateContainer .cs3.storage.provider.v1beta1.CreateContainerRequest .cs3.storage.provider.v1beta1.CreateContainerResponse

Creates a new resource of type container. MUST return CODE_FAILED_PRECONDITION if the container cannot be created at the specified reference.

TouchFile .cs3.storage.provider.v1beta1.TouchFileRequest .cs3.storage.provider.v1beta1.TouchFileResponse

Creates a new resource of type file. MUST return CODE_FAILED_PRECONDITION if the file cannot be created at the specified reference.

Delete .cs3.storage.provider.v1beta1.DeleteRequest .cs3.storage.provider.v1beta1.DeleteResponse

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

GetPath .cs3.storage.provider.v1beta1.GetPathRequest .cs3.storage.provider.v1beta1.GetPathResponse

Returns the path reference for the provided resource id reference. MUST return CODE_NOT_FOUND if the reference does not exist

GetQuota GetQuotaRequest .cs3.storage.provider.v1beta1.GetQuotaResponse

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

InitiateFileDownload .cs3.storage.provider.v1beta1.InitiateFileDownloadRequest InitiateFileDownloadResponse

Initiates the download of a file using an out-of-band data transfer mechanism.

InitiateFileUpload .cs3.storage.provider.v1beta1.InitiateFileUploadRequest InitiateFileUploadResponse

Initiates the upload of a file using an out-of-band data transfer mechanism.

ListContainerStream .cs3.storage.provider.v1beta1.ListContainerStreamRequest .cs3.storage.provider.v1beta1.ListContainerStreamResponse stream

Returns a stream of resource informations for the provided reference. MUST return CODE_NOT_FOUND if the reference does not exists.

ListContainer .cs3.storage.provider.v1beta1.ListContainerRequest .cs3.storage.provider.v1beta1.ListContainerResponse

Returns a list of resource information for the provided reference. MUST return CODE_NOT_FOUND if the reference does not exists.

ListFileVersions .cs3.storage.provider.v1beta1.ListFileVersionsRequest .cs3.storage.provider.v1beta1.ListFileVersionsResponse

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?

ListRecycleStream .cs3.storage.provider.v1beta1.ListRecycleStreamRequest .cs3.storage.provider.v1beta1.ListRecycleStreamResponse stream

Returns a stream of recycle items for this storage provider.

ListRecycle .cs3.storage.provider.v1beta1.ListRecycleRequest .cs3.storage.provider.v1beta1.ListRecycleResponse

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

Move .cs3.storage.provider.v1beta1.MoveRequest .cs3.storage.provider.v1beta1.MoveResponse

Moves 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 cannot be moved to the destination reference.

PurgeRecycle .cs3.storage.provider.v1beta1.PurgeRecycleRequest .cs3.storage.provider.v1beta1.PurgeRecycleResponse

Permanently removes a recycle item from the recycle. This operation is irrevocable. MUST return CODE_NOT_FOUND if the recycle item id does not exist.

RestoreFileVersion .cs3.storage.provider.v1beta1.RestoreFileVersionRequest .cs3.storage.provider.v1beta1.RestoreFileVersionResponse

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.

RestoreRecycleItem .cs3.storage.provider.v1beta1.RestoreRecycleItemRequest .cs3.storage.provider.v1beta1.RestoreRecycleItemResponse

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.

Stat .cs3.storage.provider.v1beta1.StatRequest .cs3.storage.provider.v1beta1.StatResponse

Returns the resource information at the provided reference. MUST return CODE_NOT_FOUND if the reference does not exist.

CreateSymlink .cs3.storage.provider.v1beta1.CreateSymlinkRequest .cs3.storage.provider.v1beta1.CreateSymlinkResponse

Creates a symlink to another resource.

SetArbitraryMetadata .cs3.storage.provider.v1beta1.SetArbitraryMetadataRequest .cs3.storage.provider.v1beta1.SetArbitraryMetadataResponse

Sets arbitrary metadata into a storage resource. Arbitrary metadata is returned in a cs3.storage.provider.v1beta1.ResourceInfo.

UnsetArbitraryMetadata .cs3.storage.provider.v1beta1.UnsetArbitraryMetadataRequest .cs3.storage.provider.v1beta1.UnsetArbitraryMetadataResponse

Unsets arbitrary metdata into a storage resource. Arbitrary metadata is returned in a cs3.storage.provider.v1beta1.ResourceInfo.

SetLock .cs3.storage.provider.v1beta1.SetLockRequest .cs3.storage.provider.v1beta1.SetLockResponse

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

GetLock .cs3.storage.provider.v1beta1.GetLockRequest .cs3.storage.provider.v1beta1.GetLockResponse

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

RefreshLock .cs3.storage.provider.v1beta1.RefreshLockRequest .cs3.storage.provider.v1beta1.RefreshLockResponse

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

Unlock .cs3.storage.provider.v1beta1.UnlockRequest .cs3.storage.provider.v1beta1.UnlockResponse

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

CreateHome .cs3.storage.provider.v1beta1.CreateHomeRequest .cs3.storage.provider.v1beta1.CreateHomeResponse

Creates the home directory for a user.

CreateStorageSpace .cs3.storage.provider.v1beta1.CreateStorageSpaceRequest .cs3.storage.provider.v1beta1.CreateStorageSpaceResponse

Creates a storage space.

ListStorageSpaces .cs3.storage.provider.v1beta1.ListStorageSpacesRequest .cs3.storage.provider.v1beta1.ListStorageSpacesResponse

Lists storage spaces.

UpdateStorageSpace .cs3.storage.provider.v1beta1.UpdateStorageSpaceRequest .cs3.storage.provider.v1beta1.UpdateStorageSpaceResponse

Updates a storage space.

DeleteStorageSpace .cs3.storage.provider.v1beta1.DeleteStorageSpaceRequest .cs3.storage.provider.v1beta1.DeleteStorageSpaceResponse

Deletes a storage space. *****************************************************************/ ************************ APP PROVIDER ********************/ *****************************************************************/

OpenInApp OpenInAppRequest .cs3.app.provider.v1beta1.OpenInAppResponse

Returns 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 ********************/ *****************************************************************/

CreateShare .cs3.sharing.collaboration.v1beta1.CreateShareRequest .cs3.sharing.collaboration.v1beta1.CreateShareResponse

Creates a new share. MUST return CODE_NOT_FOUND if the resource reference does not exist. MUST return CODE_LOCKED if the resource reference already locked. MUST return CODE_ALREADY_EXISTS if the share already exists for the 4-tuple consisting of (owner, shared_resource, grantee). New shares MUST be created in the state SHARE_STATE_PENDING.

RemoveShare .cs3.sharing.collaboration.v1beta1.RemoveShareRequest .cs3.sharing.collaboration.v1beta1.RemoveShareResponse

Removes a share. MUST return CODE_NOT_FOUND if the share reference does not exist.

GetShare .cs3.sharing.collaboration.v1beta1.GetShareRequest .cs3.sharing.collaboration.v1beta1.GetShareResponse

Gets share information for a single share. MUST return CODE_NOT_FOUND if the share reference does not exist.

ListShares .cs3.sharing.collaboration.v1beta1.ListSharesRequest .cs3.sharing.collaboration.v1beta1.ListSharesResponse

List the shares the authproviderenticated principal has created, both as owner and creator. If a filter is specified, only shares satisfying the filter MUST be returned.

UpdateShare .cs3.sharing.collaboration.v1beta1.UpdateShareRequest .cs3.sharing.collaboration.v1beta1.UpdateShareResponse

Updates a share. MUST return CODE_NOT_FOUND if the share reference does not exist.

ListReceivedShares .cs3.sharing.collaboration.v1beta1.ListReceivedSharesRequest .cs3.sharing.collaboration.v1beta1.ListReceivedSharesResponse

List all shares the authproviderenticated principal has received.

UpdateReceivedShare .cs3.sharing.collaboration.v1beta1.UpdateReceivedShareRequest .cs3.sharing.collaboration.v1beta1.UpdateReceivedShareResponse

Update the received share to change the share state or the display name. MUST return CODE_NOT_FOUND if the share reference does not exist.

GetReceivedShare .cs3.sharing.collaboration.v1beta1.GetReceivedShareRequest .cs3.sharing.collaboration.v1beta1.GetReceivedShareResponse

Get the information for the given received share reference. MUST return CODE_NOT_FOUND if the received share reference does not exist. *****************************************************************/ ************************ PREFERENCES ***************************/ *****************************************************************/

SetKey .cs3.preferences.v1beta1.SetKeyRequest .cs3.preferences.v1beta1.SetKeyResponse

Maps the key-value pair.

GetKey .cs3.preferences.v1beta1.GetKeyRequest .cs3.preferences.v1beta1.GetKeyResponse

Returns the value associated with the requested key. *****************************************************************/ ************************ PUBLIC SHARE ***************************/ *****************************************************************/

CreatePublicShare .cs3.sharing.link.v1beta1.CreatePublicShareRequest .cs3.sharing.link.v1beta1.CreatePublicShareResponse

Creates a new share. MUST return CODE_NOT_FOUND if the resource reference does not exist. MUST return CODE_ALREADY_EXISTS if the share already exists for the 4-tuple consisting of (owner, shared_resource, grantee). New shares MUST be created in the state SHARE_STATE_PENDING.

RemovePublicShare .cs3.sharing.link.v1beta1.RemovePublicShareRequest .cs3.sharing.link.v1beta1.RemovePublicShareResponse

Removes a share. MUST return CODE_NOT_FOUND if the share reference does not exist.

GetPublicShare .cs3.sharing.link.v1beta1.GetPublicShareRequest .cs3.sharing.link.v1beta1.GetPublicShareResponse

Gets share information for a single share. MUST return CODE_NOT_FOUND if the share reference does not exist.

GetPublicShareByToken .cs3.sharing.link.v1beta1.GetPublicShareByTokenRequest .cs3.sharing.link.v1beta1.GetPublicShareByTokenResponse

Gets share information for a single share by its unlisted token. MUST return CODE_NOT_FOUND if the share does not exist.

ListPublicShares .cs3.sharing.link.v1beta1.ListPublicSharesRequest .cs3.sharing.link.v1beta1.ListPublicSharesResponse

List the shares the authproviderenticated principal has created, both as owner and creator. If a filter is specified, only shares satisfying the filter MUST be returned.

UpdatePublicShare .cs3.sharing.link.v1beta1.UpdatePublicShareRequest .cs3.sharing.link.v1beta1.UpdatePublicShareResponse

Updates a share. MUST return CODE_NOT_FOUND if the share reference does not exist. *****************************************************************/ ************************ OCM SHARE PROVIDER *********************/ *****************************************************************/

CreateOCMShare .cs3.sharing.ocm.v1beta1.CreateOCMShareRequest .cs3.sharing.ocm.v1beta1.CreateOCMShareResponse

Creates a new ocm share. MUST return CODE_NOT_FOUND if the resource reference does not exist. MUST return CODE_ALREADY_EXISTS if the share already exists for the 4-tuple consisting of (owner, shared_resource, grantee). New shares MUST be created in the state SHARE_STATE_PENDING.

RemoveOCMShare .cs3.sharing.ocm.v1beta1.RemoveOCMShareRequest .cs3.sharing.ocm.v1beta1.RemoveOCMShareResponse

Removes a share. MUST return CODE_NOT_FOUND if the share reference does not exist.

GetOCMShare .cs3.sharing.ocm.v1beta1.GetOCMShareRequest .cs3.sharing.ocm.v1beta1.GetOCMShareResponse

Gets share information for a single share. MUST return CODE_NOT_FOUND if the share reference does not exist.

GetOCMShareByToken .cs3.sharing.ocm.v1beta1.GetOCMShareByTokenRequest .cs3.sharing.ocm.v1beta1.GetOCMShareByTokenResponse

Gets share information for a single share by its unlisted token. MUST return CODE_NOT_FOUND if the share does not exist.

ListOCMShares .cs3.sharing.ocm.v1beta1.ListOCMSharesRequest .cs3.sharing.ocm.v1beta1.ListOCMSharesResponse

List the shares the authproviderenticated principal has created, both as owner and creator. If a filter is specified, only shares satisfying the filter MUST be returned.

UpdateOCMShare .cs3.sharing.ocm.v1beta1.UpdateOCMShareRequest .cs3.sharing.ocm.v1beta1.UpdateOCMShareResponse

Updates a share. MUST return CODE_NOT_FOUND if the share reference does not exist.

ListReceivedOCMShares .cs3.sharing.ocm.v1beta1.ListReceivedOCMSharesRequest .cs3.sharing.ocm.v1beta1.ListReceivedOCMSharesResponse

List all shares the authproviderenticated principal has received.

UpdateReceivedOCMShare .cs3.sharing.ocm.v1beta1.UpdateReceivedOCMShareRequest .cs3.sharing.ocm.v1beta1.UpdateReceivedOCMShareResponse

Update the received share to change the share state or the display name. MUST return CODE_NOT_FOUND if the share reference does not exist.

GetReceivedOCMShare .cs3.sharing.ocm.v1beta1.GetReceivedOCMShareRequest .cs3.sharing.ocm.v1beta1.GetReceivedOCMShareResponse

Get the information for the given received share reference. MUST return CODE_NOT_FOUND if the received share reference does not exist. *****************************************************************/ ************************ APP REGISTRY ****************************/ *****************************************************************/

GetAppProviders .cs3.app.registry.v1beta1.GetAppProvidersRequest .cs3.app.registry.v1beta1.GetAppProvidersResponse

Returns the app providers that are capable of handling this resource info. MUST return CODE_NOT_FOUND if no providers are available.

AddAppProvider .cs3.app.registry.v1beta1.AddAppProviderRequest .cs3.app.registry.v1beta1.AddAppProviderResponse

Registers a new app provider to the registry.

ListAppProviders .cs3.app.registry.v1beta1.ListAppProvidersRequest .cs3.app.registry.v1beta1.ListAppProvidersResponse

Returns a list of the available app providers known by this registry.

ListSupportedMimeTypes .cs3.app.registry.v1beta1.ListSupportedMimeTypesRequest .cs3.app.registry.v1beta1.ListSupportedMimeTypesResponse

Returns a list of the supported mime types along with the apps which they can opened with.

GetDefaultAppProviderForMimeType .cs3.app.registry.v1beta1.GetDefaultAppProviderForMimeTypeRequest .cs3.app.registry.v1beta1.GetDefaultAppProviderForMimeTypeResponse

Returns the default app provider which serves a specified mime type.

SetDefaultAppProviderForMimeType .cs3.app.registry.v1beta1.SetDefaultAppProviderForMimeTypeRequest .cs3.app.registry.v1beta1.SetDefaultAppProviderForMimeTypeResponse

Sets the default app provider for a specified mime type. *****************************************************************/ ************************ USER PROVIDER **************************/ *****************************************************************/

GetUser .cs3.identity.user.v1beta1.GetUserRequest .cs3.identity.user.v1beta1.GetUserResponse

Gets the information about a user by the user id.

GetUserByClaim .cs3.identity.user.v1beta1.GetUserByClaimRequest .cs3.identity.user.v1beta1.GetUserByClaimResponse

Gets the information about a user based on a specified claim.

GetUserGroups .cs3.identity.user.v1beta1.GetUserGroupsRequest .cs3.identity.user.v1beta1.GetUserGroupsResponse

Gets the groups of a user.

FindUsers .cs3.identity.user.v1beta1.FindUsersRequest .cs3.identity.user.v1beta1.FindUsersResponse

Finds users by any attribute of the user. TODO(labkode): to define the filters that make more sense. *****************************************************************/ ************************ GROUP PROVIDER **************************/ *****************************************************************/

GetGroup .cs3.identity.group.v1beta1.GetGroupRequest .cs3.identity.group.v1beta1.GetGroupResponse

Gets the information about a group by the group id.

GetGroupByClaim .cs3.identity.group.v1beta1.GetGroupByClaimRequest .cs3.identity.group.v1beta1.GetGroupByClaimResponse

Gets the information about a group based on a specified claim.

GetMembers .cs3.identity.group.v1beta1.GetMembersRequest .cs3.identity.group.v1beta1.GetMembersResponse

Gets the members of a group.

HasMember .cs3.identity.group.v1beta1.HasMemberRequest .cs3.identity.group.v1beta1.HasMemberResponse

Tells if the group has a certain member.

FindGroups .cs3.identity.group.v1beta1.FindGroupsRequest .cs3.identity.group.v1beta1.FindGroupsResponse

TODO(labkode): to define the filters that make more sense. Finds groups whose names match the specified filter. *****************************************************************/ ************************ AUTH REGISTRY **************************/ *****************************************************************/

ListAuthProviders .cs3.auth.registry.v1beta1.ListAuthProvidersRequest ListAuthProvidersResponse

Returns a list of the available auth providers known by this registry. ************************ STORAGE REGISTRY ** ********************/ *****************************************************************/

GetHome .cs3.storage.provider.v1beta1.GetHomeRequest .cs3.storage.provider.v1beta1.GetHomeResponse

Returns 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 *********************/ *****************************************************************/

GenerateInviteToken .cs3.ocm.invite.v1beta1.GenerateInviteTokenRequest .cs3.ocm.invite.v1beta1.GenerateInviteTokenResponse

Generates a new token for the user with a validity of 24 hours.

ListInviteTokens .cs3.ocm.invite.v1beta1.ListInviteTokensRequest .cs3.ocm.invite.v1beta1.ListInviteTokensResponse

Lists the valid tokens generated by the user.

ForwardInvite .cs3.ocm.invite.v1beta1.ForwardInviteRequest .cs3.ocm.invite.v1beta1.ForwardInviteResponse

Forwards a received invite to the sync'n'share system provider.

AcceptInvite .cs3.ocm.invite.v1beta1.AcceptInviteRequest .cs3.ocm.invite.v1beta1.AcceptInviteResponse

Completes an invitation acceptance.

GetAcceptedUser .cs3.ocm.invite.v1beta1.GetAcceptedUserRequest .cs3.ocm.invite.v1beta1.GetAcceptedUserResponse

Retrieves details about a remote user who has accepted an invite to share.

FindAcceptedUsers .cs3.ocm.invite.v1beta1.FindAcceptedUsersRequest .cs3.ocm.invite.v1beta1.FindAcceptedUsersResponse

Finds users who accepted invite tokens by their attributes.

DeleteAcceptedUser .cs3.ocm.invite.v1beta1.DeleteAcceptedUserRequest .cs3.ocm.invite.v1beta1.DeleteAcceptedUserResponse

Delete a previously accepted remote user, that is unfriend that user. *****************************************************************/ ******************** OCM PROVIDER AUTHORIZER ********************/ *****************************************************************/

IsProviderAllowed .cs3.ocm.provider.v1beta1.IsProviderAllowedRequest .cs3.ocm.provider.v1beta1.IsProviderAllowedResponse

Check if a given system provider is registered in the mesh or not. MUST return CODE_UNAUTHENTICATED if the system is not registered

GetInfoByDomain .cs3.ocm.provider.v1beta1.GetInfoByDomainRequest .cs3.ocm.provider.v1beta1.GetInfoByDomainResponse

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

ListAllProviders .cs3.ocm.provider.v1beta1.ListAllProvidersRequest .cs3.ocm.provider.v1beta1.ListAllProvidersResponse

Get the information of all the providers registered in the mesh. *****************************************************************/ **************************** OCM CORE ***************************/ *****************************************************************/

CreateOCMCoreShare .cs3.ocm.core.v1beta1.CreateOCMCoreShareRequest .cs3.ocm.core.v1beta1.CreateOCMCoreShareResponse

Creates a new OCM share.

UpdateOCMCoreShare .cs3.ocm.core.v1beta1.UpdateOCMCoreShareRequest .cs3.ocm.core.v1beta1.UpdateOCMCoreShareResponse

Updates an OCM share.

DeleteOCMCoreShare .cs3.ocm.core.v1beta1.DeleteOCMCoreShareRequest .cs3.ocm.core.v1beta1.DeleteOCMCoreShareResponse

Deletes an OCM share. *****************************************************************/ ************************** FILE TRANSFER ************************/ *****************************************************************/

CreateTransfer .cs3.tx.v1beta1.CreateTransferRequest .cs3.tx.v1beta1.CreateTransferResponse

Requests creation of a transfer.

GetTransferStatus .cs3.tx.v1beta1.GetTransferStatusRequest .cs3.tx.v1beta1.GetTransferStatusResponse

Requests a transfer status.

CancelTransfer .cs3.tx.v1beta1.CancelTransferRequest .cs3.tx.v1beta1.CancelTransferResponse

Requests to cancel a transfer.

ListTransfers .cs3.tx.v1beta1.ListTransfersRequest .cs3.tx.v1beta1.ListTransfersResponse

Requests a list of transfers received by the authenticated principle.

RetryTransfer .cs3.tx.v1beta1.RetryTransferRequest .cs3.tx.v1beta1.RetryTransferResponse

Requests retrying a transfer. *****************************************************************/ ************************** Permissions **************************/ *****************************************************************/

CheckPermission .cs3.permissions.v1beta1.CheckPermissionRequest .cs3.permissions.v1beta1.CheckPermissionResponse

CheckPermission checks if a user or group has a certain permission.

cs3/gateway/v1beta1/resources.proto

Top

FileDownloadProtocol

A file download protocol object stores information about

downloading resources using a specific protocol.

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

protocol string

REQUIRED. The protocol to be followed.

download_endpoint string

REQUIRED. The endpoint where to download the data. The value MUST be a Uniform Resource Identifier (URI) as specified in RFC 3986.

token string

OPTIONAL. A token that MUST be validated by the data gateway for the download. Only makes sense for downloads passing through the data gateway.

FileUploadProtocol

A file upload protocol object stores information about

uploading resources using a specific protocol.

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

protocol string

REQUIRED. The protocol to be followed.

upload_endpoint string

REQUIRED. The endpoint where to upload the data. The value MUST be a Uniform Resource Identifier (URI) as specified in RFC 3986.

available_checksums cs3.storage.provider.v1beta1.ResourceChecksumPriority repeated

REQUIRED. List of available checksums the client can use when sending the file.

token string

OPTIONAL. A token that MUST be validated by the data gateway for the upload. Only makes sense for uploads passing through the data gateway.

cs3/permissions/v1beta1/permissions_api.proto

Top

CheckPermissionRequest

CheckPermissionsRequest is used to check if a user has a certain permission.

FieldTypeLabelDescription
permission string

REQUIRED. The permission to check.

subject_ref SubjectReference

REQUIRED. The subject holding the permission.

ref cs3.storage.provider.v1beta1.Reference

OPTIONAL. The target resource of the permission.

CheckPermissionResponse

CheckPermissionsResponse ...

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

PermissionsAPI

PermissionsAPI defines a service for permissions.

Method NameRequest TypeResponse TypeDescription
CheckPermission CheckPermissionRequest CheckPermissionResponse

CheckPermission defines a method to check permission/role.

cs3/permissions/v1beta1/resources.proto

Top

SubjectReference

SubjectReference references either a user or a group by id.

FieldTypeLabelDescription
user_id cs3.identity.user.v1beta1.UserId

group_id cs3.identity.group.v1beta1.GroupId

cs3/preferences/v1beta1/preferences_api.proto

Top

GetKeyRequest

FieldTypeLabelDescription
key PreferenceKey

REQUIRED.

GetKeyResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

val string

REQUIRED. The value associated with the key.

SetKeyRequest

FieldTypeLabelDescription
key PreferenceKey

REQUIRED.

val string

REQUIRED. The value associated with the key.

SetKeyResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

PreferencesAPI

Preferences API.

The Preferences API is responsible for creating

a key-value map according to user preferences.

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.

Method NameRequest TypeResponse TypeDescription
SetKey SetKeyRequest SetKeyResponse

Maps the key-value pair.

GetKey GetKeyRequest GetKeyResponse

Returns the value associated with the requested key.

cs3/preferences/v1beta1/resources.proto

Top

PreferenceKey

Represents a key object consisting of a namespace and a string key.

FieldTypeLabelDescription
namespace string

REQUIRED. The namespace to which the key belongs.

key string

REQUIRED.

cs3/rpc/v1beta1/code.proto

Top

Code

These are the canonical error codes used by CS3 APIs.

Adapted from Google APIs:

https://github.com/googleapis/googleapis/

Sometimes multiple error codes may apply. Services should return

the most specific error code that applies. For example, prefer

`OUT_OF_RANGE` over `FAILED_PRECONDITION` if both codes apply.

Similarly prefer `NOT_FOUND` or `ALREADY_EXISTS` over `FAILED_PRECONDITION`.

NameNumberDescription
CODE_INVALID 0

A programmer would not intentionally set the code to CODE_INVALID. This code exists to force service implementors to set a specific code for the API call and to not rely on defaults. HTTP Mapping: 500 Internal Server Error

CODE_OK 1

Not an error; returned on success HTTP Mapping: 200 OK

CODE_CANCELLED 2

The operation was cancelled, typically by the caller. HTTP Mapping: 499 Client Closed Request

CODE_UNKNOWN 3

Unknown error. For example, this error may be returned when a `Status` value received from another address space belongs to an error space that is not known in this address space. Also errors raised by APIs that do not return enough error information may be converted to this error. HTTP Mapping: 500 Internal Server Error

CODE_INVALID_ARGUMENT 4

The client specified an invalid argument. Note that this differs from `FAILED_PRECONDITION`. `INVALID_ARGUMENT` indicates arguments that are problematic regardless of the state of the system (e.g., a malformed file name). HTTP Mapping: 400 Bad Request

CODE_DEADLINE_EXCEEDED 5

The deadline expired before the operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long enough for the deadline to expire. HTTP Mapping: 504 Gateway Timeout

CODE_NOT_FOUND 6

Some requested entity (e.g., file or directory) was not found. Note to server developers: if a request is denied for an entire class of users, such as gradual feature rollout or undocumented whitelist, `NOT_FOUND` may be used. If a request is denied for some users within a class of users, such as user-based access control, `PERMISSION_DENIED` must be used. HTTP Mapping: 404 Not Found

CODE_ALREADY_EXISTS 7

The entity that a client attempted to create (e.g., file or directory) already exists. HTTP Mapping: 409 Conflict

CODE_PERMISSION_DENIED 8

The caller does not have permission to execute the specified operation. `PERMISSION_DENIED` must not be used for rejections caused by exhausting some resource (use `RESOURCE_EXHAUSTED` instead for those errors). `PERMISSION_DENIED` must not be used if the caller can not be identified (use `UNAUTHENTICATED` instead for those errors). This error code does not imply the request is valid or the requested entity exists or satisfies other pre-conditions. HTTP Mapping: 403 Forbidden

CODE_UNAUTHENTICATED 9

The request does not have valid authentication credentials for the operation. HTTP Mapping: 401 Unauthorized

CODE_RESOURCE_EXHAUSTED 10

Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space. HTTP Mapping: 429 Too Many Requests

CODE_FAILED_PRECONDITION 11

The operation was rejected because the system is not in a state required for the operation's execution. For example, the directory to be deleted is non-empty, an rmdir operation is applied to a non-directory, etc. Service implementors can use the following guidelines to decide between `FAILED_PRECONDITION`, `ABORTED`, and `UNAVAILABLE`: (a) Use `UNAVAILABLE` if the client can retry just the failing call. (b) Use `ABORTED` if the client should retry at a higher level (e.g., when a client-specified test-and-set fails, indicating the client should restart a read-modify-write sequence). (c) Use `FAILED_PRECONDITION` if the client should not retry until the system state has been explicitly fixed. E.g., if an "rmdir" fails because the directory is non-empty, `FAILED_PRECONDITION` should be returned since the client should not retry unless the files are deleted from the directory. HTTP Mapping: 400 Bad Request

CODE_ABORTED 12

The operation was aborted, typically due to a concurrency issue such as a sequencer check failure or transaction abort. See the guidelines above for deciding between `FAILED_PRECONDITION`, `ABORTED`, and `UNAVAILABLE`. HTTP Mapping: 409 Conflict

CODE_OUT_OF_RANGE 13

The operation was attempted past the valid range. E.g., seeking or reading past end-of-file. Unlike `INVALID_ARGUMENT`, this error indicates a problem that may be fixed if the system state changes. For example, a 32-bit file system will generate `INVALID_ARGUMENT` if asked to read at an offset that is not in the range [0,2^32-1], but it will generate `OUT_OF_RANGE` if asked to read from an offset past the current file size. There is a fair bit of overlap between `FAILED_PRECONDITION` and `OUT_OF_RANGE`. We recommend using `OUT_OF_RANGE` (the more specific error) when it applies so that callers who are iterating through a space can easily look for an `OUT_OF_RANGE` error to detect when they are done. HTTP Mapping: 400 Bad Request

CODE_UNIMPLEMENTED 14

The operation is not implemented or is not supported/enabled in this service. HTTP Mapping: 501 Not Implemented

CODE_INTERNAL 15

Internal errors. This means that some invariants expected by the underlying system have been broken. This error code is reserved for serious errors. HTTP Mapping: 500 Internal Server Error

CODE_UNAVAILABLE 16

The service is currently unavailable. This is most likely a transient condition, which can be corrected by retrying with a backoff. See the guidelines above for deciding between `FAILED_PRECONDITION`, `ABORTED`, and `UNAVAILABLE`. HTTP Mapping: 503 Service Unavailable

CODE_DATA_LOSS 17

Unrecoverable data loss or corruption. HTTP Mapping: 500 Internal Server Error

CODE_REDIRECTION 18

Redirects the operation to another location. Used in a Status reponse with a reference to the target URI.

CODE_INSUFFICIENT_STORAGE 19

The operation could not be performed because there is not enough storage available. This can be because of lack of real storage space or because of the exceeding of a quota associated to a storage. HTTP Mapping: 507 Insufficient Storage

CODE_LOCKED 20

The ability to lock a resource is specific to some WebDAV servers. The HTTP 423 Locked error response code indicates that either the resources tentatively targeted by is locked, meaning it can't be accessed. HTTP Mapping: 423 Locked

cs3/rpc/v1beta1/status.proto

Top

Status

The `Status` message contains two pieces of data: error code and error message.

The error code should be an enum value of [cs3.rpc.code].

The error message should be a developer-facing English

message that helps developers *understand* and *resolve* the error.

FieldTypeLabelDescription
code Code

REQUIRED. The status code, which should be an enum value of [cs3.rpc.code][cs3.rpc.code].

message string

OPTIONAL. A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the

trace string

OPTIONAL. A trace added to the response for helping support to identify client problems.

target_uri string

OPTIONAL. A target URI as per RFC3986 to redirect requests to another location. A Status message with CODE_REDIRECT MUST always set the target_uri. https://golang.org/pkg/net/url/#URL provides a quick view of the format.

cs3/tx/v1beta1/resources.proto

Top

TxId

TxId uniquely identifies a transfer in the transfer provider namespace.

FieldTypeLabelDescription
opaque_id string

REQUIRED. The internal transfer id used by the service implementor to uniquely identity the transfer in the internal implementation of the service.

TxInfo

TxInfo represents information about a transfer.

FieldTypeLabelDescription
id TxId

REQUIRED. The transfer identifier.

status Status

REQUIRED. The transfer status. Eg.: STATUS_TRANSFER_FAILED. Note: the description field may provide additional information on the transfer status.

grantee cs3.storage.provider.v1beta1.Grantee

REQUIRED. The destination (receiver of the transfer)

creator cs3.identity.user.v1beta1.UserId

REQUIRED. Uniquely identifies a principal who initiates the transfer creation.

ctime cs3.types.v1beta1.Timestamp

REQUIRED. Creation time of the transfer.

description string

OPTIONAL. Information to describe the transfer status. Eg. may contain information about a transfer failure. Meant to be human-readable.

share_id cs3.sharing.ocm.v1beta1.ShareId

REQUIRED. Opaque unique identifier of the share on which the transfer is based.

Status

Status represents transfer status.

NameNumberDescription
STATUS_INVALID 0

STATUS_DESTINATION_NOT_FOUND 1

The destination could not be found.

STATUS_TRANSFER_NEW 2

A new data transfer

STATUS_TRANSFER_AWAITING_ACCEPTANCE 3

The data transfer is awaiting acceptance from the destination

STATUS_TRANSFER_ACCEPTED 4

The data transfer is accepted by the destination.

STATUS_TRANSFER_IN_PROGRESS 5

The data transfer has started and not yet completed.

STATUS_TRANSFER_COMPLETE 6

The data transfer has completed.

STATUS_TRANSFER_FAILED 7

The data transfer has failed.

STATUS_TRANSFER_CANCELLED 8

The data transfer had been cancelled.

STATUS_TRANSFER_CANCEL_FAILED 9

The request for cancelling the data transfer has failed.

STATUS_TRANSFER_EXPIRED 10

The transfer has expired somewhere down the line.

cs3/tx/v1beta1/tx_api.proto

Top

CancelTransferRequest

FieldTypeLabelDescription
tx_id TxId

REQUIRED. The transfer identifier.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

CancelTransferResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

tx_info TxInfo

REQUIRED. TxInfo, includes ao. transfer id, status, description.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

CreateTransferRequest

FieldTypeLabelDescription
src_target_uri string

REQUIRED. The source target URI. Should include at the minimum all the info needed to access the source. https://golang.org/pkg/net/url/#URL provides a quick view of the format.

dest_target_uri string

REQUIRED. The destination target URI. Should include at the minimum all the info needed to access the destination. https://golang.org/pkg/net/url/#URL provides a quick view of the format.

share_id cs3.sharing.ocm.v1beta1.ShareId

REQUIRED. The share Id of the share this transfer is based on.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

CreateTransferResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

tx_info TxInfo

REQUIRED. TxInfo, includes transfer id, status, description.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

GetTransferStatusRequest

FieldTypeLabelDescription
tx_id TxId

REQUIRED. The transfer identifier.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

GetTransferStatusResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

tx_info TxInfo

REQUIRED. TxInfo, includes ao. transfer id, status, description.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ListTransfersRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

filters ListTransfersRequest.Filter repeated

OPTIONAL. The list of filters to apply if any.

ListTransfersRequest.Filter

REQUIRED.

Represents a filter to apply to the request.

FieldTypeLabelDescription
type ListTransfersRequest.Filter.Type

REQUIRED.

status Status

share_id cs3.sharing.ocm.v1beta1.ShareId

tx_id TxId

ListTransfersResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

transfers TxInfo repeated

REQUIRED. List of TxInfo types representing transfers.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

RetryTransferRequest

FieldTypeLabelDescription
tx_id TxId

REQUIRED. The transfer identifier.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

RetryTransferResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

tx_info TxInfo

REQUIRED. TxInfo, includes ao. transfer id, status, description.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ListTransfersRequest.Filter.Type

The filter type.

NameNumberDescription
TYPE_INVALID 0

TYPE_STATUS 1

TYPE_SHARE_ID 2

TYPE_TX_ID 3

TxAPI

Tx API

The Tx API provides data transfer capabilities.

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.

Method NameRequest TypeResponse TypeDescription
CreateTransfer CreateTransferRequest CreateTransferResponse

Requests creation of a transfer. Returns a CreateTransferResponse.

GetTransferStatus GetTransferStatusRequest GetTransferStatusResponse

Requests a transfer status.

CancelTransfer CancelTransferRequest CancelTransferResponse

Requests to cancel a transfer.

ListTransfers ListTransfersRequest ListTransfersResponse

Requests a list of transfers received by the authenticated principle. If a filter is specified, only transfers satisfying the filter MUST be returned.

RetryTransfer RetryTransferRequest RetryTransferResponse

Requests retrying a transfer.

cs3/types/v1beta1/types.proto

Top

Opaque

Opaque represents opaque information

in a form on a map.

For example, a local filesystem can

use this message to include filesystem

extended attributes.

FieldTypeLabelDescription
map Opaque.MapEntry repeated

REQUIRED.

Opaque.MapEntry

FieldTypeLabelDescription
key string

value OpaqueEntry

OpaqueEntry

OpaqueEntry represents the encoded

opaque value.

FieldTypeLabelDescription
decoder string

REQUIRED. The decoder to use: json, xml, toml, ... TODO(labkode): make encoder a fixed set using a enum type?

value bytes

REQUIRED. The encoded value.

Timestamp

Adapted from Google google/protobuf/timestamp.proto.

A Timestamp represents a point in time independent of any time zone or local

calendar, encoded as a count of seconds and fractions of seconds at

nanosecond resolution. The count is relative to an epoch at UTC midnight on

January 1, 1970, in the proleptic Gregorian calendar which extends the

Gregorian calendar backwards to year one.

The range MUST be from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z.

Restricting to this range ensures the conversion from and to [RFC

3339](https://www.ietf.org/rfc/rfc3339.txt) date strings.

FieldTypeLabelDescription
seconds uint64

Represents seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. Must be from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z inclusive.

nanos uint32

Non-negative fractions of a second at nanosecond resolution. Negative second values with fractions must still have non-negative nanos values that count forward in time. Value MUST be from 0 to 999,999,999 inclusive.

cs3/admin/group/v1beta1/group_api.proto

Top

AddUserToGroupRequest

FieldTypeLabelDescription
user_id cs3.identity.user.v1beta1.UserId

REQUIRED. ID of the user to add to the group

group_id cs3.identity.group.v1beta1.GroupId

REQUIRED. ID of the target group.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

AddUserToGroupResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

CreateGroupRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information. Allow to send any arbitrary data a service might use that is outside the API boundaries

group cs3.identity.group.v1beta1.Group

REQUIRED. The information of group to be created.

CreateGroupResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

group cs3.identity.group.v1beta1.Group

REQUIRED. The group information.

DeleteGroupRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information. Allow to send any arbitrary data a service might use that is outside the API boundaries.

group_id cs3.identity.group.v1beta1.GroupId

REQUIRED. The group to be deleted, given their ID.

DeleteGroupResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

RemoveUserFromGroupRequest

FieldTypeLabelDescription
user_id cs3.identity.user.v1beta1.UserId

REQUIRED. ID of the user to add to the group

group_id cs3.identity.group.v1beta1.GroupId

REQUIRED. ID of the target group.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

RemoveUserFromGroupResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

GroupAPI

Provides a write only API for managing groups.

Method NameRequest TypeResponse TypeDescription
CreateGroup CreateGroupRequest CreateGroupResponse

Create a group.

DeleteGroup DeleteGroupRequest DeleteGroupResponse

Delete a group.

AddUserToGroup AddUserToGroupRequest AddUserToGroupResponse

Add a user to a group.

RemoveUserFromGroup RemoveUserFromGroupRequest RemoveUserFromGroupResponse

Remove a user from a group.

cs3/admin/user/v1beta1/user_api.proto

Top

CreateUserRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information. Allow to send any arbitrary data a service might use that is outside the API boundaries

user cs3.identity.user.v1beta1.User

REQUIRED. The information of user to be created.

CreateUserResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

user cs3.identity.user.v1beta1.User

REQUIRED. The user information.

DeleteUserRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information. Allow to send any arbitrary data a service might use that is outside the API boundaries

user_id cs3.identity.user.v1beta1.UserId

REQUIRED. The user to be deleted, given their ID.

DeleteUserResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

UserAPI

Provides a write only API for managing users.

Method NameRequest TypeResponse TypeDescription
CreateUser CreateUserRequest CreateUserResponse

Create a user account.

DeleteUser DeleteUserRequest DeleteUserResponse

Delete a user account.

cs3/app/provider/v1beta1/provider_api.proto

Top

OpenInAppRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

resource_info cs3.storage.provider.v1beta1.ResourceInfo

REQUIRED. The resourceInfo to be opened. The gateway grpc message has a ref instead.

view_mode ViewMode

REQUIRED. View mode.

access_token string

REQUIRED. The access token this application provider will use when contacting the storage provider to read and write. Service implementors MUST make sure that the access token only grants access to the requested resource. Service implementors should use a ResourceId rather than a filepath to grant access, as ResourceIds MUST NOT change when a resource is renamed. The access token MUST be short-lived. TODO(labkode): investigate token derivation techniques.

OpenInAppResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

app_url OpenInAppURL

REQUIRED. The url that user agents will render to clients. Usually the rendering happens by using HTML iframes or in separate browser tabs.

ProviderAPI

App Provider API

The App Provider API is responsible for creating URLs that

will render a viewer or editor for the given resource, typically via WOPI protocol.

For example, a Collabora or HackMD editor.

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.

Method NameRequest TypeResponse TypeDescription
OpenInApp OpenInAppRequest OpenInAppResponse

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

cs3/app/provider/v1beta1/resources.proto

Top

OpenInAppURL

Represents the information for the app URL to be called by the clients.

FieldTypeLabelDescription
app_url string

REQUIRED. The URL that clients will perform requests to.

method string

REQUIRED. The method for the request to be made. Only GET and POST are supported.

form_parameters OpenInAppURL.FormParametersEntry repeated

OPTIONAL. The form parameters which have to be passed along with the request. These are sent only if the method is 'POST'.

headers OpenInAppURL.HeadersEntry repeated

OPTIONAL. The headers to be added to the request.

target Target

REQUIRED. Whether the target for the app URL is an iframe or a new page.

OpenInAppURL.FormParametersEntry

FieldTypeLabelDescription
key string

value string

OpenInAppURL.HeadersEntry

FieldTypeLabelDescription
key string

value string

Target

Defines the valid targets for an app URL.

NameNumberDescription
TARGET_INVALID 0

TARGET_IFRAME 1

The app URL is to be opened within an iframe

TARGET_BLANK 2

The app URL is to be opened on a new blank page

ViewMode

Defines the view modes.

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

cs3/app/registry/v1beta1/registry_api.proto

Top

AddAppProviderRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

provider ProviderInfo

REQUIRED. The app provider to be registered.

AddAppProviderResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

GetAppProvidersRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

resource_info cs3.storage.provider.v1beta1.ResourceInfo

REQUIRED. The resource information.

GetAppProvidersResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

providers ProviderInfo repeated

REQUIRED. The app providers available for the given resource info.

GetDefaultAppProviderForMimeTypeRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

mime_type string

REQUIRED. The mimetype for which the default app has to be returned.

GetDefaultAppProviderForMimeTypeResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

provider ProviderInfo

REQUIRED. The default app provider for the specified mime type.

ListAppProvidersRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ListAppProvidersResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

providers ProviderInfo repeated

REQUIRED. The list of app providers this registry knows about.

ListSupportedMimeTypesRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ListSupportedMimeTypesResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

mime_types MimeTypeInfo repeated

REQUIRED. The list of supported mime types and their properties.

SetDefaultAppProviderForMimeTypeRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

mime_type string

REQUIRED. The mimetype for which the default app has to be returned.

provider ProviderInfo

REQUIRED. The app provider to be marked as default for the specified mime type.

SetDefaultAppProviderForMimeTypeResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

RegistryAPI

App Registry API

The App Registry API is meant to as registry that

contains mappings between mime types and app providers.

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.

Method NameRequest TypeResponse TypeDescription
GetAppProviders GetAppProvidersRequest GetAppProvidersResponse

Returns the app providers that are capable of handling this resource info. MUST return CODE_NOT_FOUND if no providers are available.

AddAppProvider AddAppProviderRequest AddAppProviderResponse

Registers a new app provider to the registry.

ListAppProviders ListAppProvidersRequest ListAppProvidersResponse

Returns a list of the available app providers known by this registry.

ListSupportedMimeTypes ListSupportedMimeTypesRequest ListSupportedMimeTypesResponse

Returns a list of the supported mime types along with the apps which they can be opened with.

GetDefaultAppProviderForMimeType GetDefaultAppProviderForMimeTypeRequest GetDefaultAppProviderForMimeTypeResponse

Returns the default app provider which serves a specified mime type.

SetDefaultAppProviderForMimeType SetDefaultAppProviderForMimeTypeRequest SetDefaultAppProviderForMimeTypeResponse

Sets the default app provider for a specified mime type.

cs3/app/registry/v1beta1/resources.proto

Top

MimeTypeInfo

Represents a mime type and its corresponding file extension.

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

mime_type string

REQUIRED. The mime type.

ext string

REQUIRED. The file extension mapped to this mime type.

app_providers ProviderInfo repeated

REQUIRED. The list of app providers which can open this mime type

name string

OPTIONAL. The friendly name of this mime type.

description string

OPTIONAL. Human-readable information to describe the mime type.

icon string

OPTIONAL. A URI to a static asset which represents the mime type icon.

allow_creation bool

OPTIONAL. Whether the mime type is eligible for file creation in the web UI. Defaults to false, i.e. files with this mime type can be opened but not directly created from the web UI.

default_application string

OPTIONAL. name of the default application to open this mime type

ProviderInfo

Represents the information of the app provider.

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

mime_types string repeated

REQUIRED. The mimetypes handled by this provider.

address string

REQUIRED. The address where the app provider can be reached. For example, localhost:1099.

capability ProviderInfo.Capability

name string

OPTIONAL. A human-readable name of the underlying app.

description string

OPTIONAL. Information to describe the functionalities offered by the underlying app. Meant to be read by humans.

icon string

OPTIONAL. A URI to a static asset which represents the app icon.

desktop_only bool

OPTIONAL. Whether the app can be opened only on desktop

action string

OPTIONAL. The action to be displayed to the user on the context menu. By default this is "Open with".

ProviderInfo.Capability

REQUIRED.

The capability of the underlying app.

NameNumberDescription
CAPABILITY_INVALID 0

CAPABILITY_VIEWER 1

The app is a simple viewer.

CAPABILITY_EDITOR 2

The app is a full editor.

cs3/auth/applications/v1beta1/applications_api.proto

Top

GenerateAppPasswordRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

token_scope GenerateAppPasswordRequest.TokenScopeEntry repeated

OPTIONAL. The scope of the token to be issued. This would be a list of resources with corresponding role-based access scope.

label string

OPTIONAL. A label to be associated with the password.

expiration cs3.types.v1beta1.Timestamp

OPTIONAL. The time when the token will expire.

GenerateAppPasswordRequest.TokenScopeEntry

FieldTypeLabelDescription
key string

value cs3.auth.provider.v1beta1.Scope

GenerateAppPasswordResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

app_password AppPassword

REQUIRED. The generated access password.

GetAppPasswordRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

user cs3.identity.user.v1beta1.UserId

REQUIRED. The user who created the app password.

password string

REQUIRED. The password which has to be retrieved.

GetAppPasswordResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

app_password AppPassword

REQUIRED. The generated access password.

InvalidateAppPasswordRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

password string

REQUIRED. The password which has to be invalidated.

InvalidateAppPasswordResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ListAppPasswordsRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ListAppPasswordsResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

app_passwords AppPassword repeated

REQUIRED. The generated access password.

ApplicationsAPI

Auth Applications API

The Auth Applications API is meant to generate and manage authentication

tokens with specified scopes to be used in third-party applications on behalf

of the user.

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.

Method NameRequest TypeResponse TypeDescription
GenerateAppPassword GenerateAppPasswordRequest GenerateAppPasswordResponse

GenerateAppPassword creates a password with specified scope to be used by third-party applications.

ListAppPasswords ListAppPasswordsRequest ListAppPasswordsResponse

ListAppPasswords lists the application passwords created by a user.

InvalidateAppPassword InvalidateAppPasswordRequest InvalidateAppPasswordResponse

InvalidateAppPassword invalidates a generated password.

GetAppPassword GetAppPasswordRequest GetAppPasswordResponse

GetAppPassword retrieves the password information by the combination of username and password.

cs3/auth/applications/v1beta1/resources.proto

Top

AppPassword

AppPassword stores information about secondary passwords generated by users

to be used with third-party applications.

FieldTypeLabelDescription
password string

REQUIRED. The generated access password.

token_scope AppPassword.TokenScopeEntry repeated

OPTIONAL. The scope of the token to be issued. This would be a list of resources with corresponding role-based access scope.

label string

OPTIONAL. A label to be associated with the password.

user cs3.identity.user.v1beta1.UserId

REQUIRED. The user who created the password.

expiration cs3.types.v1beta1.Timestamp

OPTIONAL. The time when the token will expire.

ctime cs3.types.v1beta1.Timestamp

REQUIRED. The creation time of the password.

utime cs3.types.v1beta1.Timestamp

REQUIRED. The last time the password was used.

AppPassword.TokenScopeEntry

FieldTypeLabelDescription
key string

value cs3.auth.provider.v1beta1.Scope

cs3/auth/provider/v1beta1/provider_api.proto

Top

AuthenticateRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

client_id string

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.

client_secret string

OPTIONAL. The secret of the client.

AuthenticateResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

user cs3.identity.user.v1beta1.User

REQUIRED. The authenticated user.

token_scope AuthenticateResponse.TokenScopeEntry repeated

REQUIRED. The scope of the token to be issued. This would be a list of resources with corresponding role-based access scope.

AuthenticateResponse.TokenScopeEntry

FieldTypeLabelDescription
key string

value Scope

ProviderAPI

Auth Provider API

The Auth Provider API is meant to authenticate a client.

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.

Method NameRequest TypeResponse TypeDescription
Authenticate AuthenticateRequest AuthenticateResponse

Authenticate authenticates a client.

cs3/auth/provider/v1beta1/resources.proto

Top

Scope

Scope defines role-based permissions for various resources.

FieldTypeLabelDescription
resource cs3.types.v1beta1.OpaqueEntry

REQUIRED. The resource embedded in the request of a particular method. It depends on the method, hence is left as opaque.

role Role

REQUIRED. The role associated with the resource.

Role

The role associated with the scope.

NameNumberDescription
ROLE_INVALID 0

Used for invalid roles

ROLE_OWNER 1

Grants owner permissions on a resource

ROLE_LEGACY 2

Provides backwards compatibility

ROLE_VIEWER 3

Grants non-editor role on a resource

ROLE_EDITOR 4

Grants editor permission on a resource, including folders

ROLE_FILE_EDITOR 5

Grants editor permission on a single file

ROLE_COOWNER 6

Grants co-owner permissions on a resource

ROLE_UPLOADER 7

Role with only write permission can use InitiateFileUpload, nothing else

cs3/auth/registry/v1beta1/registry_api.proto

Top

GetAuthProvidersRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

type string

REQUIRED. The type of authentication provider.

GetAuthProvidersResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

providers ProviderInfo repeated

REQUIRED. The auth providers handling the requested auth call.

ListAuthProvidersRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information. TODO(labkode): maybe add some filter?

ListAuthProvidersResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

providers ProviderInfo repeated

REQUIRED. The list of auth providers this registry knows about.

RegistryAPI

Auth Registry API

The Auth Registry API is meant to as registry to obtain

information of available auth providers.

For example, to use OIDC or Kerberos for authentication.

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.

Method NameRequest TypeResponse TypeDescription
GetAuthProviders GetAuthProvidersRequest GetAuthProvidersResponse

Returns the auth provider that is reponsible for the given resource reference. MUST return CODE_NOT_FOUND if the reference does not exist.

ListAuthProviders ListAuthProvidersRequest ListAuthProvidersResponse

Returns a list of the available auth providers known by this registry.

cs3/auth/registry/v1beta1/resources.proto

Top

ProviderInfo

ProviderInfo provides the information about an authentication provider.

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information (containing storage-specific information). For example, additional metadata attached to the resource.

provider_type string

REQUIRED. The storage provider id that will become part of the resource id. For example, if the provider_id is "home", resources obtained from this storage provider will have a resource id like "home:1234".

address string

REQUIRED. The address where the storage provider can be reached. For example, tcp://localhost:1099.

description string

OPTIONAL. Information to describe the functionalities offered by the storage provider. Meant to be read by humans.

cs3/identity/group/v1beta1/group_api.proto

Top

FindGroupsRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

filter string

REQUIRED. The filter to apply.

skip_fetching_members bool

OPTIONAL. Whether to skip fetching members along with the group object.

FindGroupsResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

groups Group repeated

REQUIRED. The groups matching the specified filter.

GetGroupByClaimRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

claim string

REQUIRED. The claim on the basis of which groups will be filtered.

value string

REQUIRED. The value of the claim to find the specific group.

skip_fetching_members bool

OPTIONAL. Whether to skip fetching members along with the group object.

GetGroupByClaimResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

group Group

REQUIRED. The group information.

GetGroupRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

group_id GroupId

REQUIRED. The id of the group.

skip_fetching_members bool

OPTIONAL. Whether to skip fetching members along with the group object.

GetGroupResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

group Group

REQUIRED. The group information.

GetMembersRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

group_id GroupId

REQUIRED. The id of the group.

GetMembersResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

members cs3.identity.user.v1beta1.UserId repeated

REQUIRED. The members of the group.

HasMemberRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

group_id GroupId

REQUIRED. The id of the group.

user_id cs3.identity.user.v1beta1.UserId

REQUIRED. The id of the user to check.

HasMemberResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ok bool

REQUIRED. Tells if the user belongs to the group.

GroupAPI

Provides an API for managing groups.

Method NameRequest TypeResponse TypeDescription
GetGroup GetGroupRequest GetGroupResponse

Gets the information about a group by the group id.

GetGroupByClaim GetGroupByClaimRequest GetGroupByClaimResponse

Gets the information about a group based on a specified claim.

GetMembers GetMembersRequest GetMembersResponse

Gets the members of a group.

HasMember HasMemberRequest HasMemberResponse

Tells if the group has certain member.

FindGroups FindGroupsRequest FindGroupsResponse

Finds groups whose names match the specified filter.

cs3/identity/group/v1beta1/resources.proto

Top

Group

Represents a group of the system.

FieldTypeLabelDescription
id GroupId

group_name string

gid_number int64

mail string

mail_verified bool

display_name string

members cs3.identity.user.v1beta1.UserId repeated

opaque cs3.types.v1beta1.Opaque

GroupId

A GroupId represents a group.

FieldTypeLabelDescription
idp string

REQUIRED. The identity provider for the group.

opaque_id string

REQUIRED. the unique identifier for the group in the scope of the identity provider.

cs3/identity/user/v1beta1/resources.proto

Top

User

Represents a user of the system.

FieldTypeLabelDescription
id UserId

username string

mail string

mail_verified bool

display_name string

groups string repeated

opaque cs3.types.v1beta1.Opaque

uid_number int64

gid_number int64

UserId

A UserId represents a user.

FieldTypeLabelDescription
idp string

REQUIRED. The identity provider for the user.

opaque_id string

REQUIRED. the unique identifier for the user in the scope of the identity provider.

type UserType

REQUIRED. The type of user.

UserType

The type of user.

NameNumberDescription
USER_TYPE_INVALID 0

The user is invalid, for example, is missing primary attributes.

USER_TYPE_PRIMARY 1

A primary user.

USER_TYPE_SECONDARY 2

A secondary user for cases with multiple identities.

USER_TYPE_SERVICE 3

A user catering to specific services.

USER_TYPE_APPLICATION 4

A user to be used by specific applications.

USER_TYPE_GUEST 5

A guest user not affiliated to the IDP.

USER_TYPE_FEDERATED 6

A federated user provided by external IDPs.

USER_TYPE_LIGHTWEIGHT 7

A lightweight user account without access to various major functionalities.

USER_TYPE_SPACE_OWNER 8

A space owner to allow access for public link or content indexing.

cs3/identity/user/v1beta1/user_api.proto

Top

FindUsersRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

filter string

REQUIRED. TODO(labkode): create proper filters for most common searches. The filter to apply.

skip_fetching_user_groups bool

OPTIONAL. Whether to skip fetching user groups along with the user object.

FindUsersResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

users User repeated

REQUIRED. The users matching the specified filter.

GetUserByClaimRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

claim string

REQUIRED. The claim on the basis of which users will be filtered.

value string

REQUIRED. The value of the claim to find the specific user.

skip_fetching_user_groups bool

OPTIONAL. Whether to skip fetching user groups along with the user object.

GetUserByClaimResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

user User

REQUIRED. The user information.

GetUserGroupsRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

user_id UserId

REQUIRED. The id of the user.

GetUserGroupsResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

groups string repeated

REQUIRED. The groups for the user.

GetUserRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

user_id UserId

REQUIRED. The id of the user.

skip_fetching_user_groups bool

OPTIONAL. Whether to skip fetching user groups along with the user object.

GetUserResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

user User

REQUIRED. The user information.

UserAPI

Provides an API for managing users.

Method NameRequest TypeResponse TypeDescription
GetUser GetUserRequest GetUserResponse

Gets the information about a user by the user id.

GetUserByClaim GetUserByClaimRequest GetUserByClaimResponse

Gets the information about a user based on a specified claim.

GetUserGroups GetUserGroupsRequest GetUserGroupsResponse

Gets the groups of a user.

FindUsers FindUsersRequest FindUsersResponse

Finds users by any attribute of the user. TODO(labkode): to define the filters that make more sense.

cs3/ocm/core/v1beta1/ocm_core_api.proto

Top

CreateOCMCoreShareRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

description string

OPTIONAL. Description for the share.

name string

REQUIRED. Name of the resource (file or folder).

resource_id string

REQUIRED. Identifier to identify the resource at the provider side. This is unique per provider.

owner cs3.identity.user.v1beta1.UserId

REQUIRED. Provider specific identifier of the owner of the resource.

sender cs3.identity.user.v1beta1.UserId

REQUIRED. Provider specific identifier of the user that wants to share the resource.

share_with cs3.identity.user.v1beta1.UserId

REQUIRED. Consumer specific identifier of the user or group the provider wants to share the resource with. This is known in advance, for example using the OCM invitation flow. Please note that the consumer service endpoint is known in advance as well, so this is no part of the request body. TODO: this field needs to represent either a user or group in the future, not only a user.

resource_type cs3.storage.provider.v1beta1.ResourceType

REQUIRED. Resource type.

share_type cs3.sharing.ocm.v1beta1.ShareType

REQUIRED. Recipient share type.

expiration cs3.types.v1beta1.Timestamp

OPTIONAL. The expiration time for the OCM share.

protocols cs3.sharing.ocm.v1beta1.Protocol repeated

REQUIRED. The protocols which are used to establish synchronisation, with their access rights. See also cs3/sharing/ocm/v1beta1/resources.proto for how to map this to the OCM share payload.

CreateOCMCoreShareResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

id string

REQUIRED. Unique ID to identify the share at the consumer side.

created cs3.types.v1beta1.Timestamp

REQUIRED.

DeleteOCMCoreShareRequest

FieldTypeLabelDescription
id string

REQUIRED. Unique ID to identify the share at the consumer side.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

DeleteOCMCoreShareResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

UpdateOCMCoreShareRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ocm_share_id string

REQUIRED. Unique ID to identify the share at the consumer side.

description string

OPTIONAL. Description for the share.

share_type cs3.sharing.ocm.v1beta1.ShareType

OPTIONAL. Recipient share type.

expiration cs3.types.v1beta1.Timestamp

OPTIONAL. The expiration time for the OCM share.

protocols cs3.sharing.ocm.v1beta1.Protocol repeated

OPTIONAL. The protocols which are used to establish synchronisation, with their access rights.

UpdateOCMCoreShareResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

OcmCoreAPI

OCM Core API

the OCM Core API is the mapping for the local system of the OCM protocol,

including multi-protocol shares. Implementations are expected to expose

the `/ocm` endpoints according to the OCM API, and in response to those

endpoints implement the following API.

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.

Method NameRequest TypeResponse TypeDescription
CreateOCMCoreShare CreateOCMCoreShareRequest CreateOCMCoreShareResponse

Creates a new OCM share, in response to a call from remote to: https://cs3org.github.io/OCM-API/docs.html?branch=v1.1.0&repo=OCM-API&user=cs3org#/paths/~1shares/post

UpdateOCMCoreShare UpdateOCMCoreShareRequest UpdateOCMCoreShareResponse

Updates an OCM share, in response to a notification from the remote system to: https://cs3org.github.io/OCM-API/docs.html?branch=v1.1.0&repo=OCM-API&user=cs3org#/paths/~1notifications/post

DeleteOCMCoreShare DeleteOCMCoreShareRequest DeleteOCMCoreShareResponse

Deletes an OCM share, in response to a notification from the remote system to: https://cs3org.github.io/OCM-API/docs.html?branch=v1.1.0&repo=OCM-API&user=cs3org#/paths/~1notifications/post

cs3/ocm/invite/v1beta1/invite_api.proto

Top

AcceptInviteRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

invite_token InviteToken

REQUIRED. The token to authenticate with.

remote_user cs3.identity.user.v1beta1.User

REQUIRED. The user who accepted the invite.

AcceptInviteResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

user_id cs3.identity.user.v1beta1.UserId

REQUIRED. The initiator's user id of the workflow.

email string

REQUIRED. The initiator's email of the workflow.

display_name string

REQUIRED. The initiator's display name of the workflow.

DeleteAcceptedUserRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

remote_user_id cs3.identity.user.v1beta1.UserId

REQUIRED. The id of the user.

DeleteAcceptedUserResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

FindAcceptedUsersRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

filter string

REQUIRED. The filter to apply.

FindAcceptedUsersResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

accepted_users cs3.identity.user.v1beta1.User repeated

REQUIRED. The accepted users matching the specified filter.

ForwardInviteRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

invite_token InviteToken

REQUIRED. The token to authenticate with.

origin_system_provider cs3.ocm.provider.v1beta1.ProviderInfo

REQUIRED. The details of the sync'n'share system provider of the user who sent the invite.

ForwardInviteResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

user_id cs3.identity.user.v1beta1.UserId

REQUIRED. The initiator's user id of the workflow.

email string

REQUIRED. The initiator's email of the workflow.

display_name string

REQUIRED. The initiator's display name of the workflow.

GenerateInviteTokenRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

description string

OPTIONAL. The description of the token.

GenerateInviteTokenResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

invite_token InviteToken

REQUIRED. The generated token.

GetAcceptedUserRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

remote_user_id cs3.identity.user.v1beta1.UserId

REQUIRED. The id of the user.

GetAcceptedUserResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

remote_user cs3.identity.user.v1beta1.User

REQUIRED. The user information.

ListInviteTokensRequest

ListInviteTokensResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

invite_tokens InviteToken repeated

REQUIRED. The list of valid tokens.

InviteAPI

Invite API

The Invite API is meant to invite users and groups belonging to other

sync'n'share systems, so that collaboration of resources can be enabled.

The following APIs match the OCM v1.1 spec for the /invite-accepted endpoint.

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.

Method NameRequest TypeResponse TypeDescription
GenerateInviteToken GenerateInviteTokenRequest GenerateInviteTokenResponse

Generates a new token for the user with a validity of 24 hours.

ListInviteTokens ListInviteTokensRequest ListInviteTokensResponse

Lists the valid tokens generated by the user.

ForwardInvite ForwardInviteRequest ForwardInviteResponse

Forwards a received invite to the remote sync'n'share system provider. The remote system SHALL get an `invite-accepted` call as follows: https://cs3org.github.io/OCM-API/docs.html?branch=v1.1.0&repo=OCM-API&user=cs3org#/paths/~1invite-accepted/post MUST return CODE_NOT_FOUND if the token does not exist. MUST return CODE_INVALID_ARGUMENT if the token expired. MUST return CODE_ALREADY_EXISTS if the user already accepted an invite. MUST return CODE_PERMISSION_DENIED if the remote service is not trusted to accept invitations.

AcceptInvite AcceptInviteRequest AcceptInviteResponse

Completes an invitation acceptance. MUST return CODE_NOT_FOUND if the token does not exist. MUST return CODE_INVALID_ARGUMENT if the token expired. MUST return CODE_ALREADY_EXISTS if the user already accepted an invite.

GetAcceptedUser GetAcceptedUserRequest GetAcceptedUserResponse

Retrieves details about a remote user who has accepted an invite to share. MUST return CODE_NOT_FOUND if the user does not exist.

FindAcceptedUsers FindAcceptedUsersRequest FindAcceptedUsersResponse

Finds users who accepted invite tokens by their attributes.

DeleteAcceptedUser DeleteAcceptedUserRequest DeleteAcceptedUserResponse

Delete a previously accepted remote user, that is unfriend that user. MUST return CODE_NOT_FOUND if the user does not exist.

cs3/ocm/invite/v1beta1/resources.proto

Top

InviteToken

InviteToken is used to invite users and groups from other sync'n'share

systems to collaborate on resources.

FieldTypeLabelDescription
token string

REQUIRED. Unique ID associated with an InviteToken.

user_id cs3.identity.user.v1beta1.UserId

REQUIRED. The user who created the token.

expiration cs3.types.v1beta1.Timestamp

OPTIONAL. The time when the token will expire.

description string

OPTIONAL. User-defined description to be forwarded to the invitees.

cs3/ocm/provider/v1beta1/provider_api.proto

Top

GetInfoByDomainRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

domain string

REQUIRED. The domain of the system provider.

GetInfoByDomainResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

provider_info ProviderInfo

REQUIRED. The info of the provider

IsProviderAllowedRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

provider ProviderInfo

REQUIRED. The provider that we need to check against the list of verified mesh providers.

IsProviderAllowedResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ListAllProvidersRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ListAllProvidersResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

providers ProviderInfo repeated

REQUIRED. The share.

ProviderAPI

OCM Auth Provider API

The Auth Provider API is meant to authenticate a sync'n'share provider regsistered in the mesh.

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.

Method NameRequest TypeResponse TypeDescription
IsProviderAllowed IsProviderAllowedRequest IsProviderAllowedResponse

Check if a given system provider is registered in the mesh or not. MUST return CODE_UNAUTHENTICATED if the system is not registered

GetInfoByDomain GetInfoByDomainRequest GetInfoByDomainResponse

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

ListAllProviders ListAllProvidersRequest ListAllProvidersResponse

Get the information of all the providers registered in the mesh.

cs3/ocm/provider/v1beta1/resources.proto

Top

ProviderInfo

Details of the sync'n'share system provider.

FieldTypeLabelDescription
name string

REQUIRED. The name of the provider.

full_name string

REQUIRED. The full name of the provider.

description string

REQUIRED. A description of the provider.

organization string

REQUIRED. The organization to which the provider belongs.

domain string

REQUIRED. The domain of the sync'n'share provider.

homepage string

REQUIRED. The homepage of the provider.

email string

REQUIRED. The email at which the provider can be reached.

services Service repeated

REQUIRED. The list of services provided by the provider.

properties ProviderInfo.PropertiesEntry repeated

OPTIONAL. Additional properties about the service.

ProviderInfo.PropertiesEntry

FieldTypeLabelDescription
key string

value string

Service

The services offered by sync'n'share system providers.

FieldTypeLabelDescription
host string

REQUIRED. The URL at which the service is hosted.

endpoint ServiceEndpoint

REQUIRED. The primary endpoint of the service.

api_version string

REQUIRED. The API version of the provided service.

additional_endpoints ServiceEndpoint repeated

OPTIONAL. Additional endpoints at which the service is exposed.

ServiceEndpoint

The endpoints exposed by particular services.

FieldTypeLabelDescription
type ServiceType

REQUIRED. The type of service.

name string

REQUIRED. The name of the service.

path string

REQUIRED. The path at which the service is hosted.

is_monitored bool

OPTIONAL. Whether the service is monitored.

properties ServiceEndpoint.PropertiesEntry repeated

OPTIONAL. Additional properties about the service.

ServiceEndpoint.PropertiesEntry

FieldTypeLabelDescription
key string

value string

ServiceType

Identifier for various types of services offered by sync'n'share system providers.

FieldTypeLabelDescription
name string

REQUIRED The name of the service type.

description string

REQUIRED The description of the service type.

cs3/sharing/collaboration/v1beta1/collaboration_api.proto

Top

CreateShareRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

resource_info cs3.storage.provider.v1beta1.ResourceInfo

REQUIRED. The information of the resource to be shared.

grant ShareGrant

REQUIRED. The share grant for the share.

CreateShareResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

share Share

REQUIRED. The created share.

GetReceivedShareRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref ShareReference

REQUIRED. The reference of the received share.

GetReceivedShareResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

share ReceivedShare

REQUIRED. The share.

GetShareRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref ShareReference

REQUIRED. The reference to which the action should be performed.

GetShareResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

share Share

REQUIRED. The share.

ListReceivedSharesRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

filters Filter repeated

OPTIONAL. The list of filters to apply if any.

page_size int32

OPTIONAL. Clients use this field to specify the maximum number of results to be returned by the server. The server may further constrain the maximum number of results returned in a single page. If the page_size is 0, the server will decide the number of results to be returned. see https://cloud.google.com/apis/design/design_patterns#list_pagination

page_token string

OPTIONAL. The client uses this field to request a specific page of the list results.

ListReceivedSharesResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

shares ReceivedShare repeated

REQUIRED. The list of received shares.

next_page_token string

OPTIONAL. This field represents the pagination token to retrieve the next page of results. If the value is "", it means no further results for the request. see https://cloud.google.com/apis/design/design_patterns#list_pagination

ListSharesRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

filters Filter repeated

OPTIONAL. The list of filters to apply if any.

page_size int32

OPTIONAL. Clients use this field to specify the maximum number of results to be returned by the server. The server may further constrain the maximum number of results returned in a single page. If the page_size is 0, the server will decide the number of results to be returned. see https://cloud.google.com/apis/design/design_patterns#list_pagination

page_token string

OPTIONAL. The client uses this field to request a specific page of the list results.

ListSharesResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

shares Share repeated

REQUIRED. The list of shares.

next_page_token string

OPTIONAL. This field represents the pagination token to retrieve the next page of results. If the value is "", it means no further results for the request. see https://cloud.google.com/apis/design/design_patterns#list_pagination

RemoveShareRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref ShareReference

REQUIRED. The reference to which the action should be performed.

RemoveShareResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

UpdateReceivedShareRequest

TODO(labkode): clean up display_name ? we'll use storage links for that.

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

share ReceivedShare

REQUIRED. The received share to update.

update_mask google.protobuf.FieldMask

The update mask applies to the resource. For the `FieldMask` definition, see https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#fieldmask

UpdateReceivedShareResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

share ReceivedShare

REQUIRED. The updated share.

UpdateShareRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref ShareReference

REQUIRED. Deprecated use the share and update_mask attribute.

field UpdateShareRequest.UpdateField

REQUIRED. Deprecated use the share and update_mask attribute.

update_mask google.protobuf.FieldMask

The update mask applies to the resource. For the `FieldMask` definition, see https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#fieldmask

share Share

REQUIRED. The share containing the new data

UpdateShareRequest.UpdateField

REQUIRED.

FieldTypeLabelDescription
permissions SharePermissions

Update the permissions.

display_name string

Update the display name.

UpdateShareResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

share Share

REQUIRED. The updated share.

CollaborationAPI

User Share Provider API

The User Share Provider API is meant to manipulate share

resources for a specific share type (user, group, ocm, ...)

from the perspective of the creator or the share and

from the perspective of the receiver of the share.

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.

Method NameRequest TypeResponse TypeDescription
CreateShare CreateShareRequest CreateShareResponse

Creates a new share. MUST return CODE_NOT_FOUND if the resource reference does not exist. MUST return CODE_LOCKED if the resource reference already locked. MUST return CODE_ALREADY_EXISTS if the share already exists for the 4-tuple consisting of (owner, shared_resource, grantee). New shares MUST be created in the state SHARE_STATE_PENDING.

RemoveShare RemoveShareRequest RemoveShareResponse

Removes a share. MUST return CODE_NOT_FOUND if the share reference does not exist.

GetShare GetShareRequest GetShareResponse

Gets share information for a single share. MUST return CODE_NOT_FOUND if the share reference does not exist.

ListShares ListSharesRequest ListSharesResponse

List the shares the authenticated principal has created, both as owner and creator. If a filter is specified, only shares satisfying the filter MUST be returned.

UpdateShare UpdateShareRequest UpdateShareResponse

Updates a share. MUST return CODE_NOT_FOUND if the share reference does not exist.

ListReceivedShares ListReceivedSharesRequest ListReceivedSharesResponse

List all shares the authenticated principal has received.

UpdateReceivedShare UpdateReceivedShareRequest UpdateReceivedShareResponse

Update the received share to change the share state or the display name. MUST return CODE_NOT_FOUND if the share reference does not exist.

GetReceivedShare GetReceivedShareRequest GetReceivedShareResponse

Get the information for the given received share reference. MUST return CODE_NOT_FOUND if the received share reference does not exist.

cs3/sharing/collaboration/v1beta1/resources.proto

Top

Filter

Represents a filter to apply to the request.

FieldTypeLabelDescription
type Filter.Type

REQUIRED.

resource_id cs3.storage.provider.v1beta1.ResourceId

owner cs3.identity.user.v1beta1.UserId

creator cs3.identity.user.v1beta1.UserId

grantee_type cs3.storage.provider.v1beta1.GranteeType

space_id string

state ShareState

ReceivedShare

A received share is the share that a grantee will receive.

It expands the original share by adding state to the share,

a display name from the perspective of the grantee and a

resource mount point in case the share will be mounted

in a storage provider.

FieldTypeLabelDescription
share Share

REQUIRED.

state ShareState

REQUIRED. The state of the share.

mount_point cs3.storage.provider.v1beta1.Reference

REQUIRED. The mount point of the share.

hidden bool

Optional. Hide share, default false

Share

Shares are relationships between a resource owner

(usually the authenticated user) who grants permissions to a recipient (grantee)

on a specified resource (resource_id). UserShares represents both user and groups.

FieldTypeLabelDescription
id ShareId

REQUIRED. Opaque unique identifier of the share.

resource_id cs3.storage.provider.v1beta1.ResourceId

REQUIRED. Unique identifier of the shared resource.

permissions SharePermissions

REQUIRED. Permissions for the grantee to use the resource.

grantee cs3.storage.provider.v1beta1.Grantee

REQUIRED. The receiver of the share, like a user, group ...

owner cs3.identity.user.v1beta1.UserId

REQUIRED. Uniquely identifies the owner of the share (the resource owner at the time of creating the share). In case the ownership of the underlying resource changes the share owner field MAY change to reflect the change of ownsership.

creator cs3.identity.user.v1beta1.UserId

REQUIRED. Uniquely identifies a principal who initiates the share creation. A creator can create shares on behalf of the owner (because of re-sharing, because belonging to special groups, ...). Creator and owner often result in being the same principal.

ctime cs3.types.v1beta1.Timestamp

REQUIRED. Creation time of the share.

mtime cs3.types.v1beta1.Timestamp

REQUIRED. Last modification time of the share.

expiration cs3.types.v1beta1.Timestamp

Optional. The expiration time of the share.

ShareGrant

A share grant specifies the share permissions

for a grantee.

FieldTypeLabelDescription
grantee cs3.storage.provider.v1beta1.Grantee

REQUIRED. The grantee of the grant.

permissions SharePermissions

REQUIRED. The share permissions for the grant.

expiration cs3.types.v1beta1.Timestamp

OPTIONAL Expiration of the grant.

ShareId

A share id identifies uniquely a // share in the share provider namespace.

A ShareId MUST be unique inside the share provider.

FieldTypeLabelDescription
opaque_id string

REQUIRED. The internal id used by service implementor to uniquely Collaboration the share in the internal implementation of the service.

ShareKey

Uniquely identifies a share in the share provider.

A share MUST be uniquely identify by four (4) elements:

1) The share provider id

2) The owner of the share

3) The resource id

4) The grantee for the share

This 4-tuple MUST be unique.

For example, owner Alice shares the resource /home/docs with id

home:1234 to an user named Bob. The 4-tuple will consist of

1) The share provider id = "user"

2) The owner of the share = "Alice"

3) The resource id = "home:1234"

4) The grantee for the share = Grantee("type" = "user", "" => "Bob")

FieldTypeLabelDescription
owner cs3.identity.user.v1beta1.UserId

REQUIRED.

resource_id cs3.storage.provider.v1beta1.ResourceId

REQUIRED.

grantee cs3.storage.provider.v1beta1.Grantee

REQUIRED.

SharePermissions

The permissions for a share.

FieldTypeLabelDescription
permissions cs3.storage.provider.v1beta1.ResourcePermissions

TODO(labkode): additional permissions for shares like re-sharing and denying

ShareReference

The mechanism to identify a share

in the share provider namespace.

FieldTypeLabelDescription
id ShareId

The id of the share.

key ShareKey

The combination of fields that make the share unique.

Filter.Type

The filter to apply.

NameNumberDescription
TYPE_INVALID 0

TYPE_NO 1

TYPE_RESOURCE_ID 2

TYPE_OWNER 3

TYPE_CREATOR 4

TYPE_GRANTEE_TYPE 5

TYPE_EXCLUDE_DENIALS 6

TYPE_SPACE_ID 7

TYPE_STATE 8

ShareState

The state of the share.

NameNumberDescription
SHARE_STATE_INVALID 0

The share is no longer valid, for example, the share expired.

SHARE_STATE_PENDING 1

New shares MUST be created in the SHARE_STATE_PENDING state. This state means the share is pending to be accepted or rejected by the recipient of the share.

SHARE_STATE_ACCEPTED 2

The recipient of the share has accepted the share.

SHARE_STATE_REJECTED 3

The recipient of the share has rejected the share. Do not means the share is removed, the recipient MAY change the state to accepted or pending.

Top

CreatePublicShareRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

resource_info cs3.storage.provider.v1beta1.ResourceInfo

REQUIRED. The unique identifier for the shared storage resource.

grant Grant

REQUIRED. The restrictions to apply to the share.

description string

OPTIONAL The description to add to the share.

internal bool

OPTIONAL Indicates a share used for internal usage, not exposed by a ListPublicShares.

notify_uploads bool

OPTIONAL Whether to notify the owner of a share when a file is uploaded to it.

notify_uploads_extra_recipients string

OPTIONAL Comma-separated list of extra email addresses to notify when a file is uploaded to the share.

CreatePublicShareResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

share PublicShare

REQUIRED. The created share.

GetPublicShareByTokenRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

token string

REQUIRED. The unlisted token to identify the public share.

authentication PublicShareAuthentication

OPTIONAL. The public link can require authentication.

sign bool

OPTIONAL. If a signature should be included in the share.

GetPublicShareByTokenResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

share PublicShare

REQUIRED. The share.

password_hash string

Deprecated. OPTIONAL. The share password hash.

Fields with deprecated option

Name Option
password_hash

true

GetPublicShareRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref PublicShareReference

REQUIRED. The reference to which the action should be performed.

sign bool

OPTIONAL. If a signature should be included in the share.

GetPublicShareResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

share PublicShare

REQUIRED. The share.

ListPublicSharesRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

filters ListPublicSharesRequest.Filter repeated

OPTIONAL. The list of filters to apply if any.

sign bool

OPTIONAL. If a signature should be included in the share.

page_size int32

OPTIONAL. Clients use this field to specify the maximum number of results to be returned by the server. The server may further constrain the maximum number of results returned in a single page. If the page_size is 0, the server will decide the number of results to be returned. see https://cloud.google.com/apis/design/design_patterns#list_pagination

page_token string

OPTIONAL. The client uses this field to request a specific page of the list results.

ListPublicSharesRequest.Filter

REQUIRED.

represents a filter to apply to the request.

FieldTypeLabelDescription
type ListPublicSharesRequest.Filter.Type

resource_id cs3.storage.provider.v1beta1.ResourceId

owner cs3.identity.user.v1beta1.UserId

creator cs3.identity.user.v1beta1.UserId

ListPublicSharesResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

share PublicShare repeated

REQUIRED. The list of shares.

next_page_token string

OPTIONAL. This field represents the pagination token to retrieve the next page of results. If the value is "", it means no further results for the request. see https://cloud.google.com/apis/design/design_patterns#list_pagination

RemovePublicShareRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref PublicShareReference

REQUIRED. The reference to which the action should be performed.

RemovePublicShareResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

UpdatePublicShareRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information. REQUIRED.

ref PublicShareReference

REQUIRED. The reference to the public share. Available fields to update.

update UpdatePublicShareRequest.Update

UpdatePublicShareRequest.Update

REQUIRED.

FieldTypeLabelDescription
type UpdatePublicShareRequest.Update.Type

REQUIRED. Defines the field to update.

grant Grant

REQUIRED. Contains the field that will be updated.

display_name string

OPTIONAL Defines the public link display name.

description string

OPTIONAL Defines the public link description.

notify_uploads bool

OPTIONAL Whether to notify the owner of a share when a file is uploaded to it.

notify_uploads_extra_recipients string

OPTIONAL Comma-separated list of extra email addresses to notify when a file is uploaded to the share.

UpdatePublicShareResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

share PublicShare

REQUIRED. The updated public share.

ListPublicSharesRequest.Filter.Type

REQUIRED.

NameNumberDescription
TYPE_INVALID 0

TYPE_RESOURCE_ID 1

TYPE_OWNER 2

TYPE_CREATOR 3

UpdatePublicShareRequest.Update.Type

REQUIRED.

NameNumberDescription
TYPE_INVALID 0

TYPE_PERMISSIONS 1

TYPE_PASSWORD 2

TYPE_EXPIRATION 3

TYPE_DISPLAYNAME 4

TYPE_DESCRIPTION 5

TYPE_NOTIFYUPLOADS 6

TYPE_NOTIFYUPLOADSEXTRARECIPIENTS 7

LinkAPI

PublicShare Provider API

The Public Share Provider API is meant to manipulate public shares

also called public links.

Access to public shares can be limitted by a password. The share

provider must store this password in a secure manner e.g. hashed

with the bcrypt algorithm.

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.

Method NameRequest TypeResponse TypeDescription
CreatePublicShare CreatePublicShareRequest CreatePublicShareResponse

Creates a new share. MUST return CODE_NOT_FOUND if the resource reference does not exist. MUST return CODE_ALREADY_EXISTS if the share already exists for the 4-tuple consisting of (owner, shared_resource, grantee). New shares MUST be created in the state SHARE_STATE_PENDING.

RemovePublicShare RemovePublicShareRequest RemovePublicShareResponse

Removes a share. MUST return CODE_NOT_FOUND if the share reference does not exist.

GetPublicShare GetPublicShareRequest GetPublicShareResponse

Gets share information for a single share. MUST return CODE_NOT_FOUND if the share reference does not exist.

GetPublicShareByToken GetPublicShareByTokenRequest GetPublicShareByTokenResponse

Gets share information for a single share by its unlisted token. MUST return CODE_NOT_FOUND if the share does not exist.

ListPublicShares ListPublicSharesRequest ListPublicSharesResponse

List the shares the authenticated principal has created, both as owner and creator. If a filter is specified, only shares satisfying the filter MUST be returned.

UpdatePublicShare UpdatePublicShareRequest UpdatePublicShareResponse

Updates a share. MUST return CODE_NOT_FOUND if the share reference does not exist.

cs3/sharing/link/v1beta1/resources.proto

Top

Grant

Defines the restrictions for the public share.

FieldTypeLabelDescription
permissions PublicSharePermissions

REQUIRED. The permissions for the share.

password string

OPTIONAL. A password to protect the access to the public share.

expiration cs3.types.v1beta1.Timestamp

OPTIONAL. An expiration date to protect the access to the public share.

PublicShare

Public share are relationships between a resource owner

(usually the authenticated user) who grants permissions to a recipient (grantee)

on a specified resource (resource_id). UserShares represents both user and groups.

TODO(labkode): do we need to have resource_type stored on the share?

This is not needed if when getting the shares a stat operation is launched against the

the storage provider.

FieldTypeLabelDescription
id PublicShareId

REQUIRED. Opaque unique identifier of the share.

token string

REQUIRED. The unlisted token to give public access to the public share.

resource_id cs3.storage.provider.v1beta1.ResourceId

REQUIRED. Unique identifier of the shared resource.

permissions PublicSharePermissions

REQUIRED. Permissions for the grantee to use the resource.

owner cs3.identity.user.v1beta1.UserId

REQUIRED. Uniquely identifies the owner of the share (the resource owner at the time of creating the share). In case the ownership of the underlying resource changes the share owner field MAY change to reflect the change of ownsership.

creator cs3.identity.user.v1beta1.UserId

REQUIRED. Uniquely identifies a principal who initiates the share creation. A creator can create shares on behalf of the owner (because of re-sharing, because belonging to special groups, ...). Creator and owner often result in being the same principal.

ctime cs3.types.v1beta1.Timestamp

REQUIRED. Creation time of the share.

mtime cs3.types.v1beta1.Timestamp

REQUIRED. Last modification time of the share.

password_protected bool

REQUIRED. Determines if the public share is password protected or not.

expiration cs3.types.v1beta1.Timestamp

OPTIONAL. The expiration time for the public share.

display_name string

OPTIONAL. Display name for the shared resource (such as file, directory basename or any user defined name). The display name MAY be different than the actual resource basename. This field is only useful for informational purposes, like for example, setting the window title in a public share HTML page.

signature ShareSignature

OPTIONAL. A time constrained token with which GetPublicSharebyToken requests can be authenticated.

quicklink bool

OPTIONAL A bool value indicating if the link is the quicklink the server will enforce a maximum of 1 quicklink per resource

description string

OPTIONAL Description of the share.

notify_uploads bool

OPTIONAL Whether to notify the owner of a share when a file is uploaded to it.

notify_uploads_extra_recipients string

OPTIONAL Comma-separated list of extra email addresses to notify when a file is uploaded to the share.

PublicShareAuthentication

The mechanism to authenticate a request to

GetPublicShareByToken.

FieldTypeLabelDescription
password string

The password of the share.

signature ShareSignature

The signature issued by GetPublicShareByToken.

PublicShareId

A share id identifies uniquely a // share in the share provider namespace.

A ShareId MUST be unique inside the share provider.

FieldTypeLabelDescription
opaque_id string

REQUIRED. The internal id used by service implementor to uniquely identity the share in the internal implementation of the service.

PublicSharePermissions

The permissions for a share.

FieldTypeLabelDescription
permissions cs3.storage.provider.v1beta1.ResourcePermissions

TODO(labkode): additional permissions for shares like re-sharing

PublicShareReference

The mechanism to identify a share

in the share provider namespace.

FieldTypeLabelDescription
id PublicShareId

The id of the share.

token string

The token to identify the public share.

ShareSignature

A time constrained token which can be used to

authenticate link share requests.

FieldTypeLabelDescription
signature string

REQUIRED. The signature value.

signature_expiration cs3.types.v1beta1.Timestamp

REQUIRED. The time until the signature becomes invalid.

cs3/sharing/ocm/v1beta1/ocm_api.proto

Top

CreateOCMShareRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

resource_id cs3.storage.provider.v1beta1.ResourceId

REQUIRED. The unique identifier for the shared storage resource.

grantee cs3.storage.provider.v1beta1.Grantee

REQUIRED. The grantee for the share.

recipient_mesh_provider cs3.ocm.provider.v1beta1.ProviderInfo

REQUIRED. The details of the recipient user's mesh provider.

access_methods AccessMethod repeated

REQUIRED.

expiration cs3.types.v1beta1.Timestamp

OPTIONAL. The expiration time for the ocm share.

CreateOCMShareResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

share Share

REQUIRED. The created share.

recipient_display_name string

OPTIONAL. Display name of the recipient of the share.

GetOCMShareByTokenRequest

FieldTypeLabelDescription
token string

REQUIRED. The unlisted token to identify the public share.

GetOCMShareByTokenResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

share Share

REQUIRED. The share.

GetOCMShareRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref ShareReference

REQUIRED. The reference to which the action should be performed.

GetOCMShareResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

share Share

REQUIRED. The share.

GetReceivedOCMShareRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref ShareReference

REQUIRED. The reference of the received share.

GetReceivedOCMShareResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

share ReceivedShare

REQUIRED. The share.

ListOCMSharesRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

filters ListOCMSharesRequest.Filter repeated

OPTIONAL. The list of filters to apply if any.

page_size int32

OPTIONAL. Clients use this field to specify the maximum number of results to be returned by the server. The server may further constrain the maximum number of results returned in a single page. If the page_size is 0, the server will decide the number of results to be returned. see https://cloud.google.com/apis/design/design_patterns#list_pagination

page_token string

OPTIONAL. The client uses this field to request a specific page of the list results.

ListOCMSharesRequest.Filter

REQUIRED.

represents a filter to apply to the request.

FieldTypeLabelDescription
type ListOCMSharesRequest.Filter.Type

REQUIRED.

resource_id cs3.storage.provider.v1beta1.ResourceId

owner cs3.identity.user.v1beta1.UserId

creator cs3.identity.user.v1beta1.UserId

ListOCMSharesResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

shares Share repeated

REQUIRED. The list of shares.

next_page_token string

OPTIONAL. This field represents the pagination token to retrieve the next page of results. If the value is "", it means no further results for the request. see https://cloud.google.com/apis/design/design_patterns#list_pagination

ListReceivedOCMSharesRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

page_size int32

OPTIONAL. Clients use this field to specify the maximum number of results to be returned by the server. The server may further constrain the maximum number of results returned in a single page. If the page_size is 0, the server will decide the number of results to be returned. see https://cloud.google.com/apis/design/design_patterns#list_pagination

page_token string

OPTIONAL. The client uses this field to request a specific page of the list results.

ListReceivedOCMSharesResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

shares ReceivedShare repeated

REQUIRED. The list of received shares.

next_page_token string

OPTIONAL. This field represents the pagination token to retrieve the next page of results. If the value is "", it means no further results for the request. see https://cloud.google.com/apis/design/design_patterns#list_pagination

RemoveOCMShareRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref ShareReference

REQUIRED. The reference to which the action should be performed.

RemoveOCMShareResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

UpdateOCMShareRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref ShareReference

REQUIRED.

field UpdateOCMShareRequest.UpdateField repeated

UpdateOCMShareRequest.UpdateField

REQUIRED.

FieldTypeLabelDescription
expiration cs3.types.v1beta1.Timestamp

Update the expiration.

access_methods AccessMethod

Update access methods.

UpdateOCMShareResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

UpdateReceivedOCMShareRequest

TODO(labkode): clean up display_name ? we'll use storage links for that.

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

share ReceivedShare

REQUIRED. The received share to update.

update_mask google.protobuf.FieldMask

The update mask applies to the resource. For the `FieldMask` definition, see https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#fieldmask

UpdateReceivedOCMShareResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ListOCMSharesRequest.Filter.Type

REQUIRED.

The filter to apply.

NameNumberDescription
TYPE_INVALID 0

TYPE_NO 1

TYPE_RESOURCE_ID 2

TYPE_OWNER 3

TYPE_CREATOR 4

TYPE_OWNER_PROVIDER 5

TYPE_CREATOR_PROVIDER 6

OcmAPI

OCM Share Provider API

The OCM Share Provider API is meant to manipulate share

resources from the perspective of the creator or the share and

from the perspective of the receiver of the share.

The following APIs match the OCM v1.1 spec including multi-protocol shares.

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.

Method NameRequest TypeResponse TypeDescription
CreateOCMShare CreateOCMShareRequest CreateOCMShareResponse

Creates a new ocm share. MUST return CODE_NOT_FOUND if the resource reference does not exist. MUST return CODE_ALREADY_EXISTS if the share already exists for the 4-tuple consisting of (owner, shared_resource, grantee). New shares MUST be created in the state SHARE_STATE_PENDING, and MUST be sent to the remote system using the OCM API at: https://cs3org.github.io/OCM-API/docs.html?branch=v1.1.0&repo=OCM-API&user=cs3org#/paths/~1shares/post

RemoveOCMShare RemoveOCMShareRequest RemoveOCMShareResponse

Removes a share. MUST return CODE_NOT_FOUND if the share reference does not exist. This action SHALL be notified to the remote system using the OCM API at: https://cs3org.github.io/OCM-API/docs.html?branch=v1.1.0&repo=OCM-API&user=cs3org#/paths/~1notifications/post

GetOCMShare GetOCMShareRequest GetOCMShareResponse

Gets share information for a single share. MUST return CODE_NOT_FOUND if the share reference does not exist.

GetOCMShareByToken GetOCMShareByTokenRequest GetOCMShareByTokenResponse

Gets share information for a single share by its unlisted token. MUST return CODE_NOT_FOUND if the share does not exist.

ListOCMShares ListOCMSharesRequest ListOCMSharesResponse

List the shares the authenticated principal has created, both as owner and creator. If a filter is specified, only shares satisfying the filter MUST be returned.

UpdateOCMShare UpdateOCMShareRequest UpdateOCMShareResponse

Updates a share. MUST return CODE_NOT_FOUND if the share reference does not exist. This action SHALL be notified to the remote system using the OCM API at: https://cs3org.github.io/OCM-API/docs.html?branch=v1.1.0&repo=OCM-API&user=cs3org#/paths/~1notifications/post

ListReceivedOCMShares ListReceivedOCMSharesRequest ListReceivedOCMSharesResponse

List all shares the authenticated principal has received.

UpdateReceivedOCMShare UpdateReceivedOCMShareRequest UpdateReceivedOCMShareResponse

Update the received share to change the share state or the display name. MUST return CODE_NOT_FOUND if the share reference does not exist.

GetReceivedOCMShare GetReceivedOCMShareRequest GetReceivedOCMShareResponse

Get the information for the given received share reference. MUST return CODE_NOT_FOUND if the received share reference does not exist.

cs3/sharing/ocm/v1beta1/resources.proto

Top

AccessMethod

Defines how the recipient accesses an incoming remote OCM share.

FieldTypeLabelDescription
webdav_options WebDAVAccessMethod

Options for the WebDAV access method.

webapp_options WebappAccessMethod

Options for the Webapp access method.

transfer_options TransferAccessMethod

Options for the Transfer access method.

generic_options cs3.types.v1beta1.Opaque

Options for a generic transfer method. Used to implement future access methods.

Protocol

The protocol which is used to give access to a remote OCM user.

FieldTypeLabelDescription
webdav_options WebDAVProtocol

Options for WebDAV protocol.

webapp_options WebappProtocol

Options for Webapp protocol.

transfer_options TransferProtocol

Options for transfer protocol.

generic_options cs3.types.v1beta1.Opaque

Options for a generic protocol. Used to implement future protocols in the OCM specs.

ReceivedShare

A received share is the share that a grantee will receive.

FieldTypeLabelDescription
id ShareId

REQUIRED. Opaque unique identifier of the share.

name string

REQUIRED. Name of the shared resource.

remote_share_id string

REQUIRED. Identifier to identify the shared resource at the provider side. This is unique per provider such that if the same resource is shared twice, this will not be repeated. This correspond to the `providerId` in the OCM API specs.

grantee cs3.storage.provider.v1beta1.Grantee

REQUIRED. The receiver of the share, like a user, group ...

owner cs3.identity.user.v1beta1.UserId

REQUIRED. Uniquely identifies the owner of the share (the resource owner at the time of creating the share). In case the ownership of the underlying resource changes the share owner field MAY change to reflect the change of ownsership.

creator cs3.identity.user.v1beta1.UserId

REQUIRED. Uniquely identifies a principal who initiates the share creation. A creator can create shares on behalf of the owner (because of re-sharing, because belonging to special groups, ...). Creator and owner often result in being the same principal.

ctime cs3.types.v1beta1.Timestamp

REQUIRED. Creation time of the share.

mtime cs3.types.v1beta1.Timestamp

REQUIRED. Last modification time of the share.

expiration cs3.types.v1beta1.Timestamp

OPTIONAL. The expiration time for the ocm share.

share_type ShareType

REQUIRED. Recipient share type.

protocols Protocol repeated

REQUIRED. List of protocols offered for this share. In the OCM specifications, this corresponds to the `protocol` property, to maintain backwards compatibility with OCM v1 where only a single protocol was implemented. Furthermore, `protocol.name` MAY be set to `multi` and `protocol.options` MAY be left empty in the OCM share payload, in order to use the `protocol.webdav` and similar properties.

state ShareState

REQUIRED. The state of the share.

opaque cs3.types.v1beta1.Opaque

OPTIONAL.

resource_type cs3.storage.provider.v1beta1.ResourceType

REQUIRED. Resource type.

Share

Shares are relationships between a resource owner

(usually the authenticated user) who grants permissions to a recipient

(grantee) on a specified resource (resource_id). UserShares represents both

user and groups.

FieldTypeLabelDescription
id ShareId

REQUIRED. Opaque unique identifier of the share.

resource_id cs3.storage.provider.v1beta1.ResourceId

REQUIRED. Unique identifier of the shared resource.

name string

REQUIRED. Name of the shared resource.

token string

REQUIRED. The unlisted token to give access to the ocm share.

grantee cs3.storage.provider.v1beta1.Grantee

REQUIRED. The receiver of the share, like a user, group ...

owner cs3.identity.user.v1beta1.UserId

REQUIRED. Uniquely identifies the owner of the share (the resource owner at the time of creating the share). In case the ownership of the underlying resource changes the share owner field MAY change to reflect the change of ownsership.

creator cs3.identity.user.v1beta1.UserId

REQUIRED. Uniquely identifies a principal who initiates the share creation. A creator can create shares on behalf of the owner (because of re-sharing, because belonging to special groups, ...). Creator and owner often result in being the same principal.

ctime cs3.types.v1beta1.Timestamp

REQUIRED. Creation time of the share.

mtime cs3.types.v1beta1.Timestamp

REQUIRED. Last modification time of the share.

expiration cs3.types.v1beta1.Timestamp

OPTIONAL. The expiration time for the OCM share.

share_type ShareType

REQUIRED. Recipient share type.

access_methods AccessMethod repeated

REQUIRED.

opaque cs3.types.v1beta1.Opaque

OPTIONAL.

ShareGrant

A share grant specifies the share permissions

for a grantee.

FieldTypeLabelDescription
grantee cs3.storage.provider.v1beta1.Grantee

REQUIRED. The grantee of the grant.

permissions SharePermissions

REQUIRED. The share permissions for the grant.

ShareId

A share id identifies uniquely a share in the share provider namespace.

A ShareId MUST be unique inside the share provider.

FieldTypeLabelDescription
opaque_id string

REQUIRED. The internal id used by service implementor to uniquely identify the share in the internal implementation of the service. In the OCM specifications, this corresponds to the `providerId`.

ShareKey

Uniquely identifies a share in the share provider.

A share MUST be uniquely identify by four (4) elements:

1) The share provider id

2) The owner of the share

3) The resource id

4) The grantee for the share

This 4-tuple MUST be unique.

For example, owner Alice shares the resource /home/docs with id

home:1234 to an user named Bob. The 4-tuple will consist of

1) The share provider id = "user"

2) The owner of the share = "Alice"

3) The resource id = "home:1234"

4) The grantee for the share = Grantee("type" = "user", "" => "Bob")

FieldTypeLabelDescription
owner cs3.identity.user.v1beta1.UserId

REQUIRED.

resource_id cs3.storage.provider.v1beta1.ResourceId

REQUIRED.

grantee cs3.storage.provider.v1beta1.Grantee

REQUIRED.

SharePermissions

The permissions for a share.

FieldTypeLabelDescription
permissions cs3.storage.provider.v1beta1.ResourcePermissions

reshare bool

ShareReference

The mechanism to identify a share

in the share provider namespace.

FieldTypeLabelDescription
id ShareId

The id of the share.

key ShareKey

The combination of fields that make the share unique.

token string

The token of the share.

TransferAccessMethod

Defines the options for the Transfer access method.

FieldTypeLabelDescription
destination cs3.storage.provider.v1beta1.Reference

REQUIRED. The destination path of the data transfer.

TransferProtocol

Defines the options for the Transfer protocol.

FieldTypeLabelDescription
shared_secret string

REQUIRED. Secret used to access the source of the data transfer.

source_uri string

REQUIRED. Source URI for the data transfer.

size uint64

REQUIRED. Size in bytes of the source.

WebDAVAccessMethod

Defines the options for the WebDAV access method.

FieldTypeLabelDescription
permissions cs3.storage.provider.v1beta1.ResourcePermissions

REQUIRED. The permissions for the share.

WebDAVProtocol

Defines the options for the WebDAV protocol.

FieldTypeLabelDescription
shared_secret string

REQUIRED. Secret used to access the resource.

permissions SharePermissions

REQUIRED. Permissions of the shared resource.

uri string

REQUIRED. WebDAV URI used to access the resource.

WebappAccessMethod

Defines the options for the Webapp access method.

FieldTypeLabelDescription
view_mode cs3.app.provider.v1beta1.ViewMode

REQUIRED. The view mode for the share.

WebappProtocol

Defines the options for the Webapp protocol.

FieldTypeLabelDescription
uri_template string

REQUIRED. Template URI to open the resource with a remote app.

view_mode cs3.app.provider.v1beta1.ViewMode

REQUIRED. View mode for the remote app.

ShareState

The state of the share.

NameNumberDescription
SHARE_STATE_INVALID 0

The share is no longer valid, for example, the share expired.

SHARE_STATE_PENDING 1

New shares MUST be created in the SHARE_STATE_PENDING state. This state means the share is pending to be accepted or rejected by the recipient of the share.

SHARE_STATE_ACCEPTED 2

The recipient of the share has accepted the share.

SHARE_STATE_REJECTED 3

The recipient of the share has rejected the share. Do not means the share is removed, the recipient MAY change the state to accepted or pending.

ShareType

Defines the type of share based on its recipient.

NameNumberDescription
SHARE_TYPE_INVALID 0

SHARE_TYPE_USER 1

Share of type user.

SHARE_TYPE_GROUP 2

Share of type group.

cs3/storage/provider/v1beta1/provider_api.proto

Top

AddGrantRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref Reference

REQUIRED. The reference to which the action should be performed.

grant Grant

REQUIRED. The grant to be added.

lock_id string

OPTIONAL. A lock_id: should the reference be locked, the stored lock_id MUST be equal to the given value.

AddGrantResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

CreateContainerRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref Reference

REQUIRED. The reference to which the action should be performed.

CreateContainerResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

CreateHomeRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

quota Quota

OPTIONAL.

CreateHomeResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

CreateReferenceRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref Reference

REQUIRED. The location where to store the reference.

target_uri string

REQUIRED. The reference resource by RFC3986.

CreateReferenceResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

CreateStorageSpaceRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL.

owner cs3.identity.user.v1beta1.User

REQUIRED.

type string

OPTIONAL. Could be 'home', 'share', 'project', 'space'...

name string

OPTIONAL. User readable name of the storage space.

quota Quota

OPTIONAL.

CreateStorageSpaceResponse

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

storage_space StorageSpace

REQUIRED. The created storage space.

CreateSymlinkRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref Reference

REQUIRED. The location where to store the symlink.

target string

REQUIRED. The link target can hold arbitrary text; if later resolved, a relative link is interpreted in relation to its parent directory

CreateSymlinkResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

DeleteRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref Reference

REQUIRED. The reference to which the action should be performed.

lock_id string

OPTIONAL. A lock_id: should the reference be locked, the stored lock_id MUST be equal to the given value.

DeleteResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

DeleteStorageSpaceRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

id StorageSpaceId

REQUIRED.

DeleteStorageSpaceResponse

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

DenyGrantRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref Reference

REQUIRED. The reference to which the action should be performed.

grantee Grantee

REQUIRED. The grantee to remove permission.

lock_id string

OPTIONAL. A lock_id: should the reference be locked, the stored lock_id MUST be equal to the given value.

DenyGrantResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

GetHomeRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

GetHomeResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

path string

REQUIRED. The path to the home in a storage provider. For example /eos/user/h/hugo in the storage provider with root path /eos/user/.

GetLockRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref Reference

REQUIRED. The reference the lock is associated to.

GetLockResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

lock Lock

REQUIRED. The lock metadata

GetPathRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

resource_id ResourceId

REQUIRED. The resource id of the resource.

GetPathResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

path string

REQUIRED. The path of the resource.

GetQuotaRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref Reference

OPTIONAL. Limit the quota Response to the given reference

GetQuotaResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

total_bytes uint64

REQUIRED. The total available bytes.

used_bytes uint64

REQUIRED. The number of used bytes.

InitiateFileDownloadRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref Reference

REQUIRED. The reference to which the action should be performed.

lock_id string

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.

InitiateFileDownloadResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

protocols FileDownloadProtocol repeated

REQUIRED. The protocols through which data can be downloaded.

InitiateFileUploadRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref Reference

REQUIRED. The reference to which the action should be performed.

if_not_exist bool

OPTIONAL. Whether the file is to be uploaded in exclusive mode. Defaults to false. If true, the request SHALL be processed such that only one of multiple concurrent uploads to the same target reference MAY succeed, whereas all others MUST fail with CODE_FAILED_PRECONDITION. The semantic is similar to the O_CREAT|O_EXCL POSIX flags. The request MUST return CODE_NOT_IMPLEMENTED if the provider does not support this mode.

if_match string

OPTIONAL. Whether the file is to be uploaded if the given etag matches. Default to always upload. If the storage provider has a more recent etag for the target file, the request MUST return CODE_FAILED_PRECONDITION.

if_unmodified_since cs3.types.v1beta1.Timestamp

OPTIONAL. Whether the file is to be uploaded when it has been modified on the server. Defauls to always upload. If the resource has been modified on the storage provider after the given timestamp the request MUST return CODE_FAILED_PRECONDITION.

lock_id string

OPTIONAL. A lock_id: should the reference exist and be locked, the stored lock_id MUST be equal to the given value.

InitiateFileUploadResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

protocols FileUploadProtocol repeated

REQUIRED. The protocols through which data can be uploaded.

ListContainerRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref Reference

REQUIRED. The reference to which the action should be performed.

arbitrary_metadata_keys string repeated

OPTIONAL. Arbitrary metadata to be included with the resource. A key with the name '*' means to return all available arbitrary metadata.

field_mask google.protobuf.FieldMask

OPTIONAL. The field mask applies to the resource. For the `FieldMask` definition, see https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#fieldmask

page_size int32

OPTIONAL. Clients use this field to specify the maximum number of results to be returned by the server. The server may further constrain the maximum number of results returned in a single page. If the page_size is 0, the server will decide the number of results to be returned. see https://cloud.google.com/apis/design/design_patterns#list_pagination

page_token string

OPTIONAL. The client uses this field to request a specific page of the list results.

ListContainerResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

infos ResourceInfo repeated

REQUIRED. The list of resource informations.

next_page_token string

OPTIONAL. This field represents the pagination token to retrieve the next page of results. If the value is "", it means no further results for the request. see https://cloud.google.com/apis/design/design_patterns#list_pagination

ListContainerStreamRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref Reference

REQUIRED. The reference to which the action should be performed.

arbitrary_metadata_keys string repeated

OPTIONAL. Arbitrary metadata to be included with the resource. A key with the name '*' means to return all available arbitrary metadata.

field_mask google.protobuf.FieldMask

OPTIONAL. The field mask applies to the resource. For the `FieldMask` definition, see https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#fieldmask

page_size int32

OPTIONAL. Clients use this field to specify the maximum number of results to be returned by the server. The server may further constrain the maximum number of results returned in a single page. If the page_size is 0, the server will decide the number of results to be returned. see https://cloud.google.com/apis/design/design_patterns#list_pagination

page_token string

OPTIONAL. The client uses this field to request a specific page of the list results.

ListContainerStreamResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

info ResourceInfo

REQUIRED. The resource information.

next_page_token string

OPTIONAL. This field represents the pagination token to retrieve the next page of results. If the value is "", it means no further results for the request. see https://cloud.google.com/apis/design/design_patterns#list_pagination

ListFileVersionsRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref Reference

REQUIRED. The reference to which the action should be performed.

page_size int32

OPTIONAL. Clients use this field to specify the maximum number of results to be returned by the server. The server may further constrain the maximum number of results returned in a single page. If the page_size is 0, the server will decide the number of results to be returned. see https://cloud.google.com/apis/design/design_patterns#list_pagination

page_token string

OPTIONAL. The client uses this field to request a specific page of the list results.

ListFileVersionsResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

versions FileVersion repeated

REQUIRED. The list of file versions.

next_page_token string

OPTIONAL. This field represents the pagination token to retrieve the next page of results. If the value is "", it means no further results for the request. see https://cloud.google.com/apis/design/design_patterns#list_pagination

ListGrantsRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref Reference

REQUIRED. The reference to which the action should be performed.

page_size int32

OPTIONAL. Clients use this field to specify the maximum number of results to be returned by the server. The server may further constrain the maximum number of results returned in a single page. If the page_size is 0, the server will decide the number of results to be returned. see https://cloud.google.com/apis/design/design_patterns#list_pagination

page_token string

OPTIONAL. The client uses this field to request a specific page of the list results.

ListGrantsResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

grants Grant repeated

REQUIRED. The grants.

next_page_token string

OPTIONAL. This field represents the pagination token to retrieve the next page of results. If the value is "", it means no further results for the request. see https://cloud.google.com/apis/design/design_patterns#list_pagination

ListRecycleRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

from_ts cs3.types.v1beta1.Timestamp

OPTIONAL. SHOULD be specified. The start time range to query for recycle items. The value is the Unix Epoch timestamp in seconds.

to_ts cs3.types.v1beta1.Timestamp

OPTIONAL. SHOULD be specified. The end time range to query for recycle items. The value is Unix Epoch timestamp in seconds.

ref Reference

OPTIONAL. The reference to which the action should be performed.

key string

OPTIONAL. The key for a recycle item to be listed. If provided, the item corresponding to the key will be listed.

page_size int32

OPTIONAL. Clients use this field to specify the maximum number of results to be returned by the server. The server may further constrain the maximum number of results returned in a single page. If the page_size is 0, the server will decide the number of results to be returned. see https://cloud.google.com/apis/design/design_patterns#list_pagination

page_token string

OPTIONAL. The client uses this field to request a specific page of the list results.

ListRecycleResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

recycle_items RecycleItem repeated

REQUIRED. The list of recycle items.

next_page_token string

OPTIONAL. This field represents the pagination token to retrieve the next page of results. If the value is "", it means no further results for the request. see https://cloud.google.com/apis/design/design_patterns#list_pagination

ListRecycleStreamRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

from_ts cs3.types.v1beta1.Timestamp

OPTIONAL. SHOULD be specified. The start time range to query for recycle items. The value is the Unix Epoch timestamp in seconds.

to_ts cs3.types.v1beta1.Timestamp

OPTIONAL. SHOULD be specified. The end time range to query for recycle items. The value is Unix Epoch timestamp in seconds.

ref Reference

OPTIONAL. The reference to which the action should be performed.

key string

OPTIONAL. The key for a recycle item to be listed. If provided, the item corresponding to the key will be listed.

page_size int32

OPTIONAL. Clients use this field to specify the maximum number of results to be returned by the server. The server may further constrain the maximum number of results returned in a single page. If the page_size is 0, the server will decide the number of results to be returned. see https://cloud.google.com/apis/design/design_patterns#list_pagination

page_token string

OPTIONAL. The client uses this field to request a specific page of the list results.

ListRecycleStreamResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

recycle_item RecycleItem

REQUIRED. The recycle items.

next_page_token string

OPTIONAL. This field represents the pagination token to retrieve the next page of results. If the value is "", it means no further results for the request. see https://cloud.google.com/apis/design/design_patterns#list_pagination

ListStorageSpacesRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

filters ListStorageSpacesRequest.Filter repeated

OPTIONAL. The list of filters to apply if any.

field_mask google.protobuf.FieldMask

OPTIONAL. The field mask applies to the resource. For the `FieldMask` definition, see https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#fieldmask

page_size int32

OPTIONAL. Clients use this field to specify the maximum number of results to be returned by the server. The server may further constrain the maximum number of results returned in a single page. If the page_size is 0, the server will decide the number of results to be returned. see https://cloud.google.com/apis/design/design_patterns#list_pagination

page_token string

OPTIONAL. The client uses this field to request a specific page of the list results.

ListStorageSpacesRequest.Filter

Represents a filter to apply to the request.

FieldTypeLabelDescription
type ListStorageSpacesRequest.Filter.Type

REQUIRED.

id StorageSpaceId

owner cs3.identity.user.v1beta1.UserId

space_type string

path string

user cs3.identity.user.v1beta1.UserId

ListStorageSpacesResponse

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

storage_spaces StorageSpace repeated

REQUIRED.

next_page_token string

OPTIONAL. This field represents the pagination token to retrieve the next page of results. If the value is "", it means no further results for the request. see https://cloud.google.com/apis/design/design_patterns#list_pagination

MoveRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

source Reference

REQUIRED. The source reference the resource is moved from.

destination Reference

REQUIRED. The destination reference the resource is moved to.

lock_id string

OPTIONAL. A lock_id: should the source reference be locked, the stored lock_id MUST be equal to the given value.

MoveResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

PurgeRecycleRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref Reference

REQUIRED. The reference to which the action should be performed.

key string

REQUIRED. The key corresponding to the item to be purged..

PurgeRecycleResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

RefreshLockRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref Reference

REQUIRED. The reference on which the lock should be refreshed.

lock Lock

REQUIRED. The lock metadata.

existing_lock_id string

OPTIONAL. The existing lock id. This can be used to refresh the existing lock with a new lock while checking if the lock holder sends the correct existing lock_id

RefreshLockResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

RemoveGrantRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref Reference

REQUIRED. The reference to which the action should be performed.

grant Grant

REQUIRED. The grant to remove.

lock_id string

OPTIONAL. A lock_id: should the reference be locked, the stored lock_id MUST be equal to the given value.

RemoveGrantResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

RestoreFileVersionRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref Reference

REQUIRED. The reference to which the action should be performed.

key string

REQUIRED. The key to restore a specific file version.

lock_id string

OPTIONAL. A lock_id: should the reference be locked, the stored lock_id MUST be equal to the given value.

RestoreFileVersionResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

RestoreRecycleItemRequest

TODO: restore to original location if not specified as OPTIONAL?

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref Reference

REQUIRED. The reference to the user's home directory.

key string

REQUIRED. The key for the recycle item to be restored.

restore_ref Reference

OPTIONAL. An optional restore path for the deleted resource. It can be useful to restore to another location rather than the original. If empty, service implementors MUST restore to original location if possible.

lock_id string

OPTIONAL. A lock_id: should a lock exist for the reference where the file is to be restored, the stored lock_id MUST be equal to the given value.

RestoreRecycleItemResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

SetArbitraryMetadataRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref Reference

REQUIRED. The reference to which the action should be performed.

arbitrary_metadata ArbitraryMetadata

REQUIRED. The arbitrary metadata to add to the resource.

lock_id string

OPTIONAL. A lock_id: should the reference be locked, the stored lock_id MUST be equal to the given value.

SetArbitraryMetadataResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

SetLockRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref Reference

REQUIRED. The reference on which the lock should be set, if no lock is present.

lock Lock

REQUIRED. The lock metadata.

SetLockResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

StatRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref Reference

REQUIRED. The reference to which the action should be performed.

arbitrary_metadata_keys string repeated

OPTIONAL. Arbitrary metadata be included with the resource. A key with the name '*' means to return all available arbitrary metadata.

field_mask google.protobuf.FieldMask

OPTIONAL. The field mask applies to the resource. For the `FieldMask` definition, see https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#fieldmask

StatResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

info ResourceInfo

REQUIRED. The resource information.

TouchFileRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref Reference

REQUIRED. The reference to which the action should be performed.

TouchFileResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

UnlockRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref Reference

REQUIRED. The reference the lock is associated to.

lock Lock

REQUIRED. The lock metadata.

UnlockResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

UnsetArbitraryMetadataRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref Reference

REQUIRED. The reference to which the action should be performed.

arbitrary_metadata_keys string repeated

REQUIRED. The arbitrary metadata to delete.

lock_id string

OPTIONAL. A lock_id: should the reference be locked, the stored lock_id MUST be equal to the given value.

UnsetArbitraryMetadataResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

UpdateGrantRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref Reference

REQUIRED. The reference to which the action should be performed.

grant Grant

REQUIRED. The grant to be updated.

lock_id string

OPTIONAL. A lock_id: should the reference be locked, the stored lock_id MUST be equal to the given value.

UpdateGrantResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

UpdateStorageSpaceRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

storage_space StorageSpace

REQUIRED.

UpdateStorageSpaceResponse

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

storage_space StorageSpace

REQUIRED. The updated storage space.

ListStorageSpacesRequest.Filter.Type

The filter to apply.

NameNumberDescription
TYPE_INVALID 0

TYPE_NO 1

TYPE_ID 2

TYPE_OWNER 3

TYPE_SPACE_TYPE 4

TYPE_PATH 5

TYPE_USER 6

ProviderAPI

Storage Provider API

The Storage Provider API is meant to manipulate storage

resources in the underlying storage system behind the service.

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.

Method NameRequest TypeResponse TypeDescription
AddGrant AddGrantRequest AddGrantResponse

Adds a new grant for the provided reference. MUST return CODE_NOT_FOUND if the reference does not exist

CreateContainer CreateContainerRequest CreateContainerResponse

Creates a new resource of type container. MUST return CODE_FAILED_PRECONDITION if the container cannot be created at the specified reference.

TouchFile TouchFileRequest TouchFileResponse

Creates a new resource of type file. MUST return CODE_FAILED_PRECONDITION if the file cannot be created at the specified reference.

Delete DeleteRequest DeleteResponse

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

DenyGrant DenyGrantRequest DenyGrantResponse

Denies access to the provided reference. MUST return CODE_NOT_FOUND if the reference does not exist

GetPath GetPathRequest GetPathResponse

Returns the path reference for the provided resource id reference. MUST return CODE_NOT_FOUND if the reference does not exist

GetQuota GetQuotaRequest GetQuotaResponse

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

InitiateFileDownload InitiateFileDownloadRequest InitiateFileDownloadResponse

Initiates the download of a file using an out-of-band data transfer mechanism.

InitiateFileUpload InitiateFileUploadRequest InitiateFileUploadResponse

Initiates the upload of a file using an out-of-band data transfer mechanism.

ListGrants ListGrantsRequest ListGrantsResponse

Returns the list of grants for the provided reference. MUST return CODE_NOT_FOUND if the reference does not exists.

ListContainerStream ListContainerStreamRequest ListContainerStreamResponse stream

Returns a stream of resource informations for the provided reference. MUST return CODE_NOT_FOUND if the reference does not exists.

ListContainer ListContainerRequest ListContainerResponse

Returns a list of resource information for the provided reference. MUST return CODE_NOT_FOUND if the reference does not exists.

ListFileVersions ListFileVersionsRequest ListFileVersionsResponse

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?

ListRecycleStream ListRecycleStreamRequest ListRecycleStreamResponse stream

Returns a stream of recycle items for this storage provider.

ListRecycle ListRecycleRequest ListRecycleResponse

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

Move MoveRequest MoveResponse

Moves 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 cannot be moved to the destination reference.

RemoveGrant RemoveGrantRequest RemoveGrantResponse

Removes a grant for the provided reference. This is recursive and atomic for directories. Does not follow references. MUST return CODE_NOT_FOUND if the reference does not exist. MUST return CODE_NOT_FOUND if grant does not exist.

PurgeRecycle PurgeRecycleRequest PurgeRecycleResponse

Permanently removes a recycle item from the recycle. This operation is irrevocable. MUST return CODE_NOT_FOUND if the recycle item id does not exist.

RestoreFileVersion RestoreFileVersionRequest RestoreFileVersionResponse

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.

RestoreRecycleItem RestoreRecycleItemRequest RestoreRecycleItemResponse

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.

Stat StatRequest StatResponse

Returns the resource information at the provided reference. MUST return CODE_NOT_FOUND if the reference does not exist.

UpdateGrant UpdateGrantRequest UpdateGrantResponse

Updates an ACL for the provided reference. MUST return CODE_NOT_FOUND if the reference does not exist. MUST return CODE_FAILED_PRECONDITION if the acl does not exist.

CreateSymlink CreateSymlinkRequest CreateSymlinkResponse

Creates a symlink to another resource.

CreateReference CreateReferenceRequest CreateReferenceResponse

Creates a reference to another resource in the same cluster or another domain (OCM shares). The references resource can be accessed by the protocol specificied in the request message.

SetArbitraryMetadata SetArbitraryMetadataRequest SetArbitraryMetadataResponse

Sets arbitrary metadata into a storage resource. Arbitrary metadata is returned in a cs3.storageprovider.v1beta1.ResourceInfo.

UnsetArbitraryMetadata UnsetArbitraryMetadataRequest UnsetArbitraryMetadataResponse

Unsets arbitrary metdata into a storage resource. Arbitrary metadata is returned in a cs3.storageprovider.v1beta1.ResourceInfo.

SetLock SetLockRequest SetLockResponse

Locks a storage resource. Note that if the resource is a container, MAY return CODE_NOT_IMPLEMENTED as the behavior is yet to be defined at this stage. 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.

GetLock GetLockRequest GetLockResponse

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

RefreshLock RefreshLockRequest RefreshLockResponse

Refreshes the lock metadata of a storage resource. MUST return CODE_NOT_FOUND if the reference does not exist. MUST return CODE_PRECONDITION_FALIED if the reference is not locked or if the caller does not hold the lock. The caller MUST have write permissions on the resource.

Unlock UnlockRequest UnlockResponse

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

CreateHome CreateHomeRequest CreateHomeResponse

Creates the home directory for a user.

GetHome GetHomeRequest GetHomeResponse

Gets the home path for the user.

CreateStorageSpace CreateStorageSpaceRequest CreateStorageSpaceResponse

Creates a storage space.

ListStorageSpaces ListStorageSpacesRequest ListStorageSpacesResponse

Lists storage spaces.

UpdateStorageSpace UpdateStorageSpaceRequest UpdateStorageSpaceResponse

Updates a storage space.

DeleteStorageSpace DeleteStorageSpaceRequest DeleteStorageSpaceResponse

Deletes a storage space.

cs3/storage/provider/v1beta1/resources.proto

Top

ArbitraryMetadata

Arbitrary metadata than can be set to the resource.

FieldTypeLabelDescription
metadata ArbitraryMetadata.MetadataEntry repeated

ArbitraryMetadata.MetadataEntry

FieldTypeLabelDescription
key string

value string

CanonicalMetadata

CanonicalMetadata contains extra metadata

attached to a resource. This message and the Opaque

message differ in that Opaque allows service implementors

to include any extra metadata in any format and most clients

will ignore it. However, the CanonicalMetadata message

contains well defined fileds that clients MUST understand if

they are specified.

FieldTypeLabelDescription
target Reference

REQUIRED if resource type is RESOURCE_TYPE_REFERENCE. The target reference the resource points to. TODO(moscicki): what fields can fit here? executable bit? bool executable = 2; TODO(labkode): at some points maybe we could add here acls and other well-known metadata.

FileDownloadProtocol

A file download protocol object stores information about

downloading resources using a specific protocol.

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

protocol string

REQUIRED. The protocol to be followed.

download_endpoint string

REQUIRED. The endpoint where to download the data. The value MUST be a Uniform Resource Identifier (URI) as specified in RFC 3986.

expose bool

REQUIRED. Tells to the gateway if the client should be exposed directly to the download_endpoint.

FileUploadProtocol

A file upload protocol object stores information about

uploading resources using a specific protocol.

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

protocol string

REQUIRED. The protocol to be followed.

upload_endpoint string

REQUIRED. The endpoint where to upload the data. The value MUST be a Uniform Resource Identifier (URI) as specified in RFC 3986.

available_checksums ResourceChecksumPriority repeated

REQUIRED. List of available checksums the client can use when sending the file.

expose bool

REQUIRED. Tells to the gateway if the client should be exposed directly to the upload_endpoint.

expiration cs3.types.v1beta1.Timestamp

OPTIONAL. The time at which the upload will expire.

FileVersion

The information for a file version.

TODO(labkode): make size and mtime OPTIONAL?

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

key string

MUST the specified. The key to identify the version.

size uint64

REQUIRED. The size in bytes of the file version.

mtime uint64

REQUIRED. The Unix Epoch timestamp in seconds.

etag string

REQUIRED. As decribed in https://tools.ietf.org/html/rfc7232#section-2.3 For a file version, the etag does not change because a version is immutable.

Grant

A grant grants permissions

to a resource to a grantee.

FieldTypeLabelDescription
grantee Grantee

REQUIRED. The grantee of the grant.

permissions ResourcePermissions

REQUIRED. The permissions for the grant.

creator cs3.identity.user.v1beta1.UserId

OPTIONAL The Creator of the grant

expiration cs3.types.v1beta1.Timestamp

OPTIONAL Expiration of the grant.

Grantee

A grantee is the receiver of a grant.

FieldTypeLabelDescription
type GranteeType

REQUIRED. The type of the grantee.

user_id cs3.identity.user.v1beta1.UserId

The user id.

group_id cs3.identity.group.v1beta1.GroupId

The group id.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information such as UID or GID.

Lock

The metadata associated with a lock on a resource.

Provided that storage drivers are free to implement the storage

of this metadata according to their constraints, a reference

implementation is given here. The lock SHOULD be stored

as an extended attribute on the referenced filesystem entry.

Such extended attribute MUST NOT be exposed via the `Stat` and `SetArbitraryMetadata` APIs.

Instead, the `ResourceInfo.Lock` attribute MUST be populated if a lock exists for the given reference.

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

lock_id string

REQUIRED. The id of the lock, eg. the X-WOPI-Lock id or the WebDAV opaquelocktoken.

type LockType

REQUIRED. The type of lock.

user cs3.identity.user.v1beta1.UserId

OPTIONAL. The userid of a user, which represents either the lock holder, or the user that last created/modified the lock. When non empty, `RefreshLock` and `Unlock` operations MUST check their request's content against it.

app_name string

OPTIONAL. An application name if the lock is held by an app. When non empty, `RefreshLock` and `Unlock` operations MUST check their request's content against it.

expiration cs3.types.v1beta1.Timestamp

OPTIONAL. The time when the lock will expire.

Quota

Represents a quota for a storage space.

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

quota_max_bytes uint64

OPTIONAL. The bytes quota for the user.

quota_max_files uint64

OPTIONAL. The files quota for the user.

RecycleItem

A recycle item represents the information

of a deleted resource.

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

type ResourceType

REQUIRED. The type of the resource.

key string

REQUIRED. The key to identify the deleted resource.

ref Reference

REQUIRED. The original reference of the deleted resource.

size uint64

OPTIONAL. The size of the deleted resource.

deletion_time cs3.types.v1beta1.Timestamp

REQUIRED. The deletion time of the resource in Unix Epoch timestamp in seconds.

Reference

The mechanism to identify a resource in the CS3 namespace.

It can represent path based, id based and combined references:

The storage registry uses the storage_id to determine the responsible storage provider.

When the storage_id is not available it will use the path.

In a URL the different components can be represented in a string using the following layout:

!:

FieldTypeLabelDescription
resource_id ResourceId

OPTIONAL

path string

OPTIONAL. When starting with `/` represents an absolute path. In this case the resource_id MUST be empty. When starting with `.` represents a path relative to the resource_id. The resource_id MUST be given. When path is empty the resource_id must be set. Used to look up the path for a resource_id.

ResourceChecksum

The checksum to verify

the integrity of a resource.

FieldTypeLabelDescription
type ResourceChecksumType

REQUIRED. The type of checksum to use. If no checksum is provided, type MUST be RESOURCE_CHECKSUM_TYPE_UNSET.

sum string

MUST be specified if type is not RESOURCE_CHECKSUM_TYPE_UNSET or type is not RESOURCE_CHECKSUM_TYPE_INVALID. MUST be the hexadecimal representation of the cheksum. The value is case-insensitive, so "1E603A8", "1e603a8" or "1e603A8" are the same.

ResourceChecksumPriority

When negotiating the user of checksum types

between client and server, this structure

defines the priority of the checksum.

Priority 0 means highest priority.

FieldTypeLabelDescription
type ResourceChecksumType

priority uint32

ResourceId

A resource id uniquely identifies a

resource in the storage provider namespace.

A ResourceId MUST be unique in the storage provider.

FieldTypeLabelDescription
storage_id string

REQUIRED. The logical id of a storage. Used by the storage registry to determine the responsible storage provider.

opaque_id string

REQUIRED. The internal id used by service implementor to uniquely identity the resource in the internal implementation of the service.

space_id string

OPTIONAL. The internal id used by service implementor to uniquely identify the storage space. Used by the storageprovider to locate the correct storage space.

ResourceInfo

Represents the information (metadata) about

a storage resource organized in a hierarchical namespace (file, directory/container, reference, symlink, ...).

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

type ResourceType

REQUIRED. The type of the resource (container, file, ...) See the enum ResourceType for all possible types.

id ResourceId

REQUIRED. Opaque unique identifier of the resource.

checksum ResourceChecksum

REQUIRED. The data checksum for the file resource. For all other resources, the checksum is unset.

etag string

REQUIRED. As decribed in https://tools.ietf.org/html/rfc7232#section-2.3 For file resources, the etag must change if data or metadata changes. For container types, the etag must change if etag of any of the (indirectly) contained resources change. For reference types, the etag must change if etag of the target changes and the target is on the same storage provider. In all other cases the etag does not change.

mime_type string

REQUIRED. As described in [RFC 2015](https://tools.ietf.org/html/rfc2045#page-7)

mtime cs3.types.v1beta1.Timestamp

REQUIRED. Last modification time (mtime) of file or directory contents. For reference types this is NOT the mtime of the target.

path string

REQUIRED. The path for the resource: MUST start with `/` when the reference had no resource_id, indicating an absolute path. MUST start with `.` when the reference had a resource_id, indicating a relative path.

permission_set ResourcePermissions

REQUIRED. The set of permissions for the resource effective for the authenticated user.

size uint64

REQUIRED. The size of the resource in bytes (file size) TODO(moscicki): This is undefined for container type. Is the accounting recursive?, could it be set to 0 for directories if recursive not supported? use another field? TODO(moscicki): This needs to be defined also for other types (such as a symlink to a directory or file)

owner cs3.identity.user.v1beta1.UserId

REQUIRED. Identifier of the owner of the resource.

target string

OPTIONAL. if ResourceType is either RESOURCE_TYPE_SYMLINK or RESOURCE_TYPE_REFERENCE it MUST be specified.

canonical_metadata CanonicalMetadata

OPTIONAL. Additional metadata attached to the resource. If ResourceType is RESOURCE_TYPE_REFERENCE it MUST be specified.

arbitrary_metadata ArbitraryMetadata

OPTIONAL. Arbitrary metadata attached to a resource.

lock Lock

OPTIONAL. Exclusive or write lock on this resource that will limit modification of the resource to holders of the lock. Can be used by WOPI or other apps requiring write or exclusive locks.

advisory_locks Lock repeated

OPTIONAL. Advisory locks on this resource. Can be used for shared locks or other forms of collaborative locks.

parent_id ResourceId

OPTIONAL. Reference to the container of this resource. If path is relative it MUST be specified, regardless the access restrictions to the resource: a subsequent Stat() on it MAY return access denied if appropriate.

name string

OPTIONAL The name of the resource.

space StorageSpace

OPTIONAL. StorageSpace where this resource is located.

ResourcePermissions

The representation of permissions attached to a resource.

FieldTypeLabelDescription
add_grant bool

create_container bool

delete bool

get_path bool

get_quota bool

initiate_file_download bool

initiate_file_upload bool

list_grants bool

list_container bool

list_file_versions bool

list_recycle bool

move bool

remove_grant bool

purge_recycle bool

restore_file_version bool

restore_recycle_item bool

stat bool

update_grant bool

deny_grant bool

StorageSpace

Represents a storage space which could be a 'home', 'share' etc...

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

id StorageSpaceId

REQUIRED.

owner cs3.identity.user.v1beta1.User

OPTIONAL.

root ResourceId

OPTIONAL. The root resource id of the storage space.

name string

OPTIONAL.

quota Quota

OPTIONAL.

space_type string

OPTIONAL. Could be 'home', 'share', 'project', 'space'...

mtime cs3.types.v1beta1.Timestamp

OPTIONAL. Last modification time (mtime) of the root resource of this storage space.

root_info ResourceInfo

OPTIONAL. Resource info for the storage space root.

StorageSpaceId

The id of a storage space.

FieldTypeLabelDescription
opaque_id string

REQUIRED. The internal storage space id.

GranteeType

The type of the grantee.

NameNumberDescription
GRANTEE_TYPE_INVALID 0

GRANTEE_TYPE_USER 1

This type represents an individual.

GRANTEE_TYPE_GROUP 2

This type represents a group of individuals.

LockType

The available type of locks for a resource.

NameNumberDescription
LOCK_TYPE_INVALID 0

LOCK_TYPE_SHARED 1

Shared (advisory) lock: the resource can be read, written/overwritten or unlocked by everyone who has access.

LOCK_TYPE_WRITE 2

Write lock: the resource can be read by everyone who has access, but write, refreshlock and unlock operations are restricted to the lock holder.

LOCK_TYPE_EXCL 3

Exclusive lock: only the lock holder can operate on the resource, anyone else is denied to access it.

ResourceChecksumType

The type of checksum to use.

NameNumberDescription
RESOURCE_CHECKSUM_TYPE_INVALID 0

RESOURCE_CHECKSUM_TYPE_UNSET 1

unset means no checksum is set.

RESOURCE_CHECKSUM_TYPE_ADLER32 2

Use Adler32 checksum.

RESOURCE_CHECKSUM_TYPE_MD5 3

Use MD5 checksum.

RESOURCE_CHECKSUM_TYPE_SHA1 4

Use SHA-1 checksum.

ResourceType

The available types of resources.

NameNumberDescription
RESOURCE_TYPE_INVALID 0

RESOURCE_TYPE_FILE 1

The file type represents a type that holds arbitrary data. Service implementors usually map this type to files (local filesystem) or objects (Amazon S3).

RESOURCE_TYPE_CONTAINER 2

The container type represents a type that can contain another types. Service implementors usually map this type to folders (local filesystem) or buckets (Amazon S3).

RESOURCE_TYPE_REFERENCE 3

This represents a reference type which points to another resource where client MAY be redirected. Client SHOULD use the ResourceInfo.target reference for a subsequent call.

RESOURCE_TYPE_SYMLINK 4

This represents a symbolic link type if the underlying storage system supports it. Symlink target SHOULD NOT be interpreted by the clients.

RESOURCE_TYPE_INTERNAL 5

Internal resource type for some specific resources inside a storage implementation. For example, this type could be used to represent a device file on a Linux filesystem. Another example could be to represent an ongoing upload, where an hypothetically user interface could show a loading icon on this type of resources until the upload operation is completed. Internal resources SHOULD NOT be moved to a different storage provider.

cs3/storage/registry/v1beta1/registry_api.proto

Top

GetHomeRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

GetHomeResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

provider ProviderInfo

REQUIRED. The storage provider for the user home.

GetStorageProvidersRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref cs3.storage.provider.v1beta1.Reference

REQUIRED. The reference for the resource.

GetStorageProvidersResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

providers ProviderInfo repeated

REQUIRED. The storage providers handling the requested storage resource.

ListStorageProvidersRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information. TODO(labkode): maybe add some filter?

ListStorageProvidersResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

providers ProviderInfo repeated

REQUIRED. The list of storage providers this registry knows about.

RegistryAPI

Storage Registry API

The Storage Registry API is meant to as registry to obtain

information of available storage providers.

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.

Method NameRequest TypeResponse TypeDescription
GetStorageProviders GetStorageProvidersRequest GetStorageProvidersResponse

Returns the storage provider that is reponsible for the given resource reference. MUST return CODE_NOT_FOUND if the reference does not exist.

ListStorageProviders ListStorageProvidersRequest ListStorageProvidersResponse

Returns a list of the available storage providers known by this registry.

GetHome GetHomeRequest GetHomeResponse

Gets the user home storage provider. TODO(labkode): missing methods for adding and removing a storage provider with different visibility levels (system-wide, user-wide, group-wide)...

cs3/storage/registry/v1beta1/resources.proto

Top

ProviderInfo

The information for the storage provider.

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information (containing storage-specific information). For example, additional metadata attached to the resource.

provider_id string

REQUIRED. The storage provider id that will become part of the resource id. For example, if the provider_id is "home", resources obtained from this storage provider will have a resource id like "home:1234".

provider_path string

REQUIRED. The public path prefix this storage provider handles. In Unix literature, the mount path. For example, if the provider_path is "/home", resources obtained from this storage provier will have a resource path lik "/home/docs".

address string

REQUIRED. The address where the storage provider can be reached. For example, tcp://localhost:1099.

description string

OPTIONAL. Information to describe the functionalities offered by the storage provider. Meant to be read by humans.

features ProviderInfo.Features

REQUIRED. List of available methods.

ProviderInfo.Features

REQUIRED.

Represents the list of features available

on this storage provider. If the feature is not supported,

the related service methods MUST return CODE_UNIMPLEMENTED.

FieldTypeLabelDescription
recycle bool

file_versions bool

Scalar Value Types

.proto TypeNotesC++JavaPythonGoC#PHPRuby
double double double float float64 double float Float
float float float float float32 float float Float
int32 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. int32 int int int32 int integer Bignum or Fixnum (as required)
int64 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. int64 long int/long int64 long integer/string Bignum
uint32 Uses variable-length encoding. uint32 int int/long uint32 uint integer Bignum or Fixnum (as required)
uint64 Uses variable-length encoding. uint64 long int/long uint64 ulong integer/string Bignum or Fixnum (as required)
sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int32 int int int32 int integer Bignum or Fixnum (as required)
sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 long int/long int64 long integer/string Bignum
fixed32 Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int int uint32 uint integer Bignum or Fixnum (as required)
fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long uint64 ulong integer/string Bignum
sfixed32 Always four bytes. int32 int int int32 int integer Bignum or Fixnum (as required)
sfixed64 Always eight bytes. int64 long int/long int64 long integer/string Bignum
bool bool boolean boolean bool bool boolean TrueClass/FalseClass
string A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode string string string String (UTF-8)
bytes May contain any arbitrary sequence of bytes. string ByteString str []byte ByteString string String (ASCII-8BIT)