Ingoing API

API: Stable

Table of Contents

1. Remote Procedure Calls
Name Description
retrieveProducts Retrieve product support for this provider
search No description
streamingSearch No description
browse No description
copy No description
create Request creation of resource.
createDownload No description
createFolder No description
createUpload No description
delete Request deletion of resource.
emptyTrash No description
init Request from the user to (potentially) initialize any resources
move No description
retrieve No description
trash No description
updateAcl Callback received by the Provider when permissions are updated
verify Invoked by UCloud/Core to trigger verification of a single batch
2. Data Models
Name Description
FilesProviderStreamingSearchResult No description
FilesProviderStreamingSearchResult.EndOfResults No description
FilesProviderStreamingSearchResult.Result No description
PartialUFile A partial UFile returned by providers and made complete by UCloud/Core
FilesProviderBrowseRequest No description
FilesProviderCopyRequestItem No description
FilesProviderCreateDownloadRequestItem No description
FilesProviderCreateFolderRequestItem No description
FilesProviderCreateUploadRequestItem No description
FilesProviderEmptyTrashRequestItem No description
FilesProviderMoveRequestItem No description
FilesProviderRetrieveRequest No description
FilesProviderSearchRequest The base type for requesting paginated content.
FilesProviderStreamingSearchRequest No description
FilesProviderTrashRequestItem No description

Remote Procedure Calls

retrieveProducts

API: Stable Auth: Services

Retrieve product support for this provider

Request Response Error
Unit BulkResponse<FSSupport> CommonErrorMessage

This endpoint responds with the Products supported by this provider along with details for how Product is supported. The Products must be registered with UCloud/Core already.

streamingSearch

API: Stable Auth: Services

Request Response Error
FilesProviderStreamingSearchRequest FilesProviderStreamingSearchResult CommonErrorMessage

browse

API: Stable Auth: Services

Request Response Error
FilesProviderBrowseRequest PageV2<PartialUFile> CommonErrorMessage

copy

API: Stable Auth: Services

Request Response Error
BulkRequest<FilesProviderCopyRequestItem> BulkResponse<LongRunningTask> CommonErrorMessage

create

API: Stable Auth: Services

Request creation of resource.

Request Response Error
BulkRequest<UFile> BulkResponse<FindByStringId> CommonErrorMessage

createDownload

API: Stable Auth: Services

Request Response Error
BulkRequest<FilesProviderCreateDownloadRequestItem> BulkResponse<FilesCreateDownloadResponseItem> CommonErrorMessage

createFolder

API: Stable Auth: Services

Request Response Error
BulkRequest<FilesProviderCreateFolderRequestItem> BulkResponse<LongRunningTask> CommonErrorMessage

createUpload

API: Stable Auth: Services

Request Response Error
BulkRequest<FilesProviderCreateUploadRequestItem> BulkResponse<FilesCreateUploadResponseItem> CommonErrorMessage

delete

API: Stable Auth: Services

Request deletion of resource.

Request Response Error
BulkRequest<UFile> BulkResponse<Unit> CommonErrorMessage

emptyTrash

API: Stable Auth: Services

Request Response Error
BulkRequest<FilesProviderEmptyTrashRequestItem> BulkResponse<LongRunningTask> CommonErrorMessage

init

API: Stable Auth: Services

Request from the user to (potentially) initialize any resources

Request Response Error
ResourceInitializationRequest Unit CommonErrorMessage

This request is sent by the client, if the client believes that initialization of resources might be needed. NOTE: This request might be sent even if initialization has already taken place. UCloud/Core does not check if initialization has already taken place, it simply validates the request.

move

API: Stable Auth: Services

Request Response Error
BulkRequest<FilesProviderMoveRequestItem> BulkResponse<LongRunningTask> CommonErrorMessage

retrieve

API: Stable Auth: Services

Request Response Error
FilesProviderRetrieveRequest PartialUFile CommonErrorMessage

trash

API: Stable Auth: Services

Request Response Error
BulkRequest<FilesProviderTrashRequestItem> BulkResponse<LongRunningTask> CommonErrorMessage

updateAcl

API: Stable Auth: Services

Callback received by the Provider when permissions are updated

Request Response Error
BulkRequest<UpdatedAclWithResource<UFile>> BulkResponse<Unit> CommonErrorMessage

This endpoint is mandatory for Providers to implement. If the Provider does not need to keep internal state, then they may simply ignore this request by responding with 200 OK. The Provider MUST reply with an OK status. UCloud/Core will fail the request if the Provider does not acknowledge the request.

verify

API: Stable Auth: Services

Invoked by UCloud/Core to trigger verification of a single batch

Request Response Error
BulkRequest<UFile> Unit CommonErrorMessage

This endpoint is periodically invoked by UCloud/Core for resources which are deemed active. The Provider should immediately determine if these are still valid and recognized by the Provider. If any of the resources are not valid, then the Provider should notify UCloud/Core by issuing an update for each affected resource.

Data Models

FilesProviderStreamingSearchResult

API: Stable

sealed class FilesProviderStreamingSearchResult {
    class EndOfResults : FilesProviderStreamingSearchResult()
    class Result : FilesProviderStreamingSearchResult()
}

FilesProviderStreamingSearchResult.EndOfResults

API: Stable

data class EndOfResults(
    val type: String /* "end_of_results" */,
)
Properties
type: String /* "end_of_results" */ The type discriminator

FilesProviderStreamingSearchResult.Result

API: Stable

data class Result(
    val batch: List<PartialUFile>,
    val type: String /* "result" */,
)
Properties
batch: List<PartialUFile>
type: String /* "result" */ The type discriminator

PartialUFile

API: Stable

A partial UFile returned by providers and made complete by UCloud/Core

data class PartialUFile(
    val id: String,
    val status: UFileStatus,
    val createdAt: Long,
    val owner: ResourceOwner?,
    val permissions: ResourcePermissions?,
    val legacySensitivity: String?,
)
Properties
id: String The id of the file. Corresponds to UFile.id
status: UFileStatus The status of the file. Corresponds to UFile.status
createdAt: Long The creation timestamp. Corresponds to UFile.createdAt
owner: ResourceOwner? The owner of the file. Corresponds to UFile.owner. This will default to the collection's owner.
permissions: ResourcePermissions? The permissions of the file. Corresponds to UFile.permissions.This will default to the collection's permissions.
legacySensitivity: String? Legacy for reading old sensitivity values stored on in extended attributes

FilesProviderBrowseRequest

API: Stable

data class FilesProviderBrowseRequest(
    val resolvedCollection: FileCollection,
    val browse: ResourceBrowseRequest<UFileIncludeFlags>,
)
Properties
resolvedCollection: FileCollection
browse: ResourceBrowseRequest<UFileIncludeFlags>

FilesProviderCopyRequestItem

API: Stable

data class FilesProviderCopyRequestItem(
    val resolvedOldCollection: FileCollection,
    val resolvedNewCollection: FileCollection,
    val oldId: String,
    val newId: String,
    val conflictPolicy: WriteConflictPolicy,
)
Properties
resolvedOldCollection: FileCollection
resolvedNewCollection: FileCollection
oldId: String
newId: String
conflictPolicy: WriteConflictPolicy

FilesProviderCreateDownloadRequestItem

API: Stable

data class FilesProviderCreateDownloadRequestItem(
    val resolvedCollection: FileCollection,
    val id: String,
)
Properties
resolvedCollection: FileCollection
id: String

FilesProviderCreateFolderRequestItem

API: Stable

data class FilesProviderCreateFolderRequestItem(
    val resolvedCollection: FileCollection,
    val id: String,
    val conflictPolicy: WriteConflictPolicy,
)
Properties
resolvedCollection: FileCollection
id: String
conflictPolicy: WriteConflictPolicy

FilesProviderCreateUploadRequestItem

API: Stable

data class FilesProviderCreateUploadRequestItem(
    val resolvedCollection: FileCollection,
    val id: String,
    val type: UploadType,
    val supportedProtocols: List<UploadProtocol>,
    val conflictPolicy: WriteConflictPolicy,
)
Properties
resolvedCollection: FileCollection
id: String
type: UploadType
supportedProtocols: List<UploadProtocol>
conflictPolicy: WriteConflictPolicy

FilesProviderEmptyTrashRequestItem

API: Stable

data class FilesProviderEmptyTrashRequestItem(
    val resolvedCollection: FileCollection,
    val id: String,
)
Properties
resolvedCollection: FileCollection
id: String

FilesProviderMoveRequestItem

API: Stable

data class FilesProviderMoveRequestItem(
    val resolvedOldCollection: FileCollection,
    val resolvedNewCollection: FileCollection,
    val oldId: String,
    val newId: String,
    val conflictPolicy: WriteConflictPolicy,
)
Properties
resolvedOldCollection: FileCollection
resolvedNewCollection: FileCollection
oldId: String
newId: String
conflictPolicy: WriteConflictPolicy

FilesProviderRetrieveRequest

API: Stable

data class FilesProviderRetrieveRequest(
    val resolvedCollection: FileCollection,
    val retrieve: ResourceRetrieveRequest<UFileIncludeFlags>,
)
Properties
resolvedCollection: FileCollection
retrieve: ResourceRetrieveRequest<UFileIncludeFlags>

FilesProviderSearchRequest

API: Stable

The base type for requesting paginated content.

data class FilesProviderSearchRequest(
    val query: String,
    val owner: ResourceOwner,
    val flags: UFileIncludeFlags,
    val category: ProductCategoryId?,
    val itemsPerPage: Int?,
    val next: String?,
    val consistency: PaginationRequestV2Consistency?,
    val itemsToSkip: Long?,
)

Paginated content can be requested with one of the following consistency guarantees, this greatly changes the semantics of the call:

Consistency Description
PREFER Consistency is preferred but not required. An inconsistent snapshot might be returned.
REQUIRE Consistency is required. A request will fail if consistency is no longer guaranteed.

The consistency refers to if collecting all the results via the pagination API are consistent. We consider the results to be consistent if it contains a complete view at some point in time. In practice this means that the results must contain all the items, in the correct order and without duplicates.

If you use the PREFER consistency then you may receive in-complete results that might appear out-of-order and can contain duplicate items. UCloud will still attempt to serve a snapshot which appears mostly consistent. This is helpful for user-interfaces which do not strictly depend on consistency but would still prefer something which is mostly consistent.

The results might become inconsistent if the client either takes too long, or a service instance goes down while fetching the results. UCloud attempts to keep each next token alive for at least one minute before invalidating it. This does not mean that a client must collect all results within a minute but rather that they must fetch the next page within a minute of the last page. If this is not feasible and consistency is not required then PREFER should be used.

📝 NOTE: Services are allowed to ignore extra criteria of the request if the next token is supplied. This is needed in order to provide a consistent view of the results. Clients should provide the same criterion as they paginate through the results.

Properties
query: String
owner: ResourceOwner
flags: UFileIncludeFlags
category: ProductCategoryId?
itemsPerPage: Int? Requested number of items per page. Supported values: 10, 25, 50, 100, 250.
next: String? A token requesting the next page of items
consistency: PaginationRequestV2Consistency? Controls the consistency guarantees provided by the backend
itemsToSkip: Long? Items to skip ahead

FilesProviderStreamingSearchRequest

API: Stable

data class FilesProviderStreamingSearchRequest(
    val query: String,
    val owner: ResourceOwner,
    val flags: UFileIncludeFlags,
    val category: ProductCategoryId,
    val currentFolder: String?,
)
Properties
query: String
owner: ResourceOwner
flags: UFileIncludeFlags
category: ProductCategoryId
currentFolder: String?

FilesProviderTrashRequestItem

API: Stable

data class FilesProviderTrashRequestItem(
    val resolvedCollection: FileCollection,
    val id: String,
)
Properties
resolvedCollection: FileCollection
id: String