Gifts

Gifts provide the system a way to grant new and existing users (personal projects) credits from a project

Rationale

The gifting system is primarily intended to provide credits to new users when they join the system. A Gift follows the same rules as Wallets do. This means that in order to give a gift to someone you must transfer the resources from a project. This means that the credits will be subtracted directly from the source project.

A Gift can only be claimed once by every user and it will be applied directly to the user’s personal project. Clients used by the end-user should use Gifts.availableGifts to figure out which Gifts are unclaimed by this user. It may then claim the individual Gifts with Gifts.claimGift.

Administrators of a project can manage Gifts through the Gifts.createGift, Gifts.deleteGift and Gifts.listGifts endpoints.

---

⚠️ WARNING: The API listed on this page will likely change to conform with our API conventions. Be careful when building integrations. The following changes are expected:

• RPC names will change to conform with the conventions

• RPC request and response types will change to conform with the conventions

• RPCs which return a page will be collapsed into a single browse endpoint

• Some property names will change to be consistent with Resources

---

Table of Contents

1. Remote Procedure Calls

Name	Description
browse	No description
availableGifts	Finds a list of a user's unclaimed `Gift`s
claimGift	Claims a `Gift` to the calling user's personal project
createGift	Creates a new Gift in the system
deleteGift	Deletes a Gift by its DeleteGiftRequest.giftId

2. Data Models

Name	Description
GiftWithCriteria	A `Gift` along with the `criteria` for which that can `Gifts.claimGift` this
ClaimGiftRequest	No description
DeleteGiftRequest	No description
Gifts.Browse.Request	The base type for requesting paginated content.
AvailableGiftsResponse	No description

Remote Procedure Calls

browse

Request	Response	Error
Gifts.Browse.Request	PageV2<GiftWithCriteria>	CommonErrorMessage

availableGifts

Finds a list of a user’s unclaimed Gifts

Request	Response	Error
Unit	AvailableGiftsResponse	CommonErrorMessage

claimGift

Claims a Gift to the calling user’s personal project

Request	Response	Error
ClaimGiftRequest	Unit	CommonErrorMessage

User errors:

• Users who are not eligible for claiming this Gift will receive an appropriate error code.

• If the gifting project has run out of resources then this endpoint will fail. The gift will not be marked as claimed.

createGift

Creates a new Gift in the system

Request	Response	Error
GiftWithCriteria	FindByLongId	CommonErrorMessage

Only project administrators can create new Gifts in the system.

deleteGift

Deletes a Gift by its DeleteGiftRequest.giftId

Request	Response	Error
DeleteGiftRequest	Unit	CommonErrorMessage

Only project administrators of Gift.resourcesOwnedBy can delete the Gift.

Data Models

GiftWithCriteria

A Gift along with the criteria for which that can Gifts.claimGift this

data class GiftWithCriteria(
    val id: Long,
    val resourcesOwnedBy: String,
    val title: String,
    val description: String,
    val resources: List<GrantApplication.AllocationRequest>,
    val renewEvery: Int,
    val criteria: List<UserCriteria>,
)

Properties

id: Long

resourcesOwnedBy: String A reference to the project which owns these resources

title: String The title of a gift

Suitable for presentation in UIs

description: String The title of a gift

Suitable for presentation in UIs

resources: List<GrantApplication.AllocationRequest> A list of resources which will be granted to users `Gifts.claimGift` this `Gift`.

renewEvery: Int Renewal policy for the gift

criteria: List<UserCriteria>

---

ClaimGiftRequest

data class ClaimGiftRequest(
    val giftId: Long,
)

Properties

giftId: Long

---

DeleteGiftRequest

data class DeleteGiftRequest(
    val giftId: Long,
)

Properties

giftId: Long

---

Gifts.Browse.Request

The base type for requesting paginated content.

data class Request(
    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

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

---

AvailableGiftsResponse

data class AvailableGiftsResponse(
    val gifts: List<FindByLongId>,
)

Properties

gifts: List<FindByLongId>

---