Ubicloud APIs (Beta) allow users to programmatically manage their resources.
Tokens
page for your project, and clicking the Create Token
button:
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. |
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 |
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.
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.
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.