| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
|
| ref | cs3.storage.provider.v1beta1.Reference | REQUIRED. The reference to which the action should be performed. |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| 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? |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
|
| token | string | REQUIRED. The access token. |
| Field | Type | Label | Description |
| 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. |
REQUIRED.
View mode.
| Name | Number | Description |
| 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. |
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 Name | Request Type | Response Type | Description |
| 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. |
A file download protocol object stores information about
downloading resources using a specific protocol.
| Field | Type | Label | Description |
| 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. |
A file upload protocol object stores information about
uploading resources using a specific protocol.
| Field | Type | Label | Description |
| 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. |
CheckPermissionsRequest is used to check if a user has a certain permission.
| Field | Type | Label | Description |
| 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. |
CheckPermissionsResponse ...
| Field | Type | Label | Description |
| status | cs3.rpc.v1beta1.Status | REQUIRED. The response status. |
PermissionsAPI defines a service for permissions.
| Method Name | Request Type | Response Type | Description |
| CheckPermission | CheckPermissionRequest | CheckPermissionResponse | CheckPermission defines a method to check permission/role. |
SubjectReference references either a user or a group by id.
| Field | Type | Label | Description |
| user_id | cs3.identity.user.v1beta1.UserId |
|
|
| group_id | cs3.identity.group.v1beta1.GroupId |
|
| Field | Type | Label | Description |
| key | PreferenceKey | REQUIRED. |
| Field | Type | Label | Description |
| status | cs3.rpc.v1beta1.Status | REQUIRED. The response status. |
|
| val | string | REQUIRED. The value associated with the key. |
| Field | Type | Label | Description |
| key | PreferenceKey | REQUIRED. |
|
| val | string | REQUIRED. The value associated with the key. |
| Field | Type | Label | Description |
| status | cs3.rpc.v1beta1.Status | REQUIRED. The response status. |
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 Name | Request Type | Response Type | Description |
| SetKey | SetKeyRequest | SetKeyResponse | Maps the key-value pair. |
| GetKey | GetKeyRequest | GetKeyResponse | Returns the value associated with the requested key. |
Represents a key object consisting of a namespace and a string key.
| Field | Type | Label | Description |
| namespace | string | REQUIRED. The namespace to which the key belongs. |
|
| key | string | REQUIRED. |
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`.
| Name | Number | Description |
| 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 |
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.
| Field | Type | Label | Description |
| 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. |
TxId uniquely identifies a transfer in the transfer provider namespace.
| Field | Type | Label | Description |
| 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 represents information about a transfer.
| Field | Type | Label | Description |
| 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 represents transfer status.
| Name | Number | Description |
| 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. |
| Field | Type | Label | Description |
| tx_id | TxId | REQUIRED. The transfer identifier. |
|
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| tx_id | TxId | REQUIRED. The transfer identifier. |
|
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
|
| filters | ListTransfersRequest.Filter | repeated | OPTIONAL. The list of filters to apply if any. |
REQUIRED.
Represents a filter to apply to the request.
| Field | Type | Label | Description |
| type | ListTransfersRequest.Filter.Type | REQUIRED. |
|
| status | Status |
|
|
| share_id | cs3.sharing.ocm.v1beta1.ShareId |
|
|
| tx_id | TxId |
|
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| tx_id | TxId | REQUIRED. The transfer identifier. |
|
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
| Field | Type | Label | Description |
| 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. |
The filter type.
| Name | Number | Description |
| TYPE_INVALID | 0 | |
| TYPE_STATUS | 1 | |
| TYPE_SHARE_ID | 2 | |
| TYPE_TX_ID | 3 |
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 Name | Request Type | Response Type | Description |
| 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. |
Opaque represents opaque information
in a form on a map.
For example, a local filesystem can
use this message to include filesystem
extended attributes.
| Field | Type | Label | Description |
| map | Opaque.MapEntry | repeated | REQUIRED. |
| Field | Type | Label | Description |
| key | string |
|
|
| value | OpaqueEntry |
|
OpaqueEntry represents the encoded
opaque value.
| Field | Type | Label | Description |
| 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. |
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.
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| status | cs3.rpc.v1beta1.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| status | cs3.rpc.v1beta1.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| status | cs3.rpc.v1beta1.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
Provides a write only API for managing groups.
| Method Name | Request Type | Response Type | Description |
| 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. |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| status | cs3.rpc.v1beta1.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
Provides a write only API for managing users.
| Method Name | Request Type | Response Type | Description |
| CreateUser | CreateUserRequest | CreateUserResponse | Create a user account. |
| DeleteUser | DeleteUserRequest | DeleteUserResponse | Delete a user account. |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| 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. |
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 Name | Request Type | Response Type | Description |
| 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. |
Represents the information for the app URL to be called by the clients.
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| key | string |
|
|
| value | string |
|
| Field | Type | Label | Description |
| key | string |
|
|
| value | string |
|
Defines the valid targets for an app URL.
| Name | Number | Description |
| 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 |
Defines the view modes.
| Name | Number | Description |
| 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. |
| Field | Type | Label | Description |
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
|
| provider | ProviderInfo | REQUIRED. The app provider to be registered. |
| Field | Type | Label | Description |
| status | cs3.rpc.v1beta1.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
| Field | Type | Label | Description |
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
|
| resource_info | cs3.storage.provider.v1beta1.ResourceInfo | REQUIRED. The resource information. |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
|
| mime_type | string | REQUIRED. The mimetype for which the default app has to be returned. |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| status | cs3.rpc.v1beta1.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
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 Name | Request Type | Response Type | Description |
| 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. |
Represents a mime type and its corresponding file extension.
| Field | Type | Label | Description |
| 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 |
Represents the information of the app provider.
| Field | Type | Label | Description |
| 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". |
REQUIRED.
The capability of the underlying app.
| Name | Number | Description |
| CAPABILITY_INVALID | 0 | |
| CAPABILITY_VIEWER | 1 | The app is a simple viewer. |
| CAPABILITY_EDITOR | 2 | The app is a full editor. |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| key | string |
|
|
| value | cs3.auth.provider.v1beta1.Scope |
|
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
|
| password | string | REQUIRED. The password which has to be invalidated. |
| Field | Type | Label | Description |
| status | cs3.rpc.v1beta1.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
| Field | Type | Label | Description |
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
| Field | Type | Label | Description |
| 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. |
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 Name | Request Type | Response Type | Description |
| 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. |
AppPassword stores information about secondary passwords generated by users
to be used with third-party applications.
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| key | string |
|
|
| value | cs3.auth.provider.v1beta1.Scope |
|
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| key | string |
|
|
| value | Scope |
|
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 Name | Request Type | Response Type | Description |
| Authenticate | AuthenticateRequest | AuthenticateResponse | Authenticate authenticates a client. |
Scope defines role-based permissions for various resources.
| Field | Type | Label | Description |
| 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. |
The role associated with the scope.
| Name | Number | Description |
| 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 |
| Field | Type | Label | Description |
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
|
| type | string | REQUIRED. The type of authentication provider. |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. TODO(labkode): maybe add some filter? |
| Field | Type | Label | Description |
| 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. |
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 Name | Request Type | Response Type | Description |
| 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. |
ProviderInfo provides the information about an authentication provider.
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| status | cs3.rpc.v1beta1.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
|
| group | Group | REQUIRED. The group information. |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| status | cs3.rpc.v1beta1.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
|
| group | Group | REQUIRED. The group information. |
| Field | Type | Label | Description |
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
|
| group_id | GroupId | REQUIRED. The id of the group. |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| 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. |
Provides an API for managing groups.
| Method Name | Request Type | Response Type | Description |
| 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. |
Represents a group of the system.
| Field | Type | Label | Description |
| id | GroupId |
|
|
| group_name | string |
|
|
| gid_number | int64 |
|
|
| string |
|
||
| mail_verified | bool |
|
|
| display_name | string |
|
|
| members | cs3.identity.user.v1beta1.UserId | repeated |
|
| opaque | cs3.types.v1beta1.Opaque |
|
A GroupId represents a group.
| Field | Type | Label | Description |
| 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. |
Represents a user of the system.
| Field | Type | Label | Description |
| id | UserId |
|
|
| username | string |
|
|
| string |
|
||
| mail_verified | bool |
|
|
| display_name | string |
|
|
| groups | string | repeated |
|
| opaque | cs3.types.v1beta1.Opaque |
|
|
| uid_number | int64 |
|
|
| gid_number | int64 |
|
A UserId represents a user.
| Field | Type | Label | Description |
| 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. |
The type of user.
| Name | Number | Description |
| 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. |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| status | cs3.rpc.v1beta1.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
|
| user | User | REQUIRED. The user information. |
| Field | Type | Label | Description |
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
|
| user_id | UserId | REQUIRED. The id of the user. |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| status | cs3.rpc.v1beta1.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
|
| user | User | REQUIRED. The user information. |
Provides an API for managing users.
| Method Name | Request Type | Response Type | Description |
| 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. |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| id | string | REQUIRED. Unique ID to identify the share at the consumer side. |
|
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
| Field | Type | Label | Description |
| status | cs3.rpc.v1beta1.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| status | cs3.rpc.v1beta1.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
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 Name | Request Type | Response Type | Description |
| 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 |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| 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. |
|
| string | REQUIRED. The initiator's email of the workflow. |
||
| display_name | string | REQUIRED. The initiator's display name of the workflow. |
| Field | Type | Label | Description |
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
|
| remote_user_id | cs3.identity.user.v1beta1.UserId | REQUIRED. The id of the user. |
| Field | Type | Label | Description |
| status | cs3.rpc.v1beta1.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
| Field | Type | Label | Description |
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
|
| filter | string | REQUIRED. The filter to apply. |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| 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. |
|
| string | REQUIRED. The initiator's email of the workflow. |
||
| display_name | string | REQUIRED. The initiator's display name of the workflow. |
| Field | Type | Label | Description |
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
|
| description | string | OPTIONAL. The description of the token. |
| Field | Type | Label | Description |
| status | cs3.rpc.v1beta1.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
|
| invite_token | InviteToken | REQUIRED. The generated token. |
| Field | Type | Label | Description |
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
|
| remote_user_id | cs3.identity.user.v1beta1.UserId | REQUIRED. The id of the user. |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| status | cs3.rpc.v1beta1.Status | REQUIRED. The response status. |
|
| invite_tokens | InviteToken | repeated | REQUIRED. The list of valid tokens. |
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 Name | Request Type | Response Type | Description |
| 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. |
InviteToken is used to invite users and groups from other sync'n'share
systems to collaborate on resources.
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
|
| domain | string | REQUIRED. The domain of the system provider. |
| Field | Type | Label | Description |
| 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 |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| status | cs3.rpc.v1beta1.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
| Field | Type | Label | Description |
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
| Field | Type | Label | Description |
| status | cs3.rpc.v1beta1.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
|
| providers | ProviderInfo | repeated | REQUIRED. The share. |
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 Name | Request Type | Response Type | Description |
| 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. |
Details of the sync'n'share system provider.
| Field | Type | Label | Description |
| 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. |
|
| 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. |
| Field | Type | Label | Description |
| key | string |
|
|
| value | string |
|
The services offered by sync'n'share system providers.
| Field | Type | Label | Description |
| 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. |
The endpoints exposed by particular services.
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| key | string |
|
|
| value | string |
|
Identifier for various types of services offered by sync'n'share system providers.
| Field | Type | Label | Description |
| name | string | REQUIRED The name of the service type. |
|
| description | string | REQUIRED The description of the service type. |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| status | cs3.rpc.v1beta1.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
|
| share | Share | REQUIRED. The created share. |
| Field | Type | Label | Description |
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
|
| ref | ShareReference | REQUIRED. The reference of the received share. |
| Field | Type | Label | Description |
| status | cs3.rpc.v1beta1.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
|
| share | ReceivedShare | REQUIRED. The share. |
| Field | Type | Label | Description |
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
|
| ref | ShareReference | REQUIRED. The reference to which the action should be performed. |
| Field | Type | Label | Description |
| status | cs3.rpc.v1beta1.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
|
| share | Share | REQUIRED. The share. |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| 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 |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| 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 |
| Field | Type | Label | Description |
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
|
| ref | ShareReference | REQUIRED. The reference to which the action should be performed. |
| Field | Type | Label | Description |
| status | cs3.rpc.v1beta1.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
TODO(labkode): clean up display_name ? we'll use storage links for that.
| Field | Type | Label | Description |
| 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 |
| Field | Type | Label | Description |
| status | cs3.rpc.v1beta1.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
|
| share | ReceivedShare | REQUIRED. The updated share. |
| Field | Type | Label | Description |
| 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 |
REQUIRED.
| Field | Type | Label | Description |
| permissions | SharePermissions | Update the permissions. |
|
| display_name | string | Update the display name. |
| Field | Type | Label | Description |
| status | cs3.rpc.v1beta1.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
|
| share | Share | REQUIRED. The updated share. |
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 Name | Request Type | Response Type | Description |
| 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. |
Represents a filter to apply to the request.
| Field | Type | Label | Description |
| 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 |
|
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.
| Field | Type | Label | Description |
| 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. |
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.
| Field | Type | Label | Description |
| 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. |
A share grant specifies the share permissions
for a grantee.
| Field | Type | Label | Description |
| 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. |
A share id identifies uniquely a // share in the share provider namespace.
A ShareId MUST be unique inside the share provider.
| Field | Type | Label | Description |
| opaque_id | string | REQUIRED. The internal id used by service implementor to uniquely Collaboration the share in the internal implementation of the service. |
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")
| Field | Type | Label | Description |
| owner | cs3.identity.user.v1beta1.UserId | REQUIRED. |
|
| resource_id | cs3.storage.provider.v1beta1.ResourceId | REQUIRED. |
|
| grantee | cs3.storage.provider.v1beta1.Grantee | REQUIRED. |
The permissions for a share.
| Field | Type | Label | Description |
| permissions | cs3.storage.provider.v1beta1.ResourcePermissions | TODO(labkode): additional permissions for shares like re-sharing and denying |
The mechanism to identify a share
in the share provider namespace.
| Field | Type | Label | Description |
| id | ShareId | The id of the share. |
|
| key | ShareKey | The combination of fields that make the share unique. |
The filter to apply.
| Name | Number | Description |
| 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 |
The state of the share.
| Name | Number | Description |
| 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. |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| status | cs3.rpc.v1beta1.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
|
| share | PublicShare | REQUIRED. The created share. |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| 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 | OPTIONAL. The share password hash. |
| Name | Option |
| password_hash | true |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| status | cs3.rpc.v1beta1.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
|
| share | PublicShare | REQUIRED. The share. |
| Field | Type | Label | Description |
| 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. |
REQUIRED.
represents a filter to apply to the request.
| Field | Type | Label | Description |
| type | ListPublicSharesRequest.Filter.Type |
|
|
| resource_id | cs3.storage.provider.v1beta1.ResourceId |
|
|
| owner | cs3.identity.user.v1beta1.UserId |
|
|
| creator | cs3.identity.user.v1beta1.UserId |
|
| Field | Type | Label | Description |
| 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 |
| Field | Type | Label | Description |
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
|
| ref | PublicShareReference | REQUIRED. The reference to which the action should be performed. |
| Field | Type | Label | Description |
| status | cs3.rpc.v1beta1.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
| Field | Type | Label | Description |
| 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 |
|
REQUIRED.
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| status | cs3.rpc.v1beta1.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
|
| share | PublicShare | REQUIRED. The updated public share. |
REQUIRED.
| Name | Number | Description |
| TYPE_INVALID | 0 | |
| TYPE_RESOURCE_ID | 1 | |
| TYPE_OWNER | 2 | |
| TYPE_CREATOR | 3 |
REQUIRED.
| Name | Number | Description |
| TYPE_INVALID | 0 | |
| TYPE_PERMISSIONS | 1 | |
| TYPE_PASSWORD | 2 | |
| TYPE_EXPIRATION | 3 | |
| TYPE_DISPLAYNAME | 4 | |
| TYPE_DESCRIPTION | 5 | |
| TYPE_NOTIFYUPLOADS | 6 | |
| TYPE_NOTIFYUPLOADSEXTRARECIPIENTS | 7 |
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 Name | Request Type | Response Type | Description |
| 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. |
Defines the restrictions for the public share.
| Field | Type | Label | Description |
| 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. |
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.
| Field | Type | Label | Description |
| 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. |
The mechanism to authenticate a request to
GetPublicShareByToken.
| Field | Type | Label | Description |
| password | string | The password of the share. |
|
| signature | ShareSignature | The signature issued by GetPublicShareByToken. |
A share id identifies uniquely a // share in the share provider namespace.
A ShareId MUST be unique inside the share provider.
| Field | Type | Label | Description |
| opaque_id | string | REQUIRED. The internal id used by service implementor to uniquely identity the share in the internal implementation of the service. |
The permissions for a share.
| Field | Type | Label | Description |
| permissions | cs3.storage.provider.v1beta1.ResourcePermissions | TODO(labkode): additional permissions for shares like re-sharing |
The mechanism to identify a share
in the share provider namespace.
| Field | Type | Label | Description |
| id | PublicShareId | The id of the share. |
|
| token | string | The token to identify the public share. |
A time constrained token which can be used to
authenticate link share requests.
| Field | Type | Label | Description |
| signature | string | REQUIRED. The signature value. |
|
| signature_expiration | cs3.types.v1beta1.Timestamp | REQUIRED. The time until the signature becomes invalid. |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| token | string | REQUIRED. The unlisted token to identify the public share. |
| Field | Type | Label | Description |
| status | cs3.rpc.v1beta1.Status | REQUIRED. The response status. |
|
| share | Share | REQUIRED. The share. |
| Field | Type | Label | Description |
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
|
| ref | ShareReference | REQUIRED. The reference to which the action should be performed. |
| Field | Type | Label | Description |
| status | cs3.rpc.v1beta1.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
|
| share | Share | REQUIRED. The share. |
| Field | Type | Label | Description |
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
|
| ref | ShareReference | REQUIRED. The reference of the received share. |
| Field | Type | Label | Description |
| status | cs3.rpc.v1beta1.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
|
| share | ReceivedShare | REQUIRED. The share. |
| Field | Type | Label | Description |
| 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. |
REQUIRED.
represents a filter to apply to the request.
| Field | Type | Label | Description |
| type | ListOCMSharesRequest.Filter.Type | REQUIRED. |
|
| resource_id | cs3.storage.provider.v1beta1.ResourceId |
|
|
| owner | cs3.identity.user.v1beta1.UserId |
|
|
| creator | cs3.identity.user.v1beta1.UserId |
|
| Field | Type | Label | Description |
| 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 |
| Field | Type | Label | Description |
| 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. |
| Field | Type | Label | Description |
| 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 |
| Field | Type | Label | Description |
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
|
| ref | ShareReference | REQUIRED. The reference to which the action should be performed. |
| Field | Type | Label | Description |
| status | cs3.rpc.v1beta1.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
| Field | Type | Label | Description |
| opaque | cs3.types.v1beta1.Opaque | OPTIONAL. Opaque information. |
|
| ref | ShareReference | REQUIRED. |
|
| field | UpdateOCMShareRequest.UpdateField | repeated |
|
REQUIRED.
| Field | Type | Label | Description |
| expiration | cs3.types.v1beta1.Timestamp | Update the expiration. |
|
| access_methods | AccessMethod | Update access methods. |