Core Types

API: Stable

Table of Contents

1. Data Models
Name Description
CommonErrorMessage A generic error message
FindByLongId A request message to find a resource by a numeric unique identifier.
FindByStringId A request message to find a resource by a unique identifier.
Page A page of items. Superseded by PageV2.
PageV2 Represents a single 'page' of results
Role Represents a `SecurityPrincipal`'s system-wide role.
SecurityPrincipal A minimal representation of a security principal.
PaginationRequest No description
PaginationRequestV2Consistency No description
BulkRequest A base type for requesting a bulk operation.
BulkResponse No description

Data Models

CommonErrorMessage

API: Stable

A generic error message

data class CommonErrorMessage(
    val why: String,
    val errorCode: String?,
)

UCloud uses HTTP status code for all error messages. In addition and if possible, UCloud will include a message using a common format. Note that this is not guaranteed to be included in case of a failure somewhere else in the network stack. For example, UCloud’s load balancer might not be able to contact the backend at all. In such a case UCloud will not include a more detailed error message.

Properties
why: String Human readable description of why the error occurred. This value is generally not stable.
errorCode: String? Machine readable description of why the error occurred. This value is stable and can be relied upon.

FindByLongId

API: Stable

A request message to find a resource by a numeric unique identifier.

data class FindByLongId(
    val id: Long,
)
Properties
id: Long

FindByStringId

API: Stable

A request message to find a resource by a unique identifier.

data class FindByStringId(
    val id: String,
)
Properties
id: String

Page

API: Stable Deprecated: Yes

A page of items. Superseded by PageV2.

data class Page<T>(
    val itemsInTotal: Int,
    val itemsPerPage: Int,
    val pageNumber: Int,
    val items: List<T>,
)
Properties
itemsInTotal: Int
itemsPerPage: Int
pageNumber: Int
items: List<T>

PageV2

API: Stable

Represents a single ‘page’ of results

data class PageV2<T>(
    val itemsPerPage: Int,
    val items: List<T>,
    val next: String?,
)

Every page contains the items from the current result set, along with information which allows the client to fetch additional information.

Properties
itemsPerPage: Int The expected items per page, this is extracted directly from the request
items: List<T> The items returned in this page

NOTE: The amount of items might differ from itemsPerPage, even if there are more results. The only reliable way to check if the end of results has been reached is by checking i next == null.

next: String? The token used to fetch additional items from this result set

Role

API: Stable

Represents a SecurityPrincipal’s system-wide role.

enum class Role {
    GUEST,
    USER,
    ADMIN,
    SERVICE,
    THIRD_PARTY_APP,
    PROVIDER,
    UNKNOWN,
}

This is usually not used for application-specific authorization.

Services are encouraged to implement their own authorization control, potentially from a common library.

Properties
GUEST The security principal is an unauthenticated guest
USER The security principal is a normal end-user.

Normal end users can also have “admin-like” privileges in certain parts of the application.

ADMIN The security principal is an administrator of the system.

Very few users should have this role.

SERVICE The security principal is a first party, __trusted__, service.
THIRD_PARTY_APP The security principal is some third party application.

This type of role is currently not used. It is reserved for potential future purposes.

PROVIDER
UNKNOWN The user role is unknown.

If the action is somewhat low-sensitivity it should be fairly safe to assume USER/THIRD_PARTY_APP privileges. This means no special privileges should be granted to the user.

This will only happen if we are sent a token of a newer version that what we cannot parse.


SecurityPrincipal

API: Stable

A minimal representation of a security principal.

data class SecurityPrincipal(
    val username: String,
    val role: Role,
    val firstName: String,
    val lastName: String,
    val uid: Long,
    val email: String?,
    val twoFactorAuthentication: Boolean?,
    val principalType: String?,
    val serviceAgreementAccepted: Boolean?,
    val organization: String?,
)

More information can be gathered from an auth service, using the username as a key.

Properties
username: String The unique username of this security principal.

This is usually suitable for display in UIs.

role: Role The role of the security principal
firstName: String The first name of the security principal. Can be empty.
lastName: String The last name of the security principal. Can be empty.
uid: Long A numeric unique identifier for this principal. The username is the preferred unique identifier.
email: String? The email of the user
twoFactorAuthentication: Boolean? A boolean flag indicating if the user has 2FA enabled for their user.

If the token does not contain this information (old tokens generated before field’s introduction) then this will be set to true. This is done to avoid breaking extended tokens. This behavior will should change in a future update.

All new tokens should contain this information explicitly.

principalType: String?
serviceAgreementAccepted: Boolean? A boolean indicating if the service agreement has been accepted
organization: String?

PaginationRequest

API: Stable Deprecated: Yes

data class PaginationRequest(
    val itemsPerPage: Int?,
    val page: Int?,
)
Properties
itemsPerPage: Int?
page: Int?

PaginationRequestV2Consistency

API: Stable

enum class PaginationRequestV2Consistency {
    PREFER,
    REQUIRE,
}
Properties
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.

Deprecated: Yes


BulkRequest

API: Stable

A base type for requesting a bulk operation.

data class BulkRequest<T>(
    val items: List<T>,
)

⚠ WARNING: All request items listed in the bulk request must be treated as a single transaction. This means that either the entire request succeeds, or the entire request fails.

There are two exceptions to this rule:

  1. Certain calls may choose to only guarantee this at the provider level. That is if a single call contain request for multiple providers, then in rare occasions (i.e. crash) changes might not be rolled back immediately on all providers. A service MUST attempt to rollback already committed changes at other providers.

  2. The underlying system does not provide such guarantees. In this case the service/provider MUST support the verification API to cleanup these resources later.


Properties
items: List<T>

BulkResponse

API: Stable

data class BulkResponse<T>(
    val responses: List<T>,
)
Properties
responses: List<T>