Overview
Ubicloud APIs (Beta) allow users to programmatically manage their resources.
The API is designed with predictable endpoints and an intuitive design, making it easy to understand and use. It adheres to REST principles, allowing users to send requests using any client that supports HTTPS requests to Ubicloud API endpoints. All request and response bodies are in JSON format.
Authentication
The Ubicloud API uses personal access tokens for authentication. If you have not already created a personal access token for your project, you can create one by going to the Tokens page for your project, and clicking the Create Token button:
That will create a personal access token. Click on the clipboard icon under the token heading to copy the token to your clipboard:
You must pass the personal access token in the authorization header for all subsequent requests. Examples are provided in the API reference.
Requests
API communicates with clients via HTTPS requests. All data sent in request bodies must be in JSON format. The API supports the following HTTP methods:
| Method | Usage |
|---|---|
| GET | Retrieves either a single resource or a list of resources. Supports pagination for lists. |
| POST | Creates a resource. All required attributes must be included in the JSON body of the request. Also allows for executing actions on resources. |
| DELETE | Deletes a resource. If the given resource URI is valid, it returns a 204 status code irrespective of the resource exists or not. |
| PATCH | Updates a resource. All required attributes must be included in the JSON body of the request. |
Responses
Following HTTP response status codes can be returned from the API.
| Status | Description |
|---|---|
| 200 | Request was successful |
| 204 | Request was successful and no content returns back |
| 400 | Invalid request |
| 401 | Not authenticated to the API |
| 403 | Unauthorized user access |
| 404 | Resource not found |
| 409 | Resource state is not valid to handle request |
| 419 | Invalid Token |
| 500 | Unexpected internal error |
All the responses except the ones with the HTTP code 204 returns the content in the JSON format.
API Design
This section explains core concepts of the Ubicloud API.
Global and Location Based Resources
Ubicloud API users can manage two types of resources: global and location-based.
Global resources on Ubicloud are created independently of any specific location. Global resources can be managed with the API currently are projects, firewalls and firewall rules. Global resources do not have a globally unique name but do have a globally unique ID. Therefore, users can create multiple global resource of the same type with the same name, and each will be assigned a unique ID.
Resources created under a specific project and location are termed location-based resources. Users can create resources in various locations for a given project. Location-based resources have unique IDs and also names unique at the project and location level. The uniqueness of names allows API to make requests idempotent by using the name as an idempotency token.
Accessing Resources
As mentioned above, all resources have unique IDs, and location-based resources also have unique names. Resources can be accessed either by their ID or by their name (if available). We refer to the former as static access and the latter as dynamic access, because static access allows users to access the same resource even if its name changes (note that renaming resources is not supported yet).
For global resources, which have only a unique ID, users can access a specific resource by its ID. For example, to retrieve a project with ID pj1234ab9eyt7jd4zmwby6ymd3, user would send a GET request to api.ubicloud.com/project/pj1234ab9eyt7jd4zmwby6ymd3.
For location-based resources, which have both unique IDs and names, users can access them either way. For example, a VM named my-ubicloud-vm with ID vm123451fzj3k70d3p8f1709s in the pj1234ab9eyt7jd4zmwby6ymd3 project located in eu-north-h1 can be accessed either via api.ubicloud.com/project/pj1234ab9eyt7jd4zmwby6ymd3/location/eu-north-h1/vm/my-ubicloud-vm or api.ubicloud.com/project/pj1234ab9eyt7jd4zmwby6ymd3/location/eu-north-h1/vm/id/vm123451fzj3k70d3p8f1709s. This enables both dynamic and static access as described.
Creating Resources
To create a global resource all attributes must be sent in the body. For example to create a project, send a POST request to api.ubicloud.com/project with the required parameters in the body of the request. To create a firewall in the project pj1234ab9eyt7jd4zmwby6ymd3 user can send a POST request to api.ubicloud.com/project/pj1234ab9eyt7jd4zmwby6ymd3/firewall with all the required parameters in the body.
For creating location-based resources, Ubicloud supports a more condensed and straightforward method. Instead of sending a POST request to the parent URI of the resource, user can send a POST request directly to the resource’s URI using its unique name, making the requests idempotent. For example, to create the previously mentioned VM, user would send a POST request to api.ubicloud.com/project/pj1234ab9eyt7jd4zmwby6ymd3/location/eu-north-h1/vm/my-ubicloud-vm with other required parameters in the request body. Essentially, URIs including the name of location-based resources can be used like variables in programming, simplifying creation, access, and deletion. No need to have a special case forPOST requests.
Deleting Resources
To delete a resource, user would send a DELETE request using the ID for global resources and either the ID or name for location-based resources. The DELETE endpoints return a 204 status code, whether the resource was deleted or did not exist to simplify client implementation. Note that, DELETE requests can still return 404 if the given resource URI is not a valid one. Please check the API reference for sample usage.
Listing Resources with Pagination Support
Users would send a GET request to the resource’s parent URI to retrieve a list of resources. For instance, a request to api.ubicloud.com/project will return all the projects user has created. All listing endpoints on Ubicloud support pagination, using cursor-based pagination as it scales better and handles parallel operations more effectively than offset-based pagination. Users can pass three different query parameters to list endpoints:
order_column: Specifies the attribute by which pages will be ordered. Each list endpoint supports ordering by id, and those with unique names also support ordering by name.
start_after: A polymorphic value after which the page will include resources. Its’ type depends on the value of order_column. If order_column is id, the value of start_after must be a valid ID. If it is name, the value of start_after can be any text. For example, to get a paginated list of VMs named alphabetically after “my-ubi”, set the order_column to “name” and start_after to “my_ubi”.
page_size: Indicates how many items will be returned in a page. The default value is 1000, and it must be between 1 and 1000.
This polymorphic start_after value helps us continue returning pages even if the record with the given start_after value is deleted in parallel. We do not try to retrieve a resource with the start_after value but compare existing items’ related column with the passed value directly, overcoming a main limitation of cursor-based pagination.
List endpoints return the response JSON with two keys: items, which holds the list of resources, and count, which keeps track of how many resources exist in total.
UBID
You might be curious why unique IDs for projects start with “pj” and those for virtual machines start with “vm”. This is intentional to make life easier for both Ubicloud developers and users. As soon as you see a resource’s ID, you can immediately understand its type, as different types of resources have different two-letter prefixes. We call these ubids, and you can see how they are both user-friendly and globally unique from the implementation.