Protocol Documentation

The resource can be opened but not downloaded.

The resource can be downloaded.

The resource can be downloaded and updated. The underlying application MUST be a fully capable editor to support this mode.

The resource can be downloaded and updated, but must be shown in preview mode. If the underlying application does not support a preview mode, or if in a view-only mode users are not allowed to switch to edit mode, then this mode MUST fall back to READ_WRITE.

Authenticates a user.

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

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

ListAppPasswords lists the application passwords created by a user.

InvalidateAppPassword invalidates a generated password.

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

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

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

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.

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

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.

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

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

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

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

Returns a list of the versions for a resource of type file at the provided reference. MUST return CODE_NOT_FOUND if the reference does not exist. MUST return CODE_OK and MUST return an empty list if no versions are available. TODO: What code if resource not of type file?

Returns a stream of recycle items for this storage provider.

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.

Moves a resource from one reference to another. MUST return CODE_NOT_FOUND if any of the references do not exist. MUST return CODE_FAILED_PRECONDITION if the source reference cannot be moved to the destination reference.

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.

Restores a file version for the provided reference. MUST return CODE_NOT_FOUND if the reference does not exist. MUST return CODE_NOT_FOUND if the version does not exist.

Restores a recycle item from the recycle. MUST return CODE_NOT_FOUND if the recycle item id does not exist. MUST return CODE_FAILED_PRECONDITION if the restore_path is non-empty and the recycle item cannot be restored to the restore_path.

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

Creates a symlink to another resource.

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

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

Locks a storage resource. MUST return CODE_NOT_FOUND if the reference does not exist. MUST return CODE_FAILED_PRECONDITION if the reference is already locked. In addition, the implementation MUST ensure atomicity when multiple users concurrently attempt to set a lock. The caller MUST have write permissions on the resource.

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

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

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

Creates the home directory for a user.

Creates a storage space.

Lists storage spaces.

Updates a storage space.

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

Returns the App URL and all necessary info to open a resource in an online editor. MUST return CODE_NOT_FOUND if the resource does not exist. *****************************************************************/ ************************ USER SHARE PROVIDER ********************/ *****************************************************************/

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

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

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

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.

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

List all shares the authproviderenticated principal has received.

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.

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

Maps the key-value pair.

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

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.

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

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

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

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.

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

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.

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

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

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

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.

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

List all shares the authproviderenticated principal has received.

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.

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

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

Registers a new app provider to the registry.

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

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

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

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

Gets the information about a user by the user id.

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

Gets the groups of a user.

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

Gets the information about a group by the group id.

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

Gets the members of a group.

Tells if the group has a certain member.

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

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

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

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

Lists the valid tokens generated by the user.

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

Completes an invitation acceptance.

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

Finds users who accepted invite tokens by their attributes.

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

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

Get the information of the provider identified by a specific domain. MUST return CODE_NOT_FOUND if the sync'n'share system provider does not exist.

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

Creates a new OCM share.

Updates an OCM share.

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

Requests creation of a transfer.

Requests a transfer status.

Requests to cancel a transfer.

Requests a list of transfers received by the authenticated principle.

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

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

CheckPermission defines a method to check permission/role.

Maps the key-value pair.

Returns the value associated with the requested key.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The destination could not be found.

A new data transfer

The data transfer is awaiting acceptance from the destination

The data transfer is accepted by the destination.

The data transfer has started and not yet completed.

The data transfer has completed.

The data transfer has failed.

The data transfer had been cancelled.

The request for cancelling the data transfer has failed.

The transfer has expired somewhere down the line.

Requests creation of a transfer. Returns a CreateTransferResponse.

Requests a transfer status.

Requests to cancel a transfer.

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

Requests retrying a transfer.

Create a group.

Delete a group.

Add a user to a group.

Remove a user from a group.

Create a user account.

Delete a user account.

Returns the App URL and all necessary info to open a resource in an online editor. MUST return CODE_NOT_FOUND if the resource does not exist.

The app URL is to be opened within an iframe

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

The resource can be opened but not downloaded.

The resource can be downloaded.

The resource can be downloaded and updated. The underlying application MUST be a fully capable editor to support this mode.

The resource can be downloaded and updated, but must be shown in preview mode. If the underlying application does not support a preview mode, or if in a view-only mode users are not allowed to switch to edit mode, then this mode MUST fall back to READ_WRITE.

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

Registers a new app provider to the registry.

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

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

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

Sets the default app provider for a specified mime type.

The app is a simple viewer.

The app is a full editor.

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

ListAppPasswords lists the application passwords created by a user.

InvalidateAppPassword invalidates a generated password.

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

Authenticate authenticates a client.

Used for invalid roles

Grants owner permissions on a resource

Provides backwards compatibility

Grants non-editor role on a resource

Grants editor permission on a resource, including folders

Grants editor permission on a single file

Grants co-owner permissions on a resource

Role with only write permission can use InitiateFileUpload, nothing else

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

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

Gets the information about a group by the group id.

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

Gets the members of a group.

Tells if the group has certain member.

Finds groups whose names match the specified filter.

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

A primary user.

A secondary user for cases with multiple identities.

A user catering to specific services.

A user to be used by specific applications.

A guest user not affiliated to the IDP.

A federated user provided by external IDPs.

A lightweight user account without access to various major functionalities.

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

Gets the information about a user by the user id.

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

Gets the groups of a user.

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

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

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

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

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

Lists the valid tokens generated by the user.

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

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

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

Finds users who accepted invite tokens by their attributes.

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

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

Get the information of the provider identified by a specific domain. MUST return CODE_NOT_FOUND if the sync'n'share system provider does not exist.

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