package cs3.sharing.link.v1beta1

Get desktop application:
View/edit binary Protocol Buffers messages

PublicShare Provider API The Public Share Provider API is meant to manipulate public shares also called public links. Access to public shares can be limitted by a password. The share provider must store this password in a secure manner e.g. hashed with the bcrypt algorithm. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. The following are global requirements that apply to all methods: Any method MUST return CODE_OK on a succesful operation. Any method MAY return NOT_IMPLEMENTED. Any method MAY return INTERNAL. Any method MAY return UNKNOWN. Any method MAY return UNAUTHENTICATED.

• rpc CreatePublicShare (CreatePublicShareRequest, CreatePublicShareResponse)

  link_api.proto:63

  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.

• rpc GetPublicShare (GetPublicShareRequest, GetPublicShareResponse)

  link_api.proto:69

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

• rpc GetPublicShareByToken (GetPublicShareByTokenRequest, GetPublicShareByTokenResponse)

  link_api.proto:72

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

• rpc ListPublicShares (ListPublicSharesRequest, ListPublicSharesResponse)

  link_api.proto:76

  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.

• rpc RemovePublicShare (RemovePublicShareRequest, RemovePublicShareResponse)

  link_api.proto:66

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

• rpc UpdatePublicShare (UpdatePublicShareRequest, UpdatePublicShareResponse)

  link_api.proto:79

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

Used as request type in: gateway.v1beta1.GatewayAPI.CreatePublicShare, LinkAPI.CreatePublicShare

• optional types.v1beta1.Opaque opaque = 1

  OPTIONAL. Opaque information.

• optional storage.provider.v1beta1.ResourceInfo resource_info = 2

  REQUIRED. The unique identifier for the shared storage resource.

• optional Grant grant = 3

  REQUIRED. The restrictions to apply to the share.

• string description = 4

  OPTIONAL The description to add to the share.

• bool internal = 5

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

• bool notify_uploads = 6

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

• string notify_uploads_extra_recipients = 7

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

Used as response type in: gateway.v1beta1.GatewayAPI.CreatePublicShare, LinkAPI.CreatePublicShare

• optional rpc.v1beta1.Status status = 1

  REQUIRED. The response status.

• optional types.v1beta1.Opaque opaque = 2

  OPTIONAL. Opaque information.

• optional PublicShare share = 3

  REQUIRED. The created share.

Used as request type in: gateway.v1beta1.GatewayAPI.GetPublicShareByToken, LinkAPI.GetPublicShareByToken

• optional types.v1beta1.Opaque opaque = 1

  OPTIONAL. Opaque information.

• string token = 2

  REQUIRED. The unlisted token to identify the public share.

• optional PublicShareAuthentication authentication = 3

  OPTIONAL. The public link can require authentication.

• bool sign = 4

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

Used as response type in: gateway.v1beta1.GatewayAPI.GetPublicShareByToken, LinkAPI.GetPublicShareByToken

• optional rpc.v1beta1.Status status = 1

  REQUIRED. The response status.

• optional types.v1beta1.Opaque opaque = 2

  OPTIONAL. Opaque information.

• optional PublicShare share = 3

  REQUIRED. The share.

• string password_hash = 4

  OPTIONAL. The share password hash.

Used as request type in: gateway.v1beta1.GatewayAPI.GetPublicShare, LinkAPI.GetPublicShare

• optional types.v1beta1.Opaque opaque = 1

  OPTIONAL. Opaque information.

• optional PublicShareReference ref = 2

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

• bool sign = 3

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

Used as response type in: gateway.v1beta1.GatewayAPI.GetPublicShare, LinkAPI.GetPublicShare

• optional rpc.v1beta1.Status status = 1

  REQUIRED. The response status.

• optional types.v1beta1.Opaque opaque = 2

  OPTIONAL. Opaque information.

• optional PublicShare share = 3

  REQUIRED. The share.

Defines the restrictions for the public share.

Used in: CreatePublicShareRequest, UpdatePublicShareRequest.Update

• optional PublicSharePermissions permissions = 1

  REQUIRED. The permissions for the share.

• string password = 2

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

• optional types.v1beta1.Timestamp expiration = 3

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

Used as request type in: gateway.v1beta1.GatewayAPI.ListExistingPublicShares, gateway.v1beta1.GatewayAPI.ListPublicShares, LinkAPI.ListPublicShares

• optional types.v1beta1.Opaque opaque = 1

  OPTIONAL. Opaque information.

• repeated ListPublicSharesRequest.Filter filters = 2

  OPTIONAL. The list of filters to apply if any.

• bool sign = 3

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

• int32 page_size = 4

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

• string page_token = 5

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

REQUIRED. represents a filter to apply to the request.

Used in: ListPublicSharesRequest

• Filter.Type type = 2

• oneof term

  • storage.provider.v1beta1.ResourceId resource_id = 3

  • identity.user.v1beta1.UserId owner = 4

  • identity.user.v1beta1.UserId creator = 5

REQUIRED.

Used in: Filter

• TYPE_INVALID = 0

• TYPE_RESOURCE_ID = 1

• TYPE_OWNER = 2

• TYPE_CREATOR = 3

Used as response type in: gateway.v1beta1.GatewayAPI.ListPublicShares, LinkAPI.ListPublicShares

• optional rpc.v1beta1.Status status = 1

  REQUIRED. The response status.

• optional types.v1beta1.Opaque opaque = 2

  OPTIONAL. Opaque information.

• repeated PublicShare share = 3

  REQUIRED. The list of shares.

• string next_page_token = 4

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

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.

Used in: gateway.v1beta1.PublicShareResourceInfo, CreatePublicShareResponse, GetPublicShareByTokenResponse, GetPublicShareResponse, ListPublicSharesResponse, UpdatePublicShareResponse

• optional PublicShareId id = 1

  REQUIRED. Opaque unique identifier of the share.

• string token = 2

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

• optional storage.provider.v1beta1.ResourceId resource_id = 3

  REQUIRED. Unique identifier of the shared resource.

• optional PublicSharePermissions permissions = 4

  REQUIRED. Permissions for the grantee to use the resource.

• optional identity.user.v1beta1.UserId owner = 5

  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.

• optional identity.user.v1beta1.UserId creator = 6

  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.

• optional types.v1beta1.Timestamp ctime = 7

  REQUIRED. Creation time of the share.

• optional types.v1beta1.Timestamp mtime = 8

  REQUIRED. Last modification time of the share.

• bool password_protected = 9

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

• optional types.v1beta1.Timestamp expiration = 10

  OPTIONAL. The expiration time for the public share.

• string display_name = 11

  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.

• optional ShareSignature signature = 12

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

• bool quicklink = 13

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

• string description = 14

  OPTIONAL Description of the share.

• bool notify_uploads = 15

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

• string notify_uploads_extra_recipients = 16

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

The mechanism to authenticate a request to GetPublicShareByToken.

Used in: GetPublicShareByTokenRequest

• oneof spec

  • string password = 1

    The password of the share.

  • ShareSignature signature = 2

    The signature issued by GetPublicShareByToken.

A share id identifies uniquely a // share in the share provider namespace. A ShareId MUST be unique inside the share provider.

Used in: PublicShare, PublicShareReference

• string opaque_id = 2

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

The permissions for a share.

Used in: Grant, PublicShare

• optional storage.provider.v1beta1.ResourcePermissions permissions = 1

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

The mechanism to identify a share in the share provider namespace.

Used in: GetPublicShareRequest, RemovePublicShareRequest, UpdatePublicShareRequest

• oneof spec

  REQUIRED. One of the specifications MUST be specified.

  • PublicShareId id = 1

    The id of the share.

  • string token = 2

    The token to identify the public share.

Used as request type in: gateway.v1beta1.GatewayAPI.RemovePublicShare, LinkAPI.RemovePublicShare

• optional types.v1beta1.Opaque opaque = 1

  OPTIONAL. Opaque information.

• optional PublicShareReference ref = 2

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

Used as response type in: gateway.v1beta1.GatewayAPI.RemovePublicShare, LinkAPI.RemovePublicShare

• optional rpc.v1beta1.Status status = 1

  REQUIRED. The response status.

• optional types.v1beta1.Opaque opaque = 2

  OPTIONAL. Opaque information.

A time constrained token which can be used to authenticate link share requests.

Used in: PublicShare, PublicShareAuthentication

• string signature = 1

  REQUIRED. The signature value.

• optional types.v1beta1.Timestamp signature_expiration = 2

  REQUIRED. The time until the signature becomes invalid.

Used as request type in: gateway.v1beta1.GatewayAPI.UpdatePublicShare, LinkAPI.UpdatePublicShare

• optional types.v1beta1.Opaque opaque = 1

  OPTIONAL. Opaque information.

  REQUIRED.

• optional PublicShareReference ref = 2

  REQUIRED. The reference to the public share.

  Available fields to update.

• optional UpdatePublicShareRequest.Update update = 3

REQUIRED.

Used in: UpdatePublicShareRequest

• Update.Type type = 3

  REQUIRED. Defines the field to update.

• optional Grant grant = 4

  REQUIRED. Contains the field that will be updated.

• string display_name = 5

  OPTIONAL Defines the public link display name.

• string description = 6

  OPTIONAL Defines the public link description.

• bool notify_uploads = 7

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

• string notify_uploads_extra_recipients = 8

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

REQUIRED.

Used in: Update

• TYPE_INVALID = 0

• TYPE_PERMISSIONS = 1

• TYPE_PASSWORD = 2

• TYPE_EXPIRATION = 3

• TYPE_DISPLAYNAME = 4

• TYPE_DESCRIPTION = 5

• TYPE_NOTIFYUPLOADS = 6

• TYPE_NOTIFYUPLOADSEXTRARECIPIENTS = 7

Used as response type in: gateway.v1beta1.GatewayAPI.UpdatePublicShare, LinkAPI.UpdatePublicShare

• optional rpc.v1beta1.Status status = 1

  REQUIRED. The response status.

• optional types.v1beta1.Opaque opaque = 2

  OPTIONAL. Opaque information.

• optional PublicShare share = 3

  REQUIRED. The updated public share.