Protocol Documentation

Table of Contents

cs3/gateway/v1beta1/gateway_api.proto

Top

AuthenticateRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

type string

REQUIRED. The type of authentication to use.

client_id string

OPTIONAL. The id of the client. For basic authentication with username and password both client_id and client_secret are expected to be filled. However, for example, for OIDC only a token is necessary.

client_secret string

OPTIONAL. The secret of the client.

AuthenticateResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

token string

REQUIRED. The access token.

user cs3.identity.user.v1beta1.User

REQUIRED. The user.

GetQuotaRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref cs3.storage.provider.v1beta1.Reference

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

InitiateFileDownloadResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

download_endpoint string

REQUIRED. The endpoint where to downooad 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.

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.

InitiateFileUploadResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

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.

ListAuthProvidersResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

types string repeated

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

ListRecycleRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref cs3.storage.provider.v1beta1.Reference

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

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.

ListRecycleStreamRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref cs3.storage.provider.v1beta1.Reference

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

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.

PurgeRecycleRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref cs3.storage.provider.v1beta1.Reference

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

WhoAmIRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

token string

REQUIRED. The access token.

WhoAmIResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

user cs3.identity.user.v1beta1.User

REQUIRED. The user information.

GatewayAPI

Gateway API

The Gateway API is the only API exposed direclty to end-clients.

It is a facade API that all clients should connect to.

Other APIS like the StorageProviderAPI are internal APIS.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL

NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and

"OPTIONAL" in this document are to be interpreted as described in

RFC 2119.

The following are global requirements that apply to all methods:

Any method MUST return CODE_OK on a succesful operation.

Any method MAY return NOT_IMPLEMENTED.

Any method MAY return INTERNAL.

Any method MAY return UNKNOWN.

Any method MAY return UNAUTHENTICATED.

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

************************ AUTH ******** **************************/

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

Method NameRequest TypeResponse TypeDescription
Authenticate AuthenticateRequest AuthenticateResponse

Authenticates a user.

WhoAmI WhoAmIRequest WhoAmIResponse

WhoAmI returns the information for a user. *****************************************************************/ ************************ 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.

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. *****************************************************************/ ************************ APP PROVIDER ********************/ *****************************************************************/

OpenFileInAppProvider .cs3.app.provider.v1beta1.OpenFileInAppProviderRequest .cs3.app.provider.v1beta1.OpenFileInAppProviderResponse

Returns the iframe url from the WOPI server. The iframe url will let you open the document in the correct online document 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.

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

Returns a list of the available app providers known by this registry. *****************************************************************/ ************************ USER PROVIDER **************************/ *****************************************************************/

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

Gets the information about an user by its user id.

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

Gets the groups of a user.

IsInGroup .cs3.identity.user.v1beta1.IsInGroupRequest .cs3.identity.user.v1beta1.IsInGroupResponse

Tells if the user is in a certain group.

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

GetRemoteUser .cs3.ocm.invite.v1beta1.GetRemoteUserRequest .cs3.ocm.invite.v1beta1.GetRemoteUserResponse

Retrieves details about a remote user who has accepted an invite to share. *****************************************************************/ ******************** 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.

cs3/preferences/v1beta1/preferences_api.proto

Top

GetKeyRequest

FieldTypeLabelDescription
key string

REQUIRED.

GetKeyResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

val string

REQUIRED. The value associated with the key.

SetKeyRequest

FieldTypeLabelDescription
key string

REQUIRED.

val string

REQUIRED. The value associated with the key.

SetKeyResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

PreferencesAPI

Preferences API.

The Preferences API is responsible for creating

a key-value map according to user preferences.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL

NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and

"OPTIONAL" in this document are to be interpreted as described in

RFC 2119.

The following are global requirements that apply to all methods:

Any method MUST return CODE_OK on a succesful operation.

Any method MAY return NOT_IMPLEMENTED.

Any method MAY return INTERNAL.

Any method MAY return UNKNOWN.

Any method MAY return UNAUTHENTICATED.

Method NameRequest TypeResponse TypeDescription
SetKey SetKeyRequest SetKeyResponse

Maps the key-value pair.

GetKey GetKeyRequest GetKeyResponse

Returns the value associated with the requested key.

cs3/rpc/v1beta1/code.proto

Top

Code

These are the canonical error codes used by CS3 APIs.

Adapted from Google APIs:

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

Sometimes multiple error codes may apply. Services should return

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

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

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

NameNumberDescription
CODE_INVALID 0

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

CODE_OK 1

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

CODE_CANCELLED 2

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

CODE_UNKNOWN 3

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

CODE_INVALID_ARGUMENT 4

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

CODE_DEADLINE_EXCEEDED 5

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

CODE_NOT_FOUND 6

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

CODE_ALREADY_EXISTS 7

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

CODE_PERMISSION_DENIED 8

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

CODE_UNAUTHENTICATED 9

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

CODE_RESOURCE_EXHAUSTED 10

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

CODE_FAILED_PRECONDITION 11

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

CODE_ABORTED 12

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

CODE_OUT_OF_RANGE 13

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

CODE_UNIMPLEMENTED 14

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

CODE_INTERNAL 15

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

CODE_UNAVAILABLE 16

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

CODE_DATA_LOSS 17

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

CODE_REDIRECTION 18

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

cs3/rpc/v1beta1/status.proto

Top

Status

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

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

The error message should be a developer-facing English

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

FieldTypeLabelDescription
code Code

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

message string

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

trace string

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

target_uri string

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

cs3/types/v1beta1/types.proto

Top

Opaque

Opaque represents opaque information

in a form on a map.

For example, a local filesystem can

use this message to include filesystem

extended attributes.

FieldTypeLabelDescription
map Opaque.MapEntry repeated

REQUIRED.

Opaque.MapEntry

FieldTypeLabelDescription
key string

value OpaqueEntry

OpaqueEntry

OpaqueEntry represents the encoded

opaque value.

FieldTypeLabelDescription
decoder string

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

value bytes

REQUIRED. The encoded value.

Timestamp

Adapted from Google google/protobuf/timestamp.proto.

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

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

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

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

Gregorian calendar backwards to year one.

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

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

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

FieldTypeLabelDescription
seconds uint64

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

nanos uint32

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

cs3/app/provider/v1beta1/provider_api.proto

Top

OpenFileInAppProviderRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref cs3.storage.provider.v1beta1.Reference

REQUIRED. The resource reference.

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

view_mode OpenFileInAppProviderRequest.ViewMode

OpenFileInAppProviderResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

app_provider_url string

REQUIRED. The url that user agents will render to clients. Usually the rendering happens by using HTML iframes, at least, Office 365, Collabora, OnlyOffice do like that.

OpenFileInAppProviderRequest.ViewMode

REQUIRED.

View mode.

NameNumberDescription
VIEW_MODE_INVALID 0

VIEW_MODE_VIEW_ONLY 1

The file can be opened but not downloaded.

VIEW_MODE_READ_ONLY 2

The file can be downloaded.

VIEW_MODE_READ_WRITE 3

The file can be downloaded and updated.

ProviderAPI

App Provider API

The App Provider API is responsible for creating urls that

will render a viewer or editor for the given resource.

For example, an OnlyOffice or HackMD editor.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL

NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and

"OPTIONAL" in this document are to be interpreted as described in

RFC 2119.

The following are global requirements that apply to all methods:

Any method MUST return CODE_OK on a succesful operation.

Any method MAY return NOT_IMPLEMENTED.

Any method MAY return INTERNAL.

Any method MAY return UNKNOWN.

Any method MAY return UNAUTHENTICATED.

Method NameRequest TypeResponse TypeDescription
OpenFileInAppProvider OpenFileInAppProviderRequest OpenFileInAppProviderResponse

Returns the iframe url MUST return CODE_NOT_FOUND if the resource does not exist.

cs3/app/registry/v1beta1/registry_api.proto

Top

GetAppProvidersRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

resource_info cs3.storage.provider.v1beta1.ResourceInfo

REQUIRED. The resource information.

GetAppProvidersResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

providers ProviderInfo repeated

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

ListAppProvidersRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

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

ListAppProvidersResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

providers ProviderInfo repeated

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

RegistryAPI

App Registry API

The App Registry API is meant to as registry that

contains mappings between mime types and app providers.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL

NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and

"OPTIONAL" in this document are to be interpreted as described in

RFC 2119.

The following are global requirements that apply to all methods:

Any method MUST return CODE_OK on a succesful operation.

Any method MAY return NOT_IMPLEMENTED.

Any method MAY return INTERNAL.

Any method MAY return UNKNOWN.

Any method MAY return UNAUTHENTICATED.

Method NameRequest TypeResponse TypeDescription
GetAppProviders GetAppProvidersRequest GetAppProvidersResponse

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

ListAppProviders ListAppProvidersRequest ListAppProvidersResponse

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

cs3/app/registry/v1beta1/resources.proto

Top

ProviderInfo

Represents the information of the app provider.

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

mime_types string repeated

REQUIRED. The mimetypes handled by this provider.

address string

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

description string

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

cs3/auth/provider/v1beta1/provider_api.proto

Top

AuthenticateRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

client_id string

client_secret string

AuthenticateResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

user cs3.identity.user.v1beta1.User

ProviderAPI

Auth Provider API

The Auth Provider API is meant to authenticate a client.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL

NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and

"OPTIONAL" in this document are to be interpreted as described in

RFC 2119.

The following are global requirements that apply to all methods:

Any method MUST return CODE_OK on a succesful operation.

Any method MAY return NOT_IMPLEMENTED.

Any method MAY return INTERNAL.

Any method MAY return UNKNOWN.

Any method MAY return UNAUTHENTICATED.

Method NameRequest TypeResponse TypeDescription
Authenticate AuthenticateRequest AuthenticateResponse

Authenticate authenticates a client.

cs3/auth/registry/v1beta1/registry_api.proto

Top

GetAuthProviderRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

type string

REQUIRED. The type of authentication provider.

GetAuthProviderResponse

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

ListAuthProvidersRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

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

ListAuthProvidersResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

providers ProviderInfo repeated

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

RegistryAPI

Auth Registry API

The Auth Registry API is meant to as registry to obtain

information of available auth providers.

For example, to use OIDC or Kerberos for authentication.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL

NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and

"OPTIONAL" in this document are to be interpreted as described in

RFC 2119.

The following are global requirements that apply to all methods:

Any method MUST return CODE_OK on a succesful operation.

Any method MAY return NOT_IMPLEMENTED.

Any method MAY return INTERNAL.

Any method MAY return UNKNOWN.

Any method MAY return UNAUTHENTICATED.

Method NameRequest TypeResponse TypeDescription
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.

cs3/auth/registry/v1beta1/resources.proto

Top

ProviderInfo

ProviderInfo provides the information about an authentication provider.

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

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

provider_type string

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

address string

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

description string

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

cs3/identity/user/v1beta1/resources.proto

Top

User

Represents an user of the system.

FieldTypeLabelDescription
id UserId

username string

mail string

mail_verified bool

display_name string

groups string repeated

opaque cs3.types.v1beta1.Opaque

UserId

A UserId represents a user.

FieldTypeLabelDescription
idp string

REQUIRED. The identity provider for the user.

opaque_id string

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

cs3/identity/user/v1beta1/user_api.proto

Top

FindUsersRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

filter string

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

FindUsersResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

users User repeated

REQUIRED. The groups for the user.

GetUserGroupsRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

user_id UserId

REQUIRED. The id of the user.

GetUserGroupsResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

groups string repeated

REQUIRED. The groups for the user.

GetUserRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

user_id UserId

REQUIRED. The id of the user.

GetUserResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

user User

REQUIRED. The user information.

IsInGroupRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

user_id UserId

REQUIRED. The id of the user.

group string

REQUIRED. The group to check.

IsInGroupResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ok bool

REQUIRED. Tells if the user belongs to the group.

UserAPI

Provides an API for managing users.

Method NameRequest TypeResponse TypeDescription
GetUser GetUserRequest GetUserResponse

Gets the information about an user by its user id.

GetUserGroups GetUserGroupsRequest GetUserGroupsResponse

Gets the groups of a user.

IsInGroup IsInGroupRequest IsInGroupResponse

Tells if the user is in a certain group.

FindUsers FindUsersRequest FindUsersResponse

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

cs3/ocm/core/v1beta1/ocm_core_api.proto

Top

CreateOCMCoreShareRequest

https://rawgit.com/GEANT/OCM-API/v1/docs.html#null%2Fpaths%2F~1shares%2Fpost

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

description string

OPTIONAL. Description for the share.

name string

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

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.

CreateOCMCoreShareResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

id string

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

created cs3.types.v1beta1.Timestamp

REQUIRED.

OcmCoreAPI

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 NameRequest TypeResponse TypeDescription
CreateOCMCoreShare CreateOCMCoreShareRequest CreateOCMCoreShareResponse

Creates a new ocm share.

cs3/ocm/core/v1beta1/resources.proto

Top

Protocol

The protocol which is used to establish synchronisation.

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

cs3/ocm/invite/v1beta1/invite_api.proto

Top

AcceptInviteRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

invite_token InviteToken

REQUIRED. The token to authenticate with.

remote_user cs3.identity.user.v1beta1.User

REQUIRED. The user who accepted the invite.

AcceptInviteResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ForwardInviteRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

invite_token InviteToken

REQUIRED. The token to authenticate with.

origin_system_provider cs3.ocm.provider.v1beta1.ProviderInfo

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

ForwardInviteResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

GenerateInviteTokenRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

GenerateInviteTokenResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

invite_token InviteToken

REQUIRED. The generated token.

GetRemoteUserRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

remote_user_id cs3.identity.user.v1beta1.UserId

REQUIRED. The id of the user.

GetRemoteUserResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

remote_user cs3.identity.user.v1beta1.User

REQUIRED. The user information.

InviteAPI

Invite API

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

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

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL

NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and

"OPTIONAL" in this document are to be interpreted as described in

RFC 2119.

The following are global requirements that apply to all methods:

Any method MUST return CODE_OK on a succesful operation.

Any method MAY return NOT_IMPLEMENTED.

Any method MAY return INTERNAL.

Any method MAY return UNKNOWN.

Any method MAY return UNAUTHENTICATED.

Method NameRequest TypeResponse TypeDescription
GenerateInviteToken GenerateInviteTokenRequest GenerateInviteTokenResponse

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

ForwardInvite ForwardInviteRequest ForwardInviteResponse

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

AcceptInvite AcceptInviteRequest AcceptInviteResponse

Completes an invitation acceptance.

GetRemoteUser GetRemoteUserRequest GetRemoteUserResponse

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

cs3/ocm/invite/v1beta1/resources.proto

Top

InviteToken

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

systems to collaborate on resources.

FieldTypeLabelDescription
token string

REQUIRED. Unique ID associated with an InviteToken.

user_id cs3.identity.user.v1beta1.UserId

REQUIRED. The user who created the token.

expiration cs3.types.v1beta1.Timestamp

OPTIONAL. The time when the token will expire.

cs3/ocm/provider/v1beta1/provider_api.proto

Top

GetInfoByDomainRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

domain string

REQUIRED. The domain of the system provider.

GetInfoByDomainResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

provider_info ProviderInfo

REQUIRED. The info of the provider

IsProviderAllowedRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

provider ProviderInfo

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

IsProviderAllowedResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ListAllProvidersRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ListAllProvidersResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

providers ProviderInfo repeated

REQUIRED. The share.

ProviderAPI

OCM Auth Provider API

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

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL

NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and

"OPTIONAL" in this document are to be interpreted as described in

RFC 2119.

The following are global requirements that apply to all methods:

Any method MUST return CODE_OK on a succesful operation.

Any method MAY return NOT_IMPLEMENTED.

Any method MAY return INTERNAL.

Any method MAY return UNKNOWN.

Any method MAY return UNAUTHENTICATED.

Method NameRequest TypeResponse TypeDescription
IsProviderAllowed IsProviderAllowedRequest IsProviderAllowedResponse

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

GetInfoByDomain GetInfoByDomainRequest GetInfoByDomainResponse

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

ListAllProviders ListAllProvidersRequest ListAllProvidersResponse

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

cs3/ocm/provider/v1beta1/resources.proto

Top

ProviderInfo

Details of the sync'n'share system provider.

FieldTypeLabelDescription
name string

REQUIRED. The name of the provider.

full_name string

REQUIRED. The full name of the provider.

description string

REQUIRED. A description of the provider.

organization string

REQUIRED. The organization to which the provider belongs.

domain string

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

homepage string

REQUIRED. The homepage of the provider.

email string

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

services Service repeated

REQUIRED. The list of services provided by the provider.

properties ProviderInfo.PropertiesEntry repeated

OPTIONAL. Additional properties about the service.

ProviderInfo.PropertiesEntry

FieldTypeLabelDescription
key string

value string

Service

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

FieldTypeLabelDescription
host string

REQUIRED. The URL at which the service is hosted.

endpoint ServiceEndpoint

REQUIRED. The primary endpoint of the service.

api_version string

REQUIRED. The API version of the provided service.

additional_endpoints ServiceEndpoint repeated

OPTIONAL. Additional endpoints at which the service is exposed.

ServiceEndpoint

The endpoints exposed by particular services.

FieldTypeLabelDescription
type ServiceType

REQUIRED. The type of service.

name string

REQUIRED. The name of the service.

path string

REQUIRED. The path at which the service is hosted.

is_monitored bool

OPTIONAL. Whether the service is monitored.

properties ServiceEndpoint.PropertiesEntry repeated

OPTIONAL. Additional properties about the service.

ServiceEndpoint.PropertiesEntry

FieldTypeLabelDescription
key string

value string

ServiceType

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

FieldTypeLabelDescription
name string

REQUIRED The name of the service type.

description string

REQUIRED The description of the service type.

cs3/sharing/collaboration/v1beta1/collaboration_api.proto

Top

CreateShareRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

resource_info cs3.storage.provider.v1beta1.ResourceInfo

REQUIRED. The information of the resource to be shared.

grant ShareGrant

REQUIRED. The share grant for the share.

CreateShareResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

share Share

REQUIRED. The created share.

GetReceivedShareRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref ShareReference

REQUIRED. The reference of the received share.

GetReceivedShareResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

share ReceivedShare

REQUIRED. The share.

GetShareRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref ShareReference

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

GetShareResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

share Share

REQUIRED. The share.

ListReceivedSharesRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ListReceivedSharesResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

shares ReceivedShare repeated

REQUIRED. The list of received shares.

ListSharesRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

filters ListSharesRequest.Filter repeated

OPTIONAL. The list of filters to apply if any.

ListSharesRequest.Filter

REQUIRED.

represents a filter to apply to the request.

FieldTypeLabelDescription
type ListSharesRequest.Filter.Type

REQUIRED.

resource_id cs3.storage.provider.v1beta1.ResourceId

owner cs3.identity.user.v1beta1.UserId

creator cs3.identity.user.v1beta1.UserId

ListSharesResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

shares Share repeated

REQUIRED. The list of shares.

RemoveShareRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref ShareReference

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

RemoveShareResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

UpdateReceivedShareRequest

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

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref ShareReference

REQUIRED.

field UpdateReceivedShareRequest.UpdateField

UpdateReceivedShareRequest.UpdateField

REQUIRED.

The field to update.

FieldTypeLabelDescription
display_name string

Update the display name.

state ShareState

Update the share state

UpdateReceivedShareResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

UpdateShareRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information. REQUIRED.

ref ShareReference

field UpdateShareRequest.UpdateField

REQUIRED.

UpdateShareRequest.UpdateField

REQUIRED.

FieldTypeLabelDescription
permissions SharePermissions

Update the permissions.

display_name string

Update the display name.

UpdateShareResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ListSharesRequest.Filter.Type

The filter to apply.

NameNumberDescription
TYPE_INVALID 0

TYPE_NO 1

TYPE_RESOURCE_ID 2

TYPE_OWNER 3

TYPE_CREATOR 4

CollaborationAPI

User Share Provider API

The User Share Provider API is meant to manipulate share

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

from the perspective of the creator or the share and

from the perspective of the receiver of the share.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL

NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and

"OPTIONAL" in this document are to be interpreted as described in

RFC 2119.

The following are global requirements that apply to all methods:

Any method MUST return CODE_OK on a succesful operation.

Any method MAY return NOT_IMPLEMENTED.

Any method MAY return INTERNAL.

Any method MAY return UNKNOWN.

Any method MAY return UNAUTHENTICATED.

Method NameRequest TypeResponse TypeDescription
CreateShare CreateShareRequest CreateShareResponse

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

RemoveShare RemoveShareRequest RemoveShareResponse

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

GetShare GetShareRequest GetShareResponse

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

ListShares ListSharesRequest ListSharesResponse

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

UpdateShare UpdateShareRequest UpdateShareResponse

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

ListReceivedShares ListReceivedSharesRequest ListReceivedSharesResponse

List all shares the authenticated principal has received.

UpdateReceivedShare UpdateReceivedShareRequest UpdateReceivedShareResponse

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

GetReceivedShare GetReceivedShareRequest GetReceivedShareResponse

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

cs3/sharing/collaboration/v1beta1/resources.proto

Top

ReceivedShare

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

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

a display name from the perspective of the grantee and a

resource mount path in case the share will be mounted

in a path in a storage provider.

FieldTypeLabelDescription
share Share

REQUIRED.

state ShareState

REQUIRED. The state of the share.

Share

Shares are relationships between a resource owner

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

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

FieldTypeLabelDescription
id ShareId

REQUIRED. Opaque unique identifier of the share.

resource_id cs3.storage.provider.v1beta1.ResourceId

REQUIRED. Unique identifier of the shared resource.

permissions SharePermissions

REQUIRED. Permissions for the grantee to use the resource.

grantee cs3.storage.provider.v1beta1.Grantee

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

owner cs3.identity.user.v1beta1.UserId

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

creator cs3.identity.user.v1beta1.UserId

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

ctime cs3.types.v1beta1.Timestamp

REQUIRED. Creation time of the share.

mtime cs3.types.v1beta1.Timestamp

REQUIRED. Last modification time of the share.

ShareGrant

A share grant specifies the share permissions

for a grantee.

FieldTypeLabelDescription
grantee cs3.storage.provider.v1beta1.Grantee

REQUIRED. The grantee of the grant.

permissions SharePermissions

REQUIRED. The share permissions for the grant.

ShareId

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

A ShareId MUST be unique inside the share provider.

FieldTypeLabelDescription
opaque_id string

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

ShareKey

Uniquely identifies a share in the share provider.

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

1) The share provider id

2) The owner of the share

3) The resource id

4) The grantee for the share

This 4-tuple MUST be unique.

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

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

1) The share provider id = "user"

2) The owner of the share = "Alice"

3) The resource id = "home:1234"

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

FieldTypeLabelDescription
owner cs3.identity.user.v1beta1.UserId

REQUIRED.

resource_id cs3.storage.provider.v1beta1.ResourceId

REQUIRED.

grantee cs3.storage.provider.v1beta1.Grantee

REQUIRED.

SharePermissions

The permissions for a share.

FieldTypeLabelDescription
permissions cs3.storage.provider.v1beta1.ResourcePermissions

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

ShareReference

The mechanism to identify a share

in the share provider namespace.

FieldTypeLabelDescription
id ShareId

The id of the share.

key ShareKey

The combination of fields that make the share unique.

ShareState

The state of the share.

NameNumberDescription
SHARE_STATE_INVALID 0

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

SHARE_STATE_PENDING 1

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

SHARE_STATE_ACCEPTED 2

The recipient of the share has accepted the share.

SHARE_STATE_REJECTED 3

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

Top

CreatePublicShareRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

resource_info cs3.storage.provider.v1beta1.ResourceInfo

REQUIRED. The unique identifier for the shared storage resource.

grant Grant

REQUIRED. The restrictions to apply to the share.

CreatePublicShareResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

share PublicShare

REQUIRED. The created share.

GetPublicShareByTokenRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

token string

REQUIRED. The unlisted token to identify the public share.

password string

OPTIONAL. The public link can be password protected.

GetPublicShareByTokenResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

share PublicShare

REQUIRED. The share.

GetPublicShareRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref PublicShareReference

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

GetPublicShareResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

share PublicShare

REQUIRED. The share.

ListPublicSharesRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

filters ListPublicSharesRequest.Filter repeated

OPTIONAL. The list of filters to apply if any.

ListPublicSharesRequest.Filter

REQUIRED.

represents a filter to apply to the request.

FieldTypeLabelDescription
type ListPublicSharesRequest.Filter.Type

resource_id cs3.storage.provider.v1beta1.ResourceId

owner cs3.identity.user.v1beta1.UserId

creator cs3.identity.user.v1beta1.UserId

ListPublicSharesResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

share PublicShare repeated

REQUIRED. The list of shares.

RemovePublicShareRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref PublicShareReference

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

RemovePublicShareResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

UpdatePublicShareRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information. REQUIRED.

ref PublicShareReference

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

update UpdatePublicShareRequest.Update

UpdatePublicShareRequest.Update

REQUIRED.

FieldTypeLabelDescription
type UpdatePublicShareRequest.Update.Type

REQUIRED. Defines the field to update.

grant Grant

REQUIRED. Contains the field that will be updated.

display_name string

OPTIONAL Defines the public link display name.

UpdatePublicShareResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

share PublicShare

REQUIRED. The updated public share.

ListPublicSharesRequest.Filter.Type

REQUIRED.

NameNumberDescription
TYPE_INVALID 0

TYPE_RESOURCE_ID 1

TYPE_OWNER 2

TYPE_CREATOR 3

UpdatePublicShareRequest.Update.Type

REQUIRED.

NameNumberDescription
TYPE_INVALID 0

TYPE_PERMISSIONS 1

TYPE_PASSWORD 2

TYPE_EXPIRATION 3

TYPE_DISPLAYNAME 4

LinkAPI

PublicShare Provider API

The Public Share Provider API is meant to manipulate public shares

also called public links.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL

NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and

"OPTIONAL" in this document are to be interpreted as described in

RFC 2119.

The following are global requirements that apply to all methods:

Any method MUST return CODE_OK on a succesful operation.

Any method MAY return NOT_IMPLEMENTED.

Any method MAY return INTERNAL.

Any method MAY return UNKNOWN.

Any method MAY return UNAUTHENTICATED.

Method NameRequest TypeResponse TypeDescription
CreatePublicShare CreatePublicShareRequest CreatePublicShareResponse

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

RemovePublicShare RemovePublicShareRequest RemovePublicShareResponse

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

GetPublicShare GetPublicShareRequest GetPublicShareResponse

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

GetPublicShareByToken GetPublicShareByTokenRequest GetPublicShareByTokenResponse

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

ListPublicShares ListPublicSharesRequest ListPublicSharesResponse

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

UpdatePublicShare UpdatePublicShareRequest UpdatePublicShareResponse

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

cs3/sharing/link/v1beta1/resources.proto

Top

Grant

Defines the restrictions for the public share.

FieldTypeLabelDescription
permissions PublicSharePermissions

REQUIRED. The permissions for the share.

password string

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

expiration cs3.types.v1beta1.Timestamp

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

PublicShare

Public share are relationships between a resource owner

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

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

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

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

the storage provider.

FieldTypeLabelDescription
id PublicShareId

REQUIRED. Opaque unique identifier of the share.

token string

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

resource_id cs3.storage.provider.v1beta1.ResourceId

REQUIRED. Unique identifier of the shared resource.

permissions PublicSharePermissions

REQUIRED. Permissions for the grantee to use the resource.

owner cs3.identity.user.v1beta1.UserId

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

creator cs3.identity.user.v1beta1.UserId

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

ctime cs3.types.v1beta1.Timestamp

REQUIRED. Creation time of the share.

mtime cs3.types.v1beta1.Timestamp

REQUIRED. Last modification time of the share.

password_protected bool

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

expiration cs3.types.v1beta1.Timestamp

OPTIONAL. The expiration time for the public share.

display_name string

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

PublicShareId

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

A ShareId MUST be unique inside the share provider.

FieldTypeLabelDescription
opaque_id string

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

PublicSharePermissions

The permissions for a share.

FieldTypeLabelDescription
permissions cs3.storage.provider.v1beta1.ResourcePermissions

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

PublicShareReference

The mechanism to identify a share

in the share provider namespace.

FieldTypeLabelDescription
id PublicShareId

The id of the share.

token string

The token to identify the public share.

cs3/sharing/ocm/v1beta1/ocm_api.proto

Top

CreateOCMShareRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

resource_id cs3.storage.provider.v1beta1.ResourceId

REQUIRED. The unique identifier for the shared storage resource.

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.

CreateOCMShareResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

share Share

REQUIRED. The created share.

GetOCMShareRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref ShareReference

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

GetOCMShareResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

share Share

REQUIRED. The share.

GetReceivedOCMShareRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref ShareReference

REQUIRED. The reference of the received share.

GetReceivedOCMShareResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

share ReceivedShare

REQUIRED. The share.

ListOCMSharesRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

filters ListOCMSharesRequest.Filter repeated

OPTIONAL. The list of filters to apply if any.

ListOCMSharesRequest.Filter

REQUIRED.

represents a filter to apply to the request.

FieldTypeLabelDescription
type ListOCMSharesRequest.Filter.Type

REQUIRED.

resource_id cs3.storage.provider.v1beta1.ResourceId

owner cs3.identity.user.v1beta1.UserId

creator cs3.identity.user.v1beta1.UserId

ListOCMSharesResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

shares Share repeated

REQUIRED. The list of shares.

ListReceivedOCMSharesRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ListReceivedOCMSharesResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

shares ReceivedShare repeated

REQUIRED. The list of received shares.

RemoveOCMShareRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref ShareReference

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

RemoveOCMShareResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

UpdateOCMShareRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information. REQUIRED.

ref ShareReference

REQUIRED.

field UpdateOCMShareRequest.UpdateField

UpdateOCMShareRequest.UpdateField

REQUIRED.

FieldTypeLabelDescription
permissions SharePermissions

Update the permissions.

display_name string

Update the display name.

UpdateOCMShareResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

UpdateReceivedOCMShareRequest

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

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref ShareReference

REQUIRED.

field UpdateReceivedOCMShareRequest.UpdateField

UpdateReceivedOCMShareRequest.UpdateField

REQUIRED.

FieldTypeLabelDescription
display_name string

Update the display name.

state ShareState

Update the share state

UpdateReceivedOCMShareResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ListOCMSharesRequest.Filter.Type

REQUIRED.

The filter to apply.

NameNumberDescription
TYPE_INVALID 0

TYPE_NO 1

TYPE_RESOURCE_ID 2

TYPE_OWNER 3

TYPE_CREATOR 4

TYPE_OWNER_PROVIDER 5

TYPE_CREATOR_PROVIDER 6

OcmAPI

OCM Share Provider API

The OCM Share Provider API is meant to manipulate share

resources from the perspective of the creator or the share and

from the perspective of the receiver of the share.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL

NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and

"OPTIONAL" in this document are to be interpreted as described in

RFC 2119.

The following are global requirements that apply to all methods:

Any method MUST return CODE_OK on a succesful operation.

Any method MAY return NOT_IMPLEMENTED.

Any method MAY return INTERNAL.

Any method MAY return UNKNOWN.

Any method MAY return UNAUTHENTICATED.

Method NameRequest TypeResponse TypeDescription
CreateOCMShare CreateOCMShareRequest CreateOCMShareResponse

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

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.

cs3/sharing/ocm/v1beta1/resources.proto

Top

ReceivedShare

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

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

a display name from the perspective of the grantee and a

resource mount path in case the share will be mounted

in a path in a storage provider.

FieldTypeLabelDescription
share Share

REQUIRED.

state ShareState

REQUIRED. The state of the share.

Share

Shares are relationships between a resource owner

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

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

FieldTypeLabelDescription
id ShareId

REQUIRED. Opaque unique identifier of the share.

resource_id cs3.storage.provider.v1beta1.ResourceId

REQUIRED. Unique identifier of the shared resource.

permissions SharePermissions

REQUIRED. Permissions for the grantee to use the resource.

grantee cs3.storage.provider.v1beta1.Grantee

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

owner cs3.identity.user.v1beta1.UserId

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

creator cs3.identity.user.v1beta1.UserId

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

ctime cs3.types.v1beta1.Timestamp

REQUIRED. Creation time of the share.

mtime cs3.types.v1beta1.Timestamp

REQUIRED. Last modification time of the share.

ShareGrant

A share grant specifies the share permissions

for a grantee.

FieldTypeLabelDescription
grantee cs3.storage.provider.v1beta1.Grantee

REQUIRED. The grantee of the grant.

permissions SharePermissions

REQUIRED. The share permissions for the grant.

ShareId

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

A ShareId MUST be unique inside the share provider.

FieldTypeLabelDescription
opaque_id string

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

ShareKey

Uniquely identifies a share in the share provider.

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

1) The share provider id

2) The owner of the share

3) The resource id

4) The grantee for the share

This 4-tuple MUST be unique.

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

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

1) The share provider id = "user"

2) The owner of the share = "Alice"

3) The resource id = "home:1234"

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

FieldTypeLabelDescription
owner cs3.identity.user.v1beta1.UserId

REQUIRED.

resource_id cs3.storage.provider.v1beta1.ResourceId

REQUIRED.

grantee cs3.storage.provider.v1beta1.Grantee

REQUIRED.

SharePermissions

The permissions for a share.

FieldTypeLabelDescription
permissions cs3.storage.provider.v1beta1.ResourcePermissions

reshare bool

ShareReference

The mechanism to identify a share

in the share provider namespace.

FieldTypeLabelDescription
id ShareId

The id of the share.

key ShareKey

The combination of fields that make the share unique.

ShareState

The state of the share.

NameNumberDescription
SHARE_STATE_INVALID 0

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

SHARE_STATE_PENDING 1

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

SHARE_STATE_ACCEPTED 2

The recipient of the share has accepted the share.

SHARE_STATE_REJECTED 3

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

cs3/storage/provider/v1beta1/provider_api.proto

Top

AddGrantRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref Reference

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

grant Grant

REQUIRED. The grant to be added.

AddGrantResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

CreateContainerRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref Reference

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

CreateContainerResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

CreateHomeRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

CreateHomeResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

CreateReferenceRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

path string

REQUIRED. The location where to store the reference.

target_uri string

REQUIRED. The reference resource by RFC3986.

CreateReferenceResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

DeleteRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref Reference

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

DeleteResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

GetHomeRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

GetHomeResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

path string

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

GetPathRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

resource_id ResourceId

REQUIRED. The resource id of the resource.

GetPathResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

path string

REQUIRED. The path of the resource.

GetQuotaRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

GetQuotaResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

total_bytes uint64

REQUIRED. The total available bytes.

used_bytes uint64

REQUIRED. The number of used bytes.

InitiateFileDownloadRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref Reference

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

InitiateFileDownloadResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

download_endpoint string

REQUIRED. The endpoint where to downooad 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.

InitiateFileUploadRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref Reference

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

InitiateFileUploadResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

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.

ListContainerRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref Reference

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

arbitrary_metadata_keys string repeated

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

ListContainerResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

infos ResourceInfo repeated

REQUIRED. The list of resource informations.

ListContainerStreamRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref Reference

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

arbitrary_metadata_keys string repeated

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

ListContainerStreamResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

info ResourceInfo

REQUIRED. The resource information.

ListFileVersionsRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref Reference

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

ListFileVersionsResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

versions FileVersion repeated

REQUIRED. The list of file versions.

ListGrantsRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref Reference

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

ListGrantsResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

grants Grant repeated

REQUIRED. The grants.

ListRecycleRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

from_ts cs3.types.v1beta1.Timestamp

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

to_ts cs3.types.v1beta1.Timestamp

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

ListRecycleResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

recycle_items RecycleItem repeated

REQUIRED. The list of recycle items.

ListRecycleStreamRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

from_ts cs3.types.v1beta1.Timestamp

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

to_ts cs3.types.v1beta1.Timestamp

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

ListRecycleStreamResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

recycle_item RecycleItem

REQUIRED. The recycle items.

MoveRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

source Reference

REQUIRED. The source reference the resource is moved from.

destination Reference

REQUIRED. The destination reference the resource is moved to.

MoveResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

PurgeRecycleRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref Reference

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

PurgeRecycleResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

RemoveGrantRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref Reference

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

grant Grant

REQUIRED. The grant to remove.

RemoveGrantResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

RestoreFileVersionRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref Reference

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

key string

REQUIRED. The key to restore a specific file version.

RestoreFileVersionResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

RestoreRecycleItemRequest

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

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref Reference

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

key string

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

restore_path string

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.

RestoreRecycleItemResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

SetArbitraryMetadataRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref Reference

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

arbitrary_metadata ArbitraryMetadata

REQUIRED. The arbitrary metadata to add to the resource.

SetArbitraryMetadataResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

StatRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref Reference

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

arbitrary_metadata_keys string repeated

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

StatResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

info ResourceInfo

REQUIRED. The resource information.

UnsetArbitraryMetadataRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref Reference

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

arbitrary_metadata_keys string repeated

REQUIRED. The arbitrary metadata to delete.

UnsetArbitraryMetadataResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

UpdateGrantRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref Reference

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

grant Grant

REQUIRED. The grant to be updated.

UpdateGrantResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ProviderAPI

Storage Provider API

The Storage Provider API is meant to manipulate storage

resources in the underlying storage system behind the service.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL

NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and

"OPTIONAL" in this document are to be interpreted as described in

RFC 2119.

The following are global requirements that apply to all methods:

Any method MUST return CODE_OK on a succesful operation.

Any method MAY return NOT_IMPLEMENTED.

Any method MAY return INTERNAL.

Any method MAY return UNKNOWN.

Any method MAY return UNAUTHENTICATED.

Method NameRequest TypeResponse TypeDescription
AddGrant AddGrantRequest AddGrantResponse

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

CreateContainer CreateContainerRequest CreateContainerResponse

Creates a new resource of type container. MUST return CODE_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.

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.

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.

cs3/storage/provider/v1beta1/resources.proto

Top

ArbitraryMetadata

Arbitrary metadata than can be set to the resource.

FieldTypeLabelDescription
metadata ArbitraryMetadata.MetadataEntry repeated

ArbitraryMetadata.MetadataEntry

FieldTypeLabelDescription
key string

value string

CanonicalMetadata

CanonicalMetadata contains extra metadata

attached to a resource. This message and the Opaque

message differ in that Opaque allows service implementors

to include any extra metadata in any format and most clients

will ignore it. However, the CanonicalMetadata message

contains well defined fileds that clients MUST understand if

they are specified.

FieldTypeLabelDescription
target Reference

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

FileVersion

The information for a file version.

TODO(labkode): make size and mtime OPTIONAL?

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

key string

MUST the specified. The key to identify the version.

size uint64

REQUIRED. The size in bytes of the file version.

mtime uint64

REQUIRED. The Unix Epoch timestamp in seconds.

Grant

A grant grants permissions

to a resource to a grantee.

FieldTypeLabelDescription
grantee Grantee

REQUIRED. The grantee of the grant.

permissions ResourcePermissions

REQUIRED. The permissions for the grant.

Grantee

A grantee is the receiver of a grant.

FieldTypeLabelDescription
type GranteeType

REQUIRED. The type of the grantee.

id cs3.identity.user.v1beta1.UserId

The unique id for the grantee. For example, a group name, user name or uuid.

RecycleItem

A recycle item represents the information

of a deleted resource.

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

type ResourceType

REQUIRED. The type of the resource.

key string

REQUIRED. The key to identify the deleted resource.

path string

REQUIRED. The original path of the deleted resource.

size uint64

OPTIONAL. The size of the deleted resource.

deletion_time cs3.types.v1beta1.Timestamp

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

Reference

The mechanism to identify a resource

in the storage provider namespace. Note that the path OR the resourceId must be specifed, not both.

FieldTypeLabelDescription
path string

The path to the resource. MUST start with the slash character (/).

id ResourceId

The id for the resource. MUST NOT start with the slash character (/).

ResourceChecksum

The checksum to verify

the integrity of a resource.

FieldTypeLabelDescription
type ResourceChecksumType

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

sum string

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

ResourceChecksumPriority

When negotiating the user of checksum types

between client and server, this structure

defines the priority of the checksum.

Priority 0 means highest priority.

FieldTypeLabelDescription
type ResourceChecksumType

priority uint32

ResourceId

A resource id identifies uniquely a

resource in the storage provider namespace.

A ResourceId MUST be unique in the storage provider.

FieldTypeLabelDescription
storage_id string

REQUIRED. The storage id of the 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.

ResourceInfo

Represents the information (metadata) about

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

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

type ResourceType

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

id ResourceId

REQUIRED. Opaque unique identifier of the resource.

checksum ResourceChecksum

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

etag string

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

mime_type string

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

mtime cs3.types.v1beta1.Timestamp

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

path string

REQUIRED. The path for the resource. It MUST start with the slash character (/).

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.

ResourcePermissions

The representation of permissions attached to a resource.

FieldTypeLabelDescription
add_grant bool

create_container bool

delete bool

get_path bool

get_quota bool

initiate_file_download bool

initiate_file_upload bool

list_grants bool

list_container bool

list_file_versions bool

list_recycle bool

move bool

remove_grant bool

purge_recycle bool

restore_file_version bool

restore_recycle_item bool

stat bool

update_grant bool

GranteeType

The type of the grantee.

NameNumberDescription
GRANTEE_TYPE_INVALID 0

GRANTEE_TYPE_USER 1

This type represents an individual.

GRANTEE_TYPE_GROUP 2

This type represents a group of individuals.

ResourceChecksumType

The type of checksum to use.

NameNumberDescription
RESOURCE_CHECKSUM_TYPE_INVALID 0

RESOURCE_CHECKSUM_TYPE_UNSET 1

unset means no checksum is set.

RESOURCE_CHECKSUM_TYPE_ADLER32 2

Use Adler32 checksum.

RESOURCE_CHECKSUM_TYPE_MD5 3

Use MD5 checksum.

RESOURCE_CHECKSUM_TYPE_SHA1 4

Use SHA-1 checksum.

ResourceType

The available types of resources.

NameNumberDescription
RESOURCE_TYPE_INVALID 0

RESOURCE_TYPE_FILE 1

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

RESOURCE_TYPE_CONTAINER 2

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

RESOURCE_TYPE_REFERENCE 3

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

RESOURCE_TYPE_SYMLINK 4

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

RESOURCE_TYPE_INTERNAL 5

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

cs3/storage/registry/v1beta1/registry_api.proto

Top

GetHomeRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

GetHomeResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

provider ProviderInfo

REQUIRED. The storage provider for the user home.

GetStorageProviderRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

ref cs3.storage.provider.v1beta1.Reference

REQUIRED. The reference for the resource.

GetStorageProviderResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

provider ProviderInfo

REQUIRED. The storage provider handling the requested storage resource.

ListStorageProvidersRequest

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

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

ListStorageProvidersResponse

FieldTypeLabelDescription
status cs3.rpc.v1beta1.Status

REQUIRED. The response status.

opaque cs3.types.v1beta1.Opaque

OPTIONAL. Opaque information.

providers ProviderInfo repeated

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

RegistryAPI

Storage Registry API

The Storage Registry API is meant to as registry to obtain

information of available storage providers.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL

NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and

"OPTIONAL" in this document are to be interpreted as described in

RFC 2119.

The following are global requirements that apply to all methods:

Any method MUST return CODE_OK on a succesful operation.

Any method MAY return NOT_IMPLEMENTED.

Any method MAY return INTERNAL.

Any method MAY return UNKNOWN.

Any method MAY return UNAUTHENTICATED.

Method NameRequest TypeResponse TypeDescription
GetStorageProvider GetStorageProviderRequest GetStorageProviderResponse

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

ListStorageProviders ListStorageProvidersRequest ListStorageProvidersResponse

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

GetHome GetHomeRequest GetHomeResponse

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

cs3/storage/registry/v1beta1/resources.proto

Top

ProviderInfo

The information for the storage provider.

FieldTypeLabelDescription
opaque cs3.types.v1beta1.Opaque

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

provider_id string

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

provider_path string

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

address string

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

description string

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

features ProviderInfo.Features

REQUIRED. List of available methods.

ProviderInfo.Features

REQUIRED.

Represents the list of features available

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

the related service methods MUST return CODE_UNIMPLEMENTED.

FieldTypeLabelDescription
recycle bool

file_versions bool

Scalar Value Types

.proto TypeNotesC++ TypeJava TypePython 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