Core Types

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

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

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

data class FindByLongId(
    val id: Long,
)

Properties

id: Long

---

FindByStringId

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

data class FindByStringId(
    val id: String,
)

Properties

id: String

---

Page

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

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

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

A minimal representation of a security principal.

data class SecurityPrincipal(
    val username: String,
    val role: Role,
    val firstName: String,
    val lastName: String,
    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.

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

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

Properties

itemsPerPage: Int?

page: Int?

---

PaginationRequestV2Consistency

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.

---

BulkRequest

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

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

Properties

responses: List<T>

---