Software Licenses

API: Experimental/Alpha

Licenses act as a key to certain restricted software.

Rationale

📝 NOTE: This API follows the standard Resources API. We recommend that you have already read and understood the concepts described here.


Users must attach a license to a Job for it to work. When attached, the software should be available. In most cases, a license is a parameter of an Application.


📝 NOTE: UCloud does not store any information about license keys, servers or any other credentials. It is the responsibility of the provider to store this information.


Table of Contents

1. Examples
Description
Create and configure a license
2. Remote Procedure Calls
Name Description
browse Browses the catalog of available resources
retrieve Retrieve a single resource
retrieveProducts Retrieve product support for all accessible providers
search Searches the catalog of available resources
create Creates one or more resources
delete Deletes one or more resources
init Request (potential) initialization of resources
updateAcl Updates the ACL attached to a resource
3. Data Models
Name Description
License A `License` for use in `Job`s
LicenseIncludeFlags No description
LicenseSpecification No description
LicenseState No description
LicenseStatus The status of an `License`
LicenseSupport No description
LicenseUpdate No description

Example: Create and configure a license

Frequency of useCommon
Actors
  • An authenticated user (user)
Communication Flow: Kotlin
/* In this example we will see how to create and manage a software license */

Licenses.retrieveProducts.call(
    Unit,
    user
).orThrow()

/*
SupportByProvider(
    productsByProvider = mapOf("example" to listOf(ResolvedSupport(
        product = Product.License(
            category = ProductCategoryId(
                id = "example-license", 
                name = "example-license", 
                provider = "example", 
            ), 
            chargeType = ChargeType.ABSOLUTE, 
            description = "An example license", 
            freeToUse = false, 
            hiddenInGrantApplications = false, 
            name = "example-license", 
            pricePerUnit = 1, 
            priority = 0, 
            productType = ProductType.LICENSE, 
            tags = emptyList(), 
            unitOfPrice = ProductPriceUnit.PER_UNIT, 
            version = 1, 
            balance = null, 
            id = "example-license", 
        ), 
        support = LicenseSupport(
            product = ProductReference(
                category = "example-license", 
                id = "example-license", 
                provider = "example", 
            ), 
        ), 
    ))), 
)
*/
Licenses.create.call(
    bulkRequestOf(LicenseSpecification(
        product = ProductReference(
            category = "example-license", 
            id = "example-license", 
            provider = "example", 
        ), 
    )),
    user
).orThrow()

/*
BulkResponse(
    responses = listOf(FindByStringId(
        id = "5123", 
    )), 
)
*/
Licenses.retrieve.call(
    ResourceRetrieveRequest(
        flags = LicenseIncludeFlags(
            filterCreatedAfter = null, 
            filterCreatedBefore = null, 
            filterCreatedBy = null, 
            filterIds = null, 
            filterProductCategory = null, 
            filterProductId = null, 
            filterProvider = null, 
            filterProviderIds = null, 
            hideProductCategory = null, 
            hideProductId = null, 
            hideProvider = null, 
            includeOthers = false, 
            includeProduct = false, 
            includeSupport = false, 
            includeUpdates = false, 
        ), 
        id = "5123", 
    ),
    user
).orThrow()

/*
License(
    createdAt = 1635170395571, 
    id = "5123", 
    owner = ResourceOwner(
        createdBy = "user", 
        project = null, 
    ), 
    permissions = null, 
    specification = LicenseSpecification(
        product = ProductReference(
            category = "example-license", 
            id = "example-license", 
            provider = "example", 
        ), 
    ), 
    status = LicenseStatus(
        boundTo = emptyList(), 
        resolvedProduct = null, 
        resolvedSupport = null, 
        state = LicenseState.READY, 
    ), 
    updates = emptyList(), 
    providerGeneratedId = "5123", 
)
*/
Communication Flow: TypeScript
/* In this example we will see how to create and manage a software license */

// Authenticated as user
await callAPI(LicensesApi.retrieveProducts(
    {
    }
);

/*
{
    "productsByProvider": {
        "example": [
            {
                "product": {
                    "balance": null,
                    "name": "example-license",
                    "pricePerUnit": 1,
                    "category": {
                        "name": "example-license",
                        "provider": "example"
                    },
                    "description": "An example license",
                    "priority": 0,
                    "tags": [
                    ],
                    "version": 1,
                    "freeToUse": false,
                    "unitOfPrice": "PER_UNIT",
                    "chargeType": "ABSOLUTE",
                    "hiddenInGrantApplications": false,
                    "productType": "LICENSE"
                },
                "support": {
                    "product": {
                        "id": "example-license",
                        "category": "example-license",
                        "provider": "example"
                    }
                }
            }
        ]
    }
}
*/
await callAPI(LicensesApi.create(
    {
        "items": [
            {
                "product": {
                    "id": "example-license",
                    "category": "example-license",
                    "provider": "example"
                }
            }
        ]
    }
);

/*
{
    "responses": [
        {
            "id": "5123"
        }
    ]
}
*/
await callAPI(LicensesApi.retrieve(
    {
        "flags": {
            "includeOthers": false,
            "includeUpdates": false,
            "includeSupport": false,
            "includeProduct": false,
            "filterCreatedBy": null,
            "filterCreatedAfter": null,
            "filterCreatedBefore": null,
            "filterProvider": null,
            "filterProductId": null,
            "filterProductCategory": null,
            "filterProviderIds": null,
            "filterIds": null,
            "hideProductId": null,
            "hideProductCategory": null,
            "hideProvider": null
        },
        "id": "5123"
    }
);

/*
{
    "id": "5123",
    "specification": {
        "product": {
            "id": "example-license",
            "category": "example-license",
            "provider": "example"
        }
    },
    "owner": {
        "createdBy": "user",
        "project": null
    },
    "createdAt": 1635170395571,
    "status": {
        "state": "READY",
        "resolvedSupport": null,
        "resolvedProduct": null,
        "boundTo": [
        ]
    },
    "updates": [
    ],
    "permissions": null
}
*/
Communication Flow: Curl
# ------------------------------------------------------------------------------------------------------
# $host is the UCloud instance to contact. Example: 'http://localhost:8080' or 'https://cloud.sdu.dk'
# $accessToken is a valid access-token issued by UCloud
# ------------------------------------------------------------------------------------------------------

# In this example we will see how to create and manage a software license

# Authenticated as user
curl -XGET -H "Authorization: Bearer $accessToken" "$host/api/licenses/retrieveProducts" 

# {
#     "productsByProvider": {
#         "example": [
#             {
#                 "product": {
#                     "balance": null,
#                     "name": "example-license",
#                     "pricePerUnit": 1,
#                     "category": {
#                         "name": "example-license",
#                         "provider": "example"
#                     },
#                     "description": "An example license",
#                     "priority": 0,
#                     "tags": [
#                     ],
#                     "version": 1,
#                     "freeToUse": false,
#                     "unitOfPrice": "PER_UNIT",
#                     "chargeType": "ABSOLUTE",
#                     "hiddenInGrantApplications": false,
#                     "productType": "LICENSE"
#                 },
#                 "support": {
#                     "product": {
#                         "id": "example-license",
#                         "category": "example-license",
#                         "provider": "example"
#                     }
#                 }
#             }
#         ]
#     }
# }

curl -XPOST -H "Authorization: Bearer $accessToken" -H "Content-Type: content-type: application/json; charset=utf-8" "$host/api/licenses" -d '{
    "items": [
        {
            "product": {
                "id": "example-license",
                "category": "example-license",
                "provider": "example"
            }
        }
    ]
}'


# {
#     "responses": [
#         {
#             "id": "5123"
#         }
#     ]
# }

curl -XGET -H "Authorization: Bearer $accessToken" "$host/api/licenses/retrieve?includeOthers=false&includeUpdates=false&includeSupport=false&includeProduct=false&id=5123" 

# {
#     "id": "5123",
#     "specification": {
#         "product": {
#             "id": "example-license",
#             "category": "example-license",
#             "provider": "example"
#         }
#     },
#     "owner": {
#         "createdBy": "user",
#         "project": null
#     },
#     "createdAt": 1635170395571,
#     "status": {
#         "state": "READY",
#         "resolvedSupport": null,
#         "resolvedProduct": null,
#         "boundTo": [
#         ]
#     },
#     "updates": [
#     ],
#     "permissions": null
# }
Communication Flow: Visual

Remote Procedure Calls

browse

API: Experimental/Alpha Auth: Users

Browses the catalog of available resources

Request Response Error
ResourceBrowseRequest<LicenseIncludeFlags> PageV2<License> CommonErrorMessage

retrieve

API: Experimental/Alpha Auth: Users

Retrieve a single resource

Request Response Error
ResourceRetrieveRequest<LicenseIncludeFlags> License CommonErrorMessage

retrieveProducts

API: Experimental/Alpha Auth: Users

Retrieve product support for all accessible providers

Request Response Error
Unit SupportByProvider<Product.License, LicenseSupport> CommonErrorMessage

This endpoint will determine all providers that which the authenticated user has access to, in the current workspace. A user has access to a product, and thus a provider, if the product is either free or if the user has been granted credits to use the product.

See also:

create

API: Experimental/Alpha Auth: Users

Creates one or more resources

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

delete

API: Experimental/Alpha Auth: Users

Deletes one or more resources

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

init

API: Experimental/Alpha Auth: Users

Request (potential) initialization of resources

Request Response Error
Unit 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.

updateAcl

API: Experimental/Alpha Auth: Users

Updates the ACL attached to a resource

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

Data Models

License

API: Experimental/Alpha

A License for use in Jobs

data class License(
    val id: String,
    val specification: LicenseSpecification,
    val owner: ResourceOwner,
    val createdAt: Long,
    val status: LicenseStatus,
    val updates: List<LicenseUpdate>?,
    val permissions: ResourcePermissions?,
    val providerGeneratedId: String?,
)
Properties
id: String A unique identifier referencing the `Resource`

The ID is unique across a provider for a single resource type.

specification: LicenseSpecification
owner: ResourceOwner Information about the owner of this resource
createdAt: Long Information about when this resource was created
status: LicenseStatus The current status of this resource
updates: List<LicenseUpdate>? A list of updates for this `License`
permissions: ResourcePermissions? Permissions assigned to this resource

A null value indicates that permissions are not supported by this resource type.

providerGeneratedId: String?

API: Internal/Beta


LicenseIncludeFlags

API: Internal/Beta

data class LicenseIncludeFlags(
    val includeOthers: Boolean?,
    val includeUpdates: Boolean?,
    val includeSupport: Boolean?,
    val includeProduct: Boolean?,
    val filterCreatedBy: String?,
    val filterCreatedAfter: Long?,
    val filterCreatedBefore: Long?,
    val filterProvider: String?,
    val filterProductId: String?,
    val filterProductCategory: String?,
    val filterProviderIds: String?,
    val filterIds: String?,
    val hideProductId: String?,
    val hideProductCategory: String?,
    val hideProvider: String?,
)
Properties
includeOthers: Boolean?
includeUpdates: Boolean?
includeSupport: Boolean?
includeProduct: Boolean? Includes `specification.resolvedProduct`
filterCreatedBy: String?
filterCreatedAfter: Long?
filterCreatedBefore: Long?
filterProvider: String?
filterProductId: String?
filterProductCategory: String?
filterProviderIds: String? Filters by the provider ID. The value is comma-separated.
filterIds: String? Filters by the resource ID. The value is comma-separated.
hideProductId: String?
hideProductCategory: String?
hideProvider: String?

LicenseSpecification

API: Internal/Beta

data class LicenseSpecification(
    val product: ProductReference,
)
Properties
product: ProductReference The product used for the `License`

LicenseState

API: Experimental/Alpha

enum class LicenseState {
    PREPARING,
    READY,
    UNAVAILABLE,
}
Properties
PREPARING A state indicating that the `License` is currently being prepared and is expected to reach `READY` soon.
READY A state indicating that the `License` is ready for use or already in use.
UNAVAILABLE A state indicating that the `License` is currently unavailable.

This state can be used to indicate downtime or service interruptions by the provider.


LicenseStatus

API: Internal/Beta

The status of an License

data class LicenseStatus(
    val state: LicenseState,
    val resolvedSupport: ResolvedSupport<Product.License, LicenseSupport>?,
    val resolvedProduct: Product.License?,
    val boundTo: List<String>?,
)
Properties
state: LicenseState
resolvedSupport: ResolvedSupport<Product.License, LicenseSupport>?
resolvedProduct: Product.License? The resolved product referenced by `product`.

This attribute is not included by default unless includeProduct is specified.

boundTo: List<String>? The IDs of the `Job`s that this `Resource` is currently bound to

LicenseSupport

API: Internal/Beta

data class LicenseSupport(
    val product: ProductReference,
)
Properties
product: ProductReference

LicenseUpdate

API: Experimental/Alpha

data class LicenseUpdate(
    val timestamp: Long?,
    val state: LicenseState?,
    val status: String?,
    val binding: JobBinding?,
)
Properties
timestamp: Long? A timestamp for when this update was registered by UCloud
state: LicenseState? The new state that the `License` transitioned to (if any)
status: String? A new status message for the `License` (if any)
binding: JobBinding?