| 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 reference to which the action should be performed. |
-
| from_ts | -cs3.types.v1beta1.Timestamp | -- | OPTIONAL. -SHOULD be specified. -The start time range to query for recycle items. -The value is the Unix Epoch timestamp in seconds. |
-
| to_ts | -cs3.types.v1beta1.Timestamp | -- | OPTIONAL. -SHOULD be specified. -The end time range to query for recycle items. -The value is Unix Epoch timestamp in seconds. |
-
| 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. |
-
| from_ts | -cs3.types.v1beta1.Timestamp | -- | OPTIONAL. -SHOULD be specified. -The start time range to query for recycle items. -The value is the Unix Epoch timestamp in seconds. |
-
| to_ts | -cs3.types.v1beta1.Timestamp | -- | OPTIONAL. -SHOULD be specified. -The end time range to query for recycle items. -The value is Unix Epoch timestamp in seconds. |
-
| 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 -when 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. |
-
| 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 |
| 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. |
-
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_PRECONDITION_FAILED if the container -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 | -ListRecycleStreamRequest | -.cs3.storage.provider.v1beta1.ListRecycleStreamResponse stream | -Returns a stream of recycle items for this storage provider. |
-
| ListRecycle | -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_PRECONDITION_FAILED if the source reference -cannot be moved to the destination reference. |
-
| PurgeRecycle | -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_PRECONDITION_FAILED 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. |
-
| 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 provider URL, which allows the user to open a resource in an online editor. - -*****************************************************************/ -************************ 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_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. |
-
| 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. |
-
| 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. - -*****************************************************************/ -******************** 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. - -*****************************************************************/ -************************** FILE TRANSFER ************************/ -*****************************************************************/ |
-
| CreateTransfer | -.cs3.tx.v1beta1.CreateTransferRequest | -.cs3.tx.v1beta1.CreateTransferResponse | -Returns a response containing a TxInfo (transfer info) object. |
-
| 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. |
-
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. |
-
| Field | Type | Label | Description |
| key | -string | -- | 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 | -string | -- | 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. |
-
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 |
-
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. |
-
| ref | -cs3.storage.provider.v1beta1.Reference | -- | REQUIRED. -Reference of the resource to be transfered. |
-
| status | -TxInfo.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. |
-
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 |
| ref | -cs3.storage.provider.v1beta1.Reference | -- | REQUIRED. -Reference of the resource to be transfered. |
-
| grantee | -cs3.storage.provider.v1beta1.Grantee | -- | REQUIRED. -The destination (receiver of the transfer) |
-
| 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. |
-
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 | -Creates (requests the destination to accept) a transfer. -Returns a response containing a TxInfo (transfer info) object. |
-
| GetTransferStatus | -GetTransferStatusRequest | -GetTransferStatusResponse | -Requests a transfer status. |
-
| CancelTransfer | -CancelTransferRequest | -CancelTransferResponse | -Requests to cancel 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 | -OpenInAppRequest.ViewMode | -- |
|
-
| 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. |
-
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. |
-
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 provider URL -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. |
-
| Field | Type | Label | Description |
| key | -string | -- |
|
-
| value | -string | -- |
|
-
| Field | Type | Label | Description |
| key | -string | -- |
|
-
| value | -string | -- |
|
-
| 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 | -ListSupportedMimeTypesResponse.MimeTypesEntry | -repeated | -REQUIRED. -The list of supported mime types with the apps which they can be opened with. |
-
| Field | Type | Label | Description |
| key | -string | -- |
|
-
| value | -AppProviderList | -- |
|
-
| 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 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. |
-
Holds a list of app providers which can open a particular mime type.
- - -| Field | Type | Label | Description |
| app_providers | -ProviderInfo | -repeated | -
|
-
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, tcp://localhost:1099. |
-
| name | -string | -- | OPTIONAL. -A human-readable name of the app provider. |
-
| description | -string | -- | OPTIONAL. -Information to describe the functionalities -offered by the app provider. 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 |
-
| 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. |
-
| provider | -ProviderInfo | -- | REQUIRED. -The auth provider 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 |
| GetAuthProvider | -GetAuthProviderRequest | -GetAuthProviderResponse | -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. |
-
| 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. |
-
| 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. |
-
| 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. |
-
| 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. |
-
| 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. |
-
| 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. |
-
| 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. |
-
https://rawgit.com/GEANT/OCM-API/v1/docs.html#null%2Fpaths%2F~1shares%2Fpost
- - -| 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). |
-
| provider_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 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. |
-
| protocol | -Protocol | -- | REQUIRED. -The protocol which is used to establish synchronisation. |
-
| 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. |
-
OCM Core API
The OCM Core API is the mapping in GRPC of the OCM core protocol.
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. |
-
The protocol which is used to establish synchronisation.
- - -| Field | Type | Label | Description |
| name | -string | -- | REQUIRED. -The name of the protocol to use. |
-
| opaque | -cs3.types.v1beta1.Opaque | -- | REQUIRED. -JSON object with protocol specific options, -e.g. uri, access_token, password, permissions etc. |
-
| 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. |
-
| 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. |
-
| 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. |
-
| 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. |
-
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 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. |
-
| ForwardInvite | -ForwardInviteRequest | -ForwardInviteResponse | -Forwards a received invite to the sync'n'share system provider. |
-
| AcceptInvite | -AcceptInviteRequest | -AcceptInviteResponse | -Completes an invitation acceptance. |
-
| GetAcceptedUser | -GetAcceptedUserRequest | -GetAcceptedUserResponse | -Retrieves details about a remote user who has accepted an invite to share. |
-
| FindAcceptedUsers | -FindAcceptedUsersRequest | -FindAcceptedUsersResponse | -Finds users who accepted invite tokens by their attributes. |
-
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. |
-
| 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. |
-
| Field | Type | Label | Description |
| opaque | -cs3.types.v1beta1.Opaque | -- | OPTIONAL. -Opaque information. |
-
| filters | -Filter | -repeated | -OPTIONAL. -The list of filters to apply if any. |
-
| 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. |
-
| 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. |
-
| ref | -ShareReference | -- | REQUIRED. |
-
| field | -UpdateReceivedShareRequest.UpdateField | -- |
|
-
REQUIRED.
The field to update.
- - -| Field | Type | Label | Description |
| display_name | -string | -- | Update the display name. |
-
| state | -ShareState | -- | Update the share state |
-
| 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. - -REQUIRED. |
-
| ref | -ShareReference | -- |
|
-
| field | -UpdateShareRequest.UpdateField | -- | REQUIRED. |
-
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_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 | -- |
|
-
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 path in case the share will be mounted
in a path in a storage provider.
- - -| Field | Type | Label | Description |
| share | -Share | -- | REQUIRED. |
-
| state | -ShareState | -- | REQUIRED. -The state 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. |
-
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. |
-
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 |
-
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 | -- |
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. |
-
| 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. |
-
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. |
-
| 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. |
-
| 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 | -- |
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. |
-
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. |
-
| grant | -ShareGrant | -- | REQUIRED. -The share grant for the share. |
-
| recipient_mesh_provider | -cs3.ocm.provider.v1beta1.ProviderInfo | -- | REQUIRED. -The details of the recipient user's mesh provider. |
-
| 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 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. |
-
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. |
-
| 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. |
-
| shares | -ReceivedShare | -repeated | -REQUIRED. -The list of received shares. |
-
| 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. - -REQUIRED. |
-
| ref | -ShareReference | -- | REQUIRED. |
-
| field | -UpdateOCMShareRequest.UpdateField | -- |
|
-
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. |
-
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. |
-
| ref | -ShareReference | -- | REQUIRED. |
-
| field | -UpdateReceivedOCMShareRequest.UpdateField | -- |
|
-
REQUIRED.
- - -| Field | Type | Label | Description |
| display_name | -string | -- | Update the display name. |
-
| state | -ShareState | -- | Update the share state |
-
| Field | Type | Label | Description |
| status | -cs3.rpc.v1beta1.Status | -- | REQUIRED. -The response status. |
-
| opaque | -cs3.types.v1beta1.Opaque | -- | OPTIONAL. -Opaque information. |
-
REQUIRED.
The filter to apply.
-| Name | Number | Description |
| TYPE_INVALID | -0 | -- |
| TYPE_NO | -1 | -- |
| TYPE_RESOURCE_ID | -2 | -- |
| TYPE_OWNER | -3 | -- |
| TYPE_CREATOR | -4 | -- |
| TYPE_OWNER_PROVIDER | -5 | -- |
| TYPE_CREATOR_PROVIDER | -6 | -- |
OCM Share Provider API
The OCM Share Provider API is meant to manipulate share
resources from the perspective of the creator or the share and
from the perspective of the receiver of the share.
The 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 |
| CreateOCMShare | -CreateOCMShareRequest | -CreateOCMShareResponse | -Creates a new ocm share. -MUST return CODE_NOT_FOUND if the resource reference does not exist. -MUST return CODE_ALREADY_EXISTS if the share already exists for the 4-tuple consisting of -(owner, shared_resource, grantee). -New shares MUST be created in the state SHARE_STATE_PENDING. |
-
| RemoveOCMShare | -RemoveOCMShareRequest | -RemoveOCMShareResponse | -Removes a share. -MUST return CODE_NOT_FOUND if the share reference does not exist. |
-
| GetOCMShare | -GetOCMShareRequest | -GetOCMShareResponse | -Gets share information for a single share. -MUST return CODE_NOT_FOUND if the share reference does not exist. |
-
| ListOCMShares | -ListOCMSharesRequest | -ListOCMSharesResponse | -List the shares the authenticated principal has created, -both as owner and creator. If a filter is specified, only -shares satisfying the filter MUST be returned. |
-
| UpdateOCMShare | -UpdateOCMShareRequest | -UpdateOCMShareResponse | -Updates a share. -MUST return CODE_NOT_FOUND if the share reference does not exist. |
-
| ListReceivedOCMShares | -ListReceivedOCMSharesRequest | -ListReceivedOCMSharesResponse | -List all shares the authenticated principal has received. |
-
| UpdateReceivedOCMShare | -UpdateReceivedOCMShareRequest | -UpdateReceivedOCMShareResponse | -Update the received share to change the share state or the display name. -MUST return CODE_NOT_FOUND if the share reference does not exist. |
-
| GetReceivedOCMShare | -GetReceivedOCMShareRequest | -GetReceivedOCMShareResponse | -Get the information for the given received share reference. -MUST return CODE_NOT_FOUND if the received share reference does not exist. |
-
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 path in case the share will be mounted
in a path in a storage provider.
- - -| Field | Type | Label | Description |
| share | -Share | -- | REQUIRED. |
-
| state | -ShareState | -- | REQUIRED. -The state 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. |
-
| name | -string | -- | REQUIRED. -Name 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. |
-
| share_type | -Share.ShareType | -- | Specifies the type 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. |
-
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. |
-
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 | -- |
|
-
| reshare | -bool | -- |
|
-
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. |
-
Defines the type of share based on its origin.
-| Name | Number | Description |
| SHARE_TYPE_INVALID | -0 | -- |
| SHARE_TYPE_REGULAR | -1 | -A regular file or folder share. |
-
| SHARE_TYPE_TRANSFER | -2 | -A file or folder transfer. |
-
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. |
-
| ref | -Reference | -- | REQUIRED. -The reference to which the action should be performed. |
-
| grant | -Grant | -- | REQUIRED. -The grant to be added. |
-
| 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 | -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. |
-
| 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. |
-
| Field | Type | Label | Description |
| opaque | -cs3.types.v1beta1.Opaque | -- | OPTIONAL. -Opaque information. |
-
| ref | -Reference | -- | REQUIRED. -The location where to store the reference. |
-
| target_uri | -string | -- | REQUIRED. -The reference resource by RFC3986. |
-
| 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. |
-
| owner | -cs3.identity.user.v1beta1.User | -- | REQUIRED. |
-
| type | -string | -- | OPTIONAL. -Could be 'home', 'share', 'project', 'space'... |
-
| name | -string | -- | OPTIONAL. -User readable name of the storage space. |
-
| quota | -Quota | -- | OPTIONAL. |
-
| Field | Type | Label | Description |
| opaque | -cs3.types.v1beta1.Opaque | -- | OPTIONAL. -Opaque information. |
-
| status | -cs3.rpc.v1beta1.Status | -- | REQUIRED. -The response status. |
-
| storage_space | -StorageSpace | -- | REQUIRED. -The created storage space. |
-
| Field | Type | Label | Description |
| opaque | -cs3.types.v1beta1.Opaque | -- | OPTIONAL. -Opaque information. |
-
| ref | -Reference | -- | REQUIRED. -The location where to store the symlink. |
-
| target | -string | -- | REQUIRED. -The link target can hold arbitrary text; if later resolved, -a relative link is interpreted in relation to its parent directory |
-
| 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 | -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. |
-
| Field | Type | Label | Description |
| opaque | -cs3.types.v1beta1.Opaque | -- | OPTIONAL. -Opaque information. |
-
| id | -StorageSpaceId | -- | REQUIRED. |
-
| Field | Type | Label | Description |
| opaque | -cs3.types.v1beta1.Opaque | -- | OPTIONAL. -Opaque information. |
-
| status | -cs3.rpc.v1beta1.Status | -- | REQUIRED. -The response status. |
-
| Field | Type | Label | Description |
| opaque | -cs3.types.v1beta1.Opaque | -- | OPTIONAL. -Opaque information. |
-
| ref | -Reference | -- | REQUIRED. -The reference to which the action should be performed. |
-
| grantee | -Grantee | -- | REQUIRED. -The grantee to remove permission. |
-
| 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. |
-
| path | -string | -- | REQUIRED. -The path to the home in a storage provider. -For example /eos/user/h/hugo in the storage provider with root path /eos/user/. |
-
| Field | Type | Label | Description |
| opaque | -cs3.types.v1beta1.Opaque | -- | OPTIONAL. -Opaque information. |
-
| resource_id | -ResourceId | -- | REQUIRED. -The resource id of the resource. |
-
| Field | Type | Label | Description |
| status | -cs3.rpc.v1beta1.Status | -- | REQUIRED. -The response status. |
-
| opaque | -cs3.types.v1beta1.Opaque | -- | OPTIONAL. -Opaque information. |
-
| path | -string | -- | REQUIRED. -The path of the resource. |
-
| 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. |
-
| total_bytes | -uint64 | -- | REQUIRED. -The total available bytes. |
-
| used_bytes | -uint64 | -- | REQUIRED. -The number of used bytes. |
-
| Field | Type | Label | Description |
| opaque | -cs3.types.v1beta1.Opaque | -- | OPTIONAL. -Opaque information. |
-
| ref | -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 |
| opaque | -cs3.types.v1beta1.Opaque | -- | OPTIONAL. -Opaque information. |
-
| ref | -Reference | -- | REQUIRED. -The reference to which the action should be performed. |
-
| if_not_exist | -bool | -- | OPTIONAL. -Whether the file is to be uploaded in exclusive mode. Defaults to false. -If true, the request SHALL be processed such that only one of multiple concurrent uploads -to the same target reference MAY succeed, whereas all others MUST fail with CODE_FAILED_PRECONDITION. -The semantic is similar to the O_CREAT|O_EXCL POSIX flags. -The request MUST return CODE_NOT_IMPLEMENTED if the provider does not support this mode. |
-
| if_match | -string | -- | OPTIONAL. -Whether the file is to be uploaded if the given etag matches. Default to always upload. -If the storage provider has a more recent etag for the target file, the request MUST -return CODE_FAILED_PRECONDITION. |
-
| 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 |
| opaque | -cs3.types.v1beta1.Opaque | -- | OPTIONAL. -Opaque information. |
-
| ref | -Reference | -- | REQUIRED. -The reference to which the action should be performed. |
-
| arbitrary_metadata_keys | -string | -repeated | -OPTIONAL. -Arbitrary metadata be included with the resource. -A key with the name '*' means to return all available arbitrary metadata. |
-
| Field | Type | Label | Description |
| status | -cs3.rpc.v1beta1.Status | -- | REQUIRED. -The response status. |
-
| opaque | -cs3.types.v1beta1.Opaque | -- | OPTIONAL. -Opaque information. |
-
| infos | -ResourceInfo | -repeated | -REQUIRED. -The list of resource informations. |
-
| Field | Type | Label | Description |
| opaque | -cs3.types.v1beta1.Opaque | -- | OPTIONAL. -Opaque information. |
-
| ref | -Reference | -- | REQUIRED. -The reference to which the action should be performed. |
-
| arbitrary_metadata_keys | -string | -repeated | -OPTIONAL. -Arbitrary metadata be included with the resource. -A key with the name '*' means to return all available arbitrary metadata. |
-
| Field | Type | Label | Description |
| status | -cs3.rpc.v1beta1.Status | -- | REQUIRED. -The response status. |
-
| opaque | -cs3.types.v1beta1.Opaque | -- | OPTIONAL. -Opaque information. |
-
| info | -ResourceInfo | -- | REQUIRED. -The resource information. |
-
| Field | Type | Label | Description |
| opaque | -cs3.types.v1beta1.Opaque | -- | OPTIONAL. -Opaque information. |
-
| ref | -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. |
-
| versions | -FileVersion | -repeated | -REQUIRED. -The list of file versions. |
-
| Field | Type | Label | Description |
| opaque | -cs3.types.v1beta1.Opaque | -- | OPTIONAL. -Opaque information. |
-
| ref | -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. |
-
| grants | -Grant | -repeated | -REQUIRED. -The grants. |
-
| Field | Type | Label | Description |
| opaque | -cs3.types.v1beta1.Opaque | -- | OPTIONAL. -Opaque information. |
-
| from_ts | -cs3.types.v1beta1.Timestamp | -- | OPTIONAL. -SHOULD be specified. -The start time range to query for recycle items. -The value is the Unix Epoch timestamp in seconds. |
-
| to_ts | -cs3.types.v1beta1.Timestamp | -- | OPTIONAL. -SHOULD be specified. -The end time range to query for recycle items. -The value is Unix Epoch timestamp in seconds. |
-
| ref | -Reference | -- | OPTIONAL. -The reference to which the action should be performed. |
-
| Field | Type | Label | Description |
| status | -cs3.rpc.v1beta1.Status | -- | REQUIRED. -The response status. |
-
| opaque | -cs3.types.v1beta1.Opaque | -- | OPTIONAL. -Opaque information. |
-
| recycle_items | -RecycleItem | -repeated | -REQUIRED. -The list of recycle items. |
-
| Field | Type | Label | Description |
| opaque | -cs3.types.v1beta1.Opaque | -- | OPTIONAL. -Opaque information. |
-
| from_ts | -cs3.types.v1beta1.Timestamp | -- | OPTIONAL. -SHOULD be specified. -The start time range to query for recycle items. -The value is the Unix Epoch timestamp in seconds. |
-
| to_ts | -cs3.types.v1beta1.Timestamp | -- | OPTIONAL. -SHOULD be specified. -The end time range to query for recycle items. -The value is Unix Epoch timestamp in seconds. |
-
| ref | -Reference | -- | OPTIONAL. -The reference to which the action should be performed. |
-
| Field | Type | Label | Description |
| status | -cs3.rpc.v1beta1.Status | -- | REQUIRED. -The response status. |
-
| opaque | -cs3.types.v1beta1.Opaque | -- | OPTIONAL. -Opaque information. |
-
| recycle_item | -RecycleItem | -- | REQUIRED. -The recycle items. |
-
| Field | Type | Label | Description |
| opaque | -cs3.types.v1beta1.Opaque | -- | OPTIONAL. -Opaque information. |
-
| filters | -ListStorageSpacesRequest.Filter | -repeated | -OPTIONAL. -The list of filters to apply if any. |
-
Represents a filter to apply to the request.
- - -| Field | Type | Label | Description |
| type | -ListStorageSpacesRequest.Filter.Type | -- | REQUIRED. |
-
| id | -StorageSpaceId | -- |
|
-
| owner | -cs3.identity.user.v1beta1.UserId | -- |
|
-
| space_type | -string | -- |
|
-
| Field | Type | Label | Description |
| opaque | -cs3.types.v1beta1.Opaque | -- | OPTIONAL. -Opaque information. |
-
| status | -cs3.rpc.v1beta1.Status | -- | REQUIRED. -The response status. |
-
| storage_spaces | -StorageSpace | -repeated | -REQUIRED. |
-
| Field | Type | Label | Description |
| opaque | -cs3.types.v1beta1.Opaque | -- | OPTIONAL. -Opaque information. |
-
| source | -Reference | -- | REQUIRED. -The source reference the resource is moved from. |
-
| destination | -Reference | -- | REQUIRED. -The destination reference the resource is moved to. |
-
| 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 | -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. |
-
| Field | Type | Label | Description |
| opaque | -cs3.types.v1beta1.Opaque | -- | OPTIONAL. -Opaque information. |
-
| ref | -Reference | -- | REQUIRED. -The reference to which the action should be performed. |
-
| grant | -Grant | -- | REQUIRED. -The grant to remove. |
-
| 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 | -Reference | -- | REQUIRED. -The reference to which the action should be performed. |
-
| key | -string | -- | REQUIRED. -The key to restore a specific file version. |
-
| Field | Type | Label | Description |
| status | -cs3.rpc.v1beta1.Status | -- | REQUIRED. -The response status. |
-
| opaque | -cs3.types.v1beta1.Opaque | -- | OPTIONAL. -Opaque information. |
-
TODO: restore to original location if not specified as OPTIONAL?
- - -| Field | Type | Label | Description |
| opaque | -cs3.types.v1beta1.Opaque | -- | OPTIONAL. -Opaque information. |
-
| ref | -Reference | -- | REQUIRED. -The reference to which the action should be performed. |
-
| key | -string | -- | REQUIRED. -The key for the recycle item to be restored. |
-
| restore_ref | -Reference | -- | OPTIONAL. -An optional restore path for the deleted resource. -It can be useful to restore to another location rather than -the original. -If empty, service implementors MUST restore -to original location if possible. |
-
| 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 | -Reference | -- | REQUIRED. -The reference to which the action should be performed. |
-
| arbitrary_metadata | -ArbitraryMetadata | -- | REQUIRED. -The arbitrary metadata to add to the resource. |
-
| 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 | -Reference | -- | REQUIRED. -The reference to which the action should be performed. |
-
| arbitrary_metadata_keys | -string | -repeated | -OPTIONAL. -Arbitrary metadata be included with the resource. -A key with the name '*' means to return all available arbitrary metadata. |
-
| Field | Type | Label | Description |
| status | -cs3.rpc.v1beta1.Status | -- | REQUIRED. -The response status. |
-
| opaque | -cs3.types.v1beta1.Opaque | -- | OPTIONAL. -Opaque information. |
-
| info | -ResourceInfo | -- | REQUIRED. -The resource information. |
-
| Field | Type | Label | Description |
| opaque | -cs3.types.v1beta1.Opaque | -- | OPTIONAL. -Opaque information. |
-
| ref | -Reference | -- | REQUIRED. -The reference to which the action should be performed. |
-
| arbitrary_metadata_keys | -string | -repeated | -REQUIRED. -The arbitrary metadata to delete. |
-
| 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 | -Reference | -- | REQUIRED. -The reference to which the action should be performed. |
-
| grant | -Grant | -- | REQUIRED. -The grant to be updated. |
-
| 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. |
-
| storage_space | -StorageSpace | -- | REQUIRED. |
-
| Field | Type | Label | Description |
| opaque | -cs3.types.v1beta1.Opaque | -- | OPTIONAL. -Opaque information. |
-
| status | -cs3.rpc.v1beta1.Status | -- | REQUIRED. -The response status. |
-
| storage_space | -StorageSpace | -- | REQUIRED. -The updated storage space. |
-
The filter to apply.
-| Name | Number | Description |
| TYPE_INVALID | -0 | -- |
| TYPE_NO | -1 | -- |
| TYPE_ID | -2 | -- |
| TYPE_OWNER | -3 | -- |
| TYPE_SPACE_TYPE | -4 | -- |
Storage Provider API
The Storage Provider API is meant to manipulate storage
resources in the underlying storage system behind the service.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
RFC 2119.
The following are global requirements that apply to all methods:
Any method MUST return CODE_OK on a succesful operation.
Any method MAY return NOT_IMPLEMENTED.
Any method MAY return INTERNAL.
Any method MAY return UNKNOWN.
Any method MAY return UNAUTHENTICATED.
-| Method Name | Request Type | Response Type | Description |
| AddGrant | -AddGrantRequest | -AddGrantResponse | -Adds a new grant for the provided reference. -MUST return CODE_NOT_FOUND if the reference does not exist |
-
| CreateContainer | -CreateContainerRequest | -CreateContainerResponse | -Creates a new resource of type container. -MUST return CODE_PRECONDITION_FAILED if the container -cannot be created at the specified reference. |
-
| Delete | -DeleteRequest | -DeleteResponse | -Deletes a resource. -If a resource specifies the non-empty container (directory, ...), -then the entire directory is deleted recursively. -If a resource specifies a reference or symlink type, only the reference is removed (not the target). -MUST return CODE_NOT_FOUND if the reference does not exist. |
-
| DenyGrant | -DenyGrantRequest | -DenyGrantResponse | -Denies access to the provided reference. -MUST return CODE_NOT_FOUND if the reference does not exist |
-
| GetPath | -GetPathRequest | -GetPathResponse | -Returns the path reference for -the provided resource id reference. -MUST return CODE_NOT_FOUND if the reference does not exist |
-
| GetQuota | -GetQuotaRequest | -GetQuotaResponse | -Returns the quota available under the provided -reference. -MUST return CODE_NOT_FOUND if the reference does not exist -MUST return CODE_RESOURCE_EXHAUSTED on exceeded quota limits. |
-
| InitiateFileDownload | -InitiateFileDownloadRequest | -InitiateFileDownloadResponse | -Initiates the download of a file using an -out-of-band data transfer mechanism. |
-
| InitiateFileUpload | -InitiateFileUploadRequest | -InitiateFileUploadResponse | -Initiates the upload of a file using an -out-of-band data transfer mechanism. |
-
| ListGrants | -ListGrantsRequest | -ListGrantsResponse | -Returns the list of grants for the provided reference. -MUST return CODE_NOT_FOUND if the reference does not exists. |
-
| ListContainerStream | -ListContainerStreamRequest | -ListContainerStreamResponse stream | -Returns a stream of resource informations -for the provided reference. -MUST return CODE_NOT_FOUND if the reference does not exists. |
-
| ListContainer | -ListContainerRequest | -ListContainerResponse | -Returns a list of resource information -for the provided reference. -MUST return CODE_NOT_FOUND if the reference does not exists. |
-
| ListFileVersions | -ListFileVersionsRequest | -ListFileVersionsResponse | -Returns a list of the versions for a resource of -type file at the provided reference. -MUST return CODE_NOT_FOUND if the reference does not exist. -MUST return CODE_OK and MUST return an empty list if no versions are available. -TODO: What code if resource not of type file? |
-
| ListRecycleStream | -ListRecycleStreamRequest | -ListRecycleStreamResponse stream | -Returns a stream of recycle items for this storage provider. |
-
| ListRecycle | -ListRecycleRequest | -ListRecycleResponse | -Returns a list of recycle items for this storage provider. -MUST return CODE_OK and MUST return an empty list if no recycle items are available. |
-
| Move | -MoveRequest | -MoveResponse | -Moves a resource from one reference to another. -MUST return CODE_NOT_FOUND if any of the references do not exist. -MUST return CODE_PRECONDITION_FAILED if the source reference -cannot be moved to the destination reference. |
-
| RemoveGrant | -RemoveGrantRequest | -RemoveGrantResponse | -Removes a grant for the provided reference. -This is recursive and atomic for directories. Does not follow references. -MUST return CODE_NOT_FOUND if the reference does not exist. -MUST return CODE_NOT_FOUND if grant does not exist. |
-
| PurgeRecycle | -PurgeRecycleRequest | -PurgeRecycleResponse | -Permanently removes a recycle item from the recycle. -This operation is irrevocable. -MUST return CODE_NOT_FOUND if the recycle item id does not exist. |
-
| RestoreFileVersion | -RestoreFileVersionRequest | -RestoreFileVersionResponse | -Restores a file version for the provided reference. -MUST return CODE_NOT_FOUND if the reference does not exist. -MUST return CODE_NOT_FOUND if the version does not exist. |
-
| RestoreRecycleItem | -RestoreRecycleItemRequest | -RestoreRecycleItemResponse | -Restores a recycle item from the recycle. -MUST return CODE_NOT_FOUND if the recycle item id does not exist. -MUST return CODE_PRECONDITION_FAILED if the restore_path is non-empty -and the recycle item cannot be restored to the restore_path. |
-
| Stat | -StatRequest | -StatResponse | -Returns the resource information at the provided reference. -MUST return CODE_NOT_FOUND if the reference does not exist. |
-
| UpdateGrant | -UpdateGrantRequest | -UpdateGrantResponse | -Updates an ACL for the provided reference. -MUST return CODE_NOT_FOUND if the reference does not exist. -MUST return CODE_PRECONDITION_FAILED if the acl does not exist. |
-
| CreateSymlink | -CreateSymlinkRequest | -CreateSymlinkResponse | -Creates a symlink to another resource. |
-
| CreateReference | -CreateReferenceRequest | -CreateReferenceResponse | -Creates a reference to another resource in the same cluster or another domain (OCM shares). -The references resource can be accessed by the protocol specificied in the request message. |
-
| SetArbitraryMetadata | -SetArbitraryMetadataRequest | -SetArbitraryMetadataResponse | -Sets arbitrary metadata into a storage resource. -Arbitrary metadata is returned in a cs3.storageprovider.v1beta1.ResourceInfo. |
-
| UnsetArbitraryMetadata | -UnsetArbitraryMetadataRequest | -UnsetArbitraryMetadataResponse | -Unsets arbitrary metdata into a storage resource. -Arbitrary metadata is returned in a cs3.storageprovider.v1beta1.ResourceInfo. |
-
| CreateHome | -CreateHomeRequest | -CreateHomeResponse | -Creates the home directory for a user. |
-
| GetHome | -GetHomeRequest | -GetHomeResponse | -Gets the home path for the user. |
-
| CreateStorageSpace | -CreateStorageSpaceRequest | -CreateStorageSpaceResponse | -Creates a storage space. |
-
| ListStorageSpaces | -ListStorageSpacesRequest | -ListStorageSpacesResponse | -Lists storage spaces. |
-
| UpdateStorageSpace | -UpdateStorageSpaceRequest | -UpdateStorageSpaceResponse | -Updates a storage space. |
-
| DeleteStorageSpace | -DeleteStorageSpaceRequest | -DeleteStorageSpaceResponse | -Deletes a storage space. |
-
Arbitrary metadata than can be set to the resource.
- - -| Field | Type | Label | Description |
| metadata | -ArbitraryMetadata.MetadataEntry | -repeated | -
|
-
| Field | Type | Label | Description |
| key | -string | -- |
|
-
| value | -string | -- |
|
-
CanonicalMetadata contains extra metadata
attached to a resource. This message and the Opaque
message differ in that Opaque allows service implementors
to include any extra metadata in any format and most clients
will ignore it. However, the CanonicalMetadata message
contains well defined fileds that clients MUST understand if
they are specified.
- - -| Field | Type | Label | Description |
| target | -Reference | -- | REQUIRED if resource type is RESOURCE_TYPE_REFERENCE. -The target reference the resource points to. - -TODO(moscicki): what fields can fit here? executable bit? -bool executable = 2; -TODO(labkode): at some points maybe we could add here -acls and other well-known metadata. |
-
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. |
-
| expose | -bool | -- | REQUIRED. -Tells to the gateway if the client should be exposed directly to the download_endpoint. |
-
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 | -ResourceChecksumPriority | -repeated | -REQUIRED. -List of available checksums -the client can use when sending -the file. |
-
| expose | -bool | -- | REQUIRED. -Tells to the gateway if the client should be exposed directly to the upload_endpoint. |
-
The information for a file version.
TODO(labkode): make size and mtime OPTIONAL?
- - -| Field | Type | Label | Description |
| opaque | -cs3.types.v1beta1.Opaque | -- | OPTIONAL. -Opaque information. |
-
| key | -string | -- | MUST the specified. -The key to identify the version. |
-
| size | -uint64 | -- | REQUIRED. -The size in bytes of the file version. |
-
| mtime | -uint64 | -- | REQUIRED. -The Unix Epoch timestamp in seconds. |
-
| etag | -string | -- | REQUIRED. -As decribed in https://tools.ietf.org/html/rfc7232#section-2.3 -For a file version, the etag does not change because a version is immutable. |
-
A grant grants permissions
to a resource to a grantee.
- - -| Field | Type | Label | Description |
| grantee | -Grantee | -- | REQUIRED. -The grantee of the grant. |
-
| permissions | -ResourcePermissions | -- | REQUIRED. -The permissions for the grant. |
-
A grantee is the receiver of a grant.
- - -| Field | Type | Label | Description |
| type | -GranteeType | -- | REQUIRED. -The type of the grantee. |
-
| user_id | -cs3.identity.user.v1beta1.UserId | -- | The user id. |
-
| group_id | -cs3.identity.group.v1beta1.GroupId | -- | The group id. |
-
| opaque | -cs3.types.v1beta1.Opaque | -- | OPTIONAL. -Opaque information such as UID or GID. |
-
Represents a quota for a storage space.
- - -| Field | Type | Label | Description |
| opaque | -cs3.types.v1beta1.Opaque | -- | OPTIONAL. -Opaque information. |
-
| quota_max_bytes | -uint64 | -- | OPTIONAL. -The bytes quota for the user. |
-
| quota_max_files | -uint64 | -- | OPTIONAL. -The files quota for the user. |
-
A recycle item represents the information
of a deleted resource.
- - -| Field | Type | Label | Description |
| opaque | -cs3.types.v1beta1.Opaque | -- | OPTIONAL. -Opaque information. |
-
| type | -ResourceType | -- | REQUIRED. -The type of the resource. |
-
| key | -string | -- | REQUIRED. -The key to identify the deleted resource. |
-
| ref | -Reference | -- | REQUIRED. -The original reference of the deleted resource. |
-
| size | -uint64 | -- | OPTIONAL. -The size of the deleted resource. |
-
| deletion_time | -cs3.types.v1beta1.Timestamp | -- | REQUIRED. -The deletion time of the resource -in Unix Epoch timestamp in seconds. |
-
The mechanism to identify a resource in the CS3 namespace.
It can represent path based, id based and combined references:
The storage registry uses the storage_id to determine the responsible storage provider.
When the storage_id is not available it will use the path.
In a URL the different components can be represented in a string using the following layout:
| Field | Type | Label | Description |
| resource_id | -ResourceId | -- | OPTIONAL |
-
| path | -string | -- | OPTIONAL. -When starting with `/` represents an absolute path. In this case the resource_id MUST be empty. -When starting with `.` represents a path relative to the resource_id. The resource_id MUST be given. -When path is empty the resource_id must be set. Used to look up the path for a resource_id. |
-
The checksum to verify
the integrity of a resource.
- - -| Field | Type | Label | Description |
| type | -ResourceChecksumType | -- | REQUIRED. -The type of checksum to use. -If no checksum is provided, -type MUST be RESOURCE_CHECKSUM_TYPE_UNSET. |
-
| sum | -string | -- | MUST be specified if type is not -RESOURCE_CHECKSUM_TYPE_UNSET or type is not -RESOURCE_CHECKSUM_TYPE_INVALID. -MUST be the hexadecimal representation of the cheksum. -The value is case-insensitive, so -"1E603A8", "1e603a8" or "1e603A8" are the same. |
-
When negotiating the user of checksum types
between client and server, this structure
defines the priority of the checksum.
Priority 0 means highest priority.
- - -| Field | Type | Label | Description |
| type | -ResourceChecksumType | -- |
|
-
| priority | -uint32 | -- |
|
-
A resource id uniquely identifies a
resource in the storage provider namespace.
A ResourceId MUST be unique in the storage provider.
- - -| Field | Type | Label | Description |
| storage_id | -string | -- | REQUIRED. -The logical id of a storage. Used by the storage -registry to determine the responsible storage provider. |
-
| opaque_id | -string | -- | REQUIRED. -The internal id used by service implementor to -uniquely identity the resource in the internal -implementation of the service. |
-
Represents the information (metadata) about
a storage resource organized in a hierarchical namespace (file, directory/container, reference, symlink, ...).
- - -| Field | Type | Label | Description |
| opaque | -cs3.types.v1beta1.Opaque | -- | OPTIONAL. -Opaque information. |
-
| type | -ResourceType | -- | REQUIRED. -The type of the resource (container, file, ...) -See the enum ResourceType for all possible types. |
-
| id | -ResourceId | -- | REQUIRED. -Opaque unique identifier of the resource. |
-
| checksum | -ResourceChecksum | -- | REQUIRED. -The data checksum for the file resource. -For all other resources, the checksum is unset. |
-
| etag | -string | -- | REQUIRED. -As decribed in https://tools.ietf.org/html/rfc7232#section-2.3 -For file resources, the etag must change if data or metadata changes. -For container types, the etag must change if etag of any of the (indirectly) contained resources change. -For reference types, the etag must change if etag of the target changes and the target is on the same storage provider. -In all other cases the etag does not change. |
-
| mime_type | -string | -- | REQUIRED. -As described in [RFC 2015](https://tools.ietf.org/html/rfc2045#page-7) |
-
| mtime | -cs3.types.v1beta1.Timestamp | -- | REQUIRED. -Last modification time (mtime) of file or directory contents. -For reference types this is NOT the mtime of the target. |
-
| path | -string | -- | REQUIRED. -The path for the resource: -MUST start with `/` when the reference had no resource_id, indicating an absolute path. -MUST start with `.` when the reference had a resource_id, indicating a relative path. |
-
| permission_set | -ResourcePermissions | -- | REQUIRED. -The set of permissions for the resource effective for the authenticated user. |
-
| size | -uint64 | -- | REQUIRED. -The size of the resource in bytes (file size) -TODO(moscicki): This is undefined for container type. -Is the accounting recursive?, could it be set to 0 for directories if recursive not supported? use another field? -TODO(moscicki): This needs to be defined also for other types (such as a symlink to a directory or file) |
-
| owner | -cs3.identity.user.v1beta1.UserId | -- | REQUIRED: -Identifier of the owner of the resource. |
-
| target | -string | -- | REQUIRED if ResourceType is either RESOURCE_TYPE_SYMLINK or RESOURCE_TYPE_REFERENCE |
-
| canonical_metadata | -CanonicalMetadata | -- | OPTIONAL. -Additional metadata attached to the resource. -If resource type is RESOURCE_TYPE_REFERENCE it MUST -be specified. |
-
| arbitrary_metadata | -ArbitraryMetadata | -- | OPTIONAL. -Arbitrary metadata attached to a resource. |
-
The representation of permissions attached to a resource.
- - -| Field | Type | Label | Description |
| add_grant | -bool | -- |
|
-
| create_container | -bool | -- |
|
-
| delete | -bool | -- |
|
-
| get_path | -bool | -- |
|
-
| get_quota | -bool | -- |
|
-
| initiate_file_download | -bool | -- |
|
-
| initiate_file_upload | -bool | -- |
|
-
| list_grants | -bool | -- |
|
-
| list_container | -bool | -- |
|
-
| list_file_versions | -bool | -- |
|
-
| list_recycle | -bool | -- |
|
-
| move | -bool | -- |
|
-
| remove_grant | -bool | -- |
|
-
| purge_recycle | -bool | -- |
|
-
| restore_file_version | -bool | -- |
|
-
| restore_recycle_item | -bool | -- |
|
-
| stat | -bool | -- |
|
-
| update_grant | -bool | -- |
|
-
| deny_grant | -bool | -- |
|
-
Represents a storage space which could be a 'home', 'share' etc...
- - -| Field | Type | Label | Description |
| opaque | -cs3.types.v1beta1.Opaque | -- | OPTIONAL. -Opaque information. |
-
| id | -StorageSpaceId | -- | REQUIRED. |
-
| owner | -cs3.identity.user.v1beta1.User | -- | OPTIONAL. |
-
| root | -ResourceId | -- | OPTIONAL. -The root resource id of the storage space. |
-
| name | -string | -- | OPTIONAL. |
-
| quota | -Quota | -- | OPTIONAL. |
-
| space_type | -string | -- | OPTIONAL. -Could be 'home', 'share', 'project', 'space'... |
-
| mtime | -cs3.types.v1beta1.Timestamp | -- | OPTIONAL. -Last modification time (mtime) of the root resource of this storage space. |
-
The id of a storage space.
- - -| Field | Type | Label | Description |
| opaque_id | -string | -- | REQUIRED. -The internal storage space id. |
-
The type of the grantee.
-| Name | Number | Description |
| GRANTEE_TYPE_INVALID | -0 | -- |
| GRANTEE_TYPE_USER | -1 | -This type represents an individual. |
-
| GRANTEE_TYPE_GROUP | -2 | -This type represents a group of individuals. |
-
The type of checksum to use.
-| Name | Number | Description |
| RESOURCE_CHECKSUM_TYPE_INVALID | -0 | -- |
| RESOURCE_CHECKSUM_TYPE_UNSET | -1 | -unset means no checksum is set. |
-
| RESOURCE_CHECKSUM_TYPE_ADLER32 | -2 | -Use Adler32 checksum. |
-
| RESOURCE_CHECKSUM_TYPE_MD5 | -3 | -Use MD5 checksum. |
-
| RESOURCE_CHECKSUM_TYPE_SHA1 | -4 | -Use SHA-1 checksum. |
-
The available types of resources.
-| Name | Number | Description |
| RESOURCE_TYPE_INVALID | -0 | -- |
| RESOURCE_TYPE_FILE | -1 | -The file type represents a type -that holds arbitrary data. -Service implementors usually map this type -to files (local filesystem) or objects -(Amazon S3). |
-
| RESOURCE_TYPE_CONTAINER | -2 | -The container type represents a type -that can contain another types. -Service implementors usually map this type -to folders (local filesystem) or buckets -(Amazon S3). |
-
| RESOURCE_TYPE_REFERENCE | -3 | -This represents a reference type which points -to another resource where client MAY be redirected. -Client SHOULD use the ResourceInfo.target -reference for a subsequent call. |
-
| RESOURCE_TYPE_SYMLINK | -4 | -This represents a symbolic link type if the underlying -storage system supports it. -Symlink target SHOULD NOT be interpreted by the clients. |
-
| RESOURCE_TYPE_INTERNAL | -5 | -Internal resource type for some specific resources inside -a storage implementation. -For example, this type could be used to represent -a device file on a Linux filesystem. -Another example could be to represent an ongoing upload, -where an hypothetically user interface could show a loading icon -on this type of resources until the upload operation is completed. -Internal resources SHOULD NOT be moved to a different storage -provider. |
-
| 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. |
-
| provider | -ProviderInfo | -- | REQUIRED. -The storage provider for the user home. |
-
| Field | Type | Label | Description |
| opaque | -cs3.types.v1beta1.Opaque | -- | OPTIONAL. -Opaque information. |
-
| ref | -cs3.storage.provider.v1beta1.Reference | -- | REQUIRED. -The reference for the resource. |
-
| 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 storage providers handling the requested storage resource. |
-
| 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 storage providers this registry knows about. |
-
Storage Registry API
The Storage Registry API is meant to as registry to obtain
information of available storage providers.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
RFC 2119.
The following are global requirements that apply to all methods:
Any method MUST return CODE_OK on a succesful operation.
Any method MAY return NOT_IMPLEMENTED.
Any method MAY return INTERNAL.
Any method MAY return UNKNOWN.
Any method MAY return UNAUTHENTICATED.
-| Method Name | Request Type | Response Type | Description |
| GetStorageProviders | -GetStorageProvidersRequest | -GetStorageProvidersResponse | -Returns the storage provider that is reponsible for the given -resource reference. -MUST return CODE_NOT_FOUND if the reference does not exist. |
-
| ListStorageProviders | -ListStorageProvidersRequest | -ListStorageProvidersResponse | -Returns a list of the available storage providers known by this registry. |
-
| GetHome | -GetHomeRequest | -GetHomeResponse | -Gets the user home storage provider. - -TODO(labkode): missing methods for adding and removing a storage provider -with different visibility levels (system-wide, user-wide, group-wide)... |
-
The information for the storage 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_id | -string | -- | REQUIRED. -The storage provider id that will become part of the -resource id. -For example, if the provider_id is "home", resources obtained -from this storage provider will have a resource id like "home:1234". |
-
| provider_path | -string | -- | REQUIRED. -The public path prefix this storage provider handles. -In Unix literature, the mount path. -For example, if the provider_path is "/home", resources obtained -from this storage provier will have a resource path lik "/home/docs". |
-
| address | -string | -- | REQUIRED. -The address where the storage provider can be reached. -For example, tcp://localhost:1099. |
-
| description | -string | -- | OPTIONAL. -Information to describe the functionalities -offered by the storage provider. Meant to be read -by humans. |
-
| features | -ProviderInfo.Features | -- | REQUIRED. -List of available methods. |
-
REQUIRED.
Represents the list of features available
on this storage provider. If the feature is not supported,
the related service methods MUST return CODE_UNIMPLEMENTED.
- - -| Field | Type | Label | Description |
| recycle | -bool | -- |
|
-
| file_versions | -bool | -- |
|
-
| .proto Type | Notes | C++ Type | Java Type | Python Type |
| double | -- | double | -double | -float | -
| float | -- | float | -float | -float | -
| int32 | -Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | -int32 | -int | -int | -
| int64 | -Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | -int64 | -long | -int/long | -
| uint32 | -Uses variable-length encoding. | -uint32 | -int | -int/long | -
| uint64 | -Uses variable-length encoding. | -uint64 | -long | -int/long | -
| sint32 | -Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | -int32 | -int | -int | -
| sint64 | -Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | -int64 | -long | -int/long | -
| fixed32 | -Always four bytes. More efficient than uint32 if values are often greater than 2^28. | -uint32 | -int | -int | -
| fixed64 | -Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | -uint64 | -long | -int/long | -
| sfixed32 | -Always four bytes. | -int32 | -int | -int | -
| sfixed64 | -Always eight bytes. | -int64 | -long | -int/long | -
| bool | -- | bool | -boolean | -boolean | -
| string | -A string must always contain UTF-8 encoded or 7-bit ASCII text. | -string | -String | -str/unicode | -
| bytes | -May contain any arbitrary sequence of bytes. | -string | -ByteString | -str | -