↑ Go up

Action API

API for background action operations

Version: 0.1.0

Server

  • URL: https://api.kopernik.us/v0
    • Kopernik.us API server

Paths

/action/{providerUid}

GET

List actions

List actions for the specified provider

Parameters:

Name In Type Required Description
providerUid path ProviderId ✅ Unique identifier of the provider

Responses:

  • 200: Actions list

  • 400: Argument validation error

/action/{providerUid}/{actionUid}

GET

Get action

Get action details

Parameters:

Name In Type Required Description
providerUid path ProviderId ✅ Unique identifier of the provider
actionUid path string ✅ Unique identifier of the action

Responses:

  • 200: Action details.

Note: this operation returns successful HTTP response (200) even if the underlying action failed. Action status and result can be accessed via the returned Action object.

  • Content Type: application/json - Schema: ActionResponse

  • 400: Argument validation error

  • 404: Provider or action not found

Schemas

ActionState

State of the action

Type: enum

Values:

  • pending
  • running
  • success
  • failed
  • rollbackRequested
  • rollbackSuccess
  • rollbackFailed

ActionType

Type of the action.

Type: enum

Values:

  • createResource
  • deleteResource
  • createBlockStorageAttachment
  • deleteBlockStorageAttachment

Action

Action object which represents an asynchronous background operation.

Action objects are typically returned by POST and DELETE requests. They allow to perform long-running operations without blocking the client request.

Action objects represent the current state of the operation, and can be polled periodically to get the latest status.

Action state is represented by its state property, and can be one of the following:

  • pending: the action is waiting to be started
  • running: the action is in progress
  • success: the action completed successfully
  • failed: the action failed
  • rollbackRequested: the action is requesting a rollback
  • rollbackSuccess: the rollback completed successfully
  • rollbackFailed: the rollback failed

These states are final: success, failed, rollbackSuccess, and rollbackFailed. As soon as the action reaches one of these states, it is considered completed and no longer updated.

When the action is in progress, its progress property can be used to get the current progress of the operation. The progress is a number between 0 and 1, usable only when action state is running, and is updated periodically. It does not represent rollback progress.

When the action is failed, its error property contains the reason for the failure. When a failed action is rolled back, and rollback operation fails, too, its rollbackError property contains the reason for last failure.

Client preferring synchronous response can use the waitTime query parameter available for action-returning requests. Setting the value to a large enough value will cause the request to wait until the action is completed, and return the action object with the final state.

Type: object

Properties:

Name Type Required Description
uid string ✅ Unique identifier of the action.
providerUid ProviderId ✅ Cloud provider identifier.
accountUid string ✅ Cloud account identifier.
requestUid string ✅ Unique identifier of the request that started the action.
type ActionType ✅ Type of the action operation.
beginTimestamp number ✅ Timestamp of the action start, in seconds since epoch.
description string ❌ Description of the action.
state ActionState ✅ State of the action.
statusCode number ❌ Status code which represents comlpeted action result, in HTTP status code format.
error string ❌ For failed actions, this is the reason for the failure.
rollbackError string ❌ For failed rollback actions, this is the reason for the rollback failure.
progress number ❌ Progress of the action, between 0 and 1.
resourceType ResourceType ❌ Type of the resource being modified by the action, if any.
objectUid string ❌ Unique identifier of the item being modified by the action, if any. For resource actions, this is the unique identifier of the resource being modified.
duration number ❌ Duration of the action in seconds, when completed.

ActionResponse

Response with action.

Composition: allOf

Type: object

Properties:

Name Type Required Description
action Action ✅

ActionListResponse

Response with list of actions.

Composition: allOf

Type: object

Properties:

Name Type Required Description
actions array<Action> ✅