diff --git a/doc/source/api/smaug_api.v1.md b/doc/source/api/smaug_api.v1.md new file mode 100644 index 00000000..b30b207f --- /dev/null +++ b/doc/source/api/smaug_api.v1.md @@ -0,0 +1,353 @@ +# Tenant API + +## Protection Plan + +### Create a Protection Plan + + +`POST` : `/v1/{tenant_id}/plans/` + +#### Request parameters +|Parameter|Style|Type|Description +|:-|:-|:-|:- +|tenant_id|URI|csapi:UUID|The tenant ID in a multi-tenancy cloud. +|name|plain|xsd:string|Friendly name for the plan. +|comments (optional)|plain|xsd:string| Plan comments. +|bank_id|plain|xsd:string|Id of the bank. + +#### Response JSON +```json +{ + "plan": { + "id": "93df2f9b-5a67-1111-1518-d177ad4c02dc", + "name": "My Plan", + "comments": "This protects everything that I love", + "bank_id": "12312412321", + "protection_defintions": [ + ] + } +} +``` + +### List Protection Plans +`GET` : `/v1/{tenant_id}/plans/` +#### Request parameters +|Parameter|Style|Type|Description +|:-|:-|:-|:- +|tenant_id|URI|csapi:UUID|The tenant ID in a multi-tenancy cloud +|name (Optional)|query|regexp|Name of the plan as a string. Can be queried with regular expressions. +|sort (Optional)|query|xsd:string|Comma-separated list of sort keys and optional sort directions in the form of `[:]`. A valid direction is asc (ascending) or desc (descending). +|limit (Optional)|query|xsd:int|Requests a specified page size of returned items from the query. Returns a number of items up to the specified limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request. +|marker (Optional)|query|xsd:string|Specifies the ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request. +#### Response JSON +```json +{ + "plans": [ + { + "name": "My Plan", + "id": "666", + "comments": "This protects everything that I love", + "bank_id": "12312412321" + } + ] +``` +### Show backup plan details +`GET` : `/v1/plans/{plan_id}` +#### Request parameters +|Parameter|Style|Type|Description +|:-|:-|:-|:- +|tenant_id|URI|csapi:UUID| The tenant ID in a multi-tenancy cloud. +|plan_id|url|xsd:string|The plan ID. +#### Response JSON +```json +{ + "id": "123", + "name": "My Plan", + "comments": "This protects everything that I love", + "bank_id": "12312412321", + "protection_defintions": [ + ] +} +``` +## Protection Definition +### Create a protection definition +`POST` : `/v1/{tenant_id}/plans//protection_defintions/` +#### Request parameters +|Parameter|Style|Type|Description +|:-|:-|:-|:- +|tenant_id|URI|csapi:UUID| The tenant ID in a multi-tenancy cloud. +|name|plain|xsd:string|Friendly name for the plan. +|description (optional)|plain|xsd:string|Plan description. +|resource| plain | xsd:dict| Resource instance id. +|plugin_id| plain | xsd:string | protection plugin id. +|parameters| plain | xsd:dict| parameters for the actions +#### Response JSON +```json +{ + "name": "Frontend VM", + "id": "45baf976-c20a-4894-3333-c94b7376bf55", + "comments": "Back it all up like there is no tomorrow", + "resource": { + "resource_type": "OS:NOVA:Server", + "resource_id": "93df2f9b-5a67-4155-a518-d177ad4c02dc" + }, + "plugin_id": "93df2f9b-5a67-4155-1518-d177ad4c02dc", + "parameters": { + "protect":{ + }, + "restore":{ + }, + "verify":{ + }, + "delete":{ + } + } +} +``` +## Protection Plugin +### List available plugins +`GET` : `/v1/protection_plugins/` +#### Request parameters +|Parameter|Style|Type|Description +|:-|:-|:-|:- +|managed_type|query|xsd:string|Filter by the resource type that the plugin manages. +#### Response JSON +```json +{ + "protection_plugins": [ + { + "id": "123", + "name": "Cinder Volume S3 Backup", + "description": "Backs up cinder volumes to S3", + "managed_type": "OS:Cinder:Volume", + "extended_info_schema": {} + } + ] +} +``` +### Show information about an action +`GET` : `/v1/protection_plugins/{plugin_id}/actions/{protect,verify,delete,restore}` +#### Response JSON +```json +{ + "actions_info": [ + "protect":{ + "name": "Start Backup", + "description": "Backs up stuff", + "parameters_schema": {}, + "result_schema": {} + }, + "restore":{ + }, + "verify":{ + }, + "delete":{ + } + ] +} +``` +### Get which resources can be protected by Protecteion Plugin +`GET`:`/v1/{tenant_id}/protection_plugins/{plugin_id}/list` +| Parameter | Style | Type | Description | +| :----------------------------------- | :---: | :---------: | :---------- | +| tenant_id | URI |csapi:UUID | The tenant ID in a multi-tenancy cloud. +| sort (Optional) | query | xsd:string | Comma-separated list of sort keys and optional sort directions in the form of [:]. A valid direction is asc (ascending) or desc (descending). | +| limit (Optional) | query | xsd:int | Requests a specified page size of returned items from the query. Returns a number of items up to the specified limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request. | +|marker (Optional) |query |xsd:string| Specifies the ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request. + +## Get which resources are dependent on a specific parent resource +GET` : `/v1/{tenant_id}/protection_plugins/{plugin_id}/get_dependent_resources` +| Parameter | Style | Type | Description | +| :----------------------------------- | :---: | :---------: | :---------- | +| tenant_id| URI |csapi:UUID | The tenant ID in a multi-tenancy cloud. +| parent_resource| plain | xsd:dict | Resource instance | + +```json + "depended_resources": [ + "resource": { + "resource_type": "...", + "resource_id": "93df2f9b-5a67-4155-a518-d177ad4c02dc" + }, + "resource: { + ... + } +``` + +## Bank Plugin + +### List available bank plugins + +`GET` : `/v1/bank_plugins/` + +```json + +``` + +## Bank + +### List available banks + +`GET` : `/v1/{tenant_id}/banks/` + +### Show information about a bank + +`GET` : `/v1/{tenant_id}/banks/{bank_id}` + +## Operations + +### List operations + +`GET` : `/v1/{tenant_id}/{plan_id}/operations/` + +### Show information about an operation + +`GET` : `/v1/{tenant_id}/{plan_id}/operations/{operation_id}` + + +### Create an operation + +`POST` : `/v1/{tenant_id}/operations/` + +| Parameter | Style | Type | Description | +| :----------------------------------- | :---: | :---------: | :---------- | +| tenant_id | URI |csapi:UUID | The tenant ID in a multi-tenancy cloud. +| plan_id | plain | xsd:string | ID of the plan you want to execute. | +| operation_type | plain | xsd:string | Type of the operation. [protect, verify, delete, restore] + +### Show operation status + +`POST` : `/v1/{tenant_id}/operations/{operatin_id}` + +```json +{ + "id": "123", + "operation_type": "protect", + "status": "in progress" +} +``` +### Schedule operation +`POST` : `/v1/{tenant_id}/operations/schedule` + +| Parameter | Style | Type | Description | +| :----------------------------------- | :---: | :---------: | :---------- | +| tenant_id | URI |csapi:UUID | The tenant ID in a multi-tenancy cloud. +| plan_id | plain | xsd:string | ID of the plan you want to execute. | +| operation_type | plain | xsd:string | Type of the operation. [protect, verify, delete, restore] +| trigger_id| plain | xsd:string | ID of the trigger that will be used to schedule this operation + +```json +{ + "schedule": + { + "name": "Daily run of my app backup", + "id": "666", + "plan-id": "45baf976-c20a-4894-a7c3-c94b7376bf3bb", + "comments": "Backup my App every day at 06:00", + "trigger_id": "45baf976-c20a-4894-a7c3-c94b7376bffff" + } +``` + +`GET` : `/v1/{tenant_id}/{plan_id}/operations/schedule` + +Normal response codes 200 + +Request parameters +| Parameter | Style | Type | Description | +| :----------------------------------- | :---: | :---------: | :---------- | +| tenant_id | URI |csapi:UUID | The tenant ID in a multi-tenancy cloud. +| sort (Optional) | query | xsd:string | Comma-separated list of sort keys and optional sort directions in the form of [:]. A valid direction is asc (ascending) or desc (descending). | +| limit (Optional) | query | xsd:int | Requests a specified page size of returned items from the query. Returns a number of items up to the specified limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request. | +|marker (Optional) |query |xsd:string| Specifies the ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request. +```json +{ + "schedule": [ + { + "name": "Daily run of my app backup", + "id": "666", + "plan-id": "45baf976-c20a-4894-a7c3-c94b7376bf3bb", + "comments": "Backup my App every day at 06:00", + "trigger_id": "45baf976-c20a-4894-a7c3-c94b7376bffff" + }, + { + } + ] +``` +## Triggers + +### Create a Trigger + +`POST` : `/v1/{tenant_id}/triggers/` +##### Request parameters +| Parameter | Style | Type | Description | +| :--------------------- | :---: | :----------: | :---------- | +| name | plain | xsd:string | The name of the storage pool. | +| description (optional) | plain | xsd:string | The description of the storage pool. | +| type | plain | xsd:string | The type of the trigger. | +##### Extra fields for `type=="timed_trigger"` +| Parameter | Style | Type | Description | +| :------------- | :---: | :----------: | :---------- | +| start_time | plain | xsd:datetime | The time when the trigger will invoke. | +| trigger_window | plain | xsd:duration | The window in which the trigger can still trigger in cases where the original start time was missed. | +| recurrence | plain | xsd:string | Recurrence as defined by iCalendar RFC 2445 | + + + +### List Triggers + +`GET` : `/v1/{tenant_id}/triggers/` + +### Show information about a Trigger + +`GET` : `/v1/{tenant_id}/triggers/{trigger_id}` + +### Ledger Transactions information + +`GET` : `/v1/{tenant_id}/{plan_id}/transaction/` +##### Request parameters +| Parameter | Style | Type | Description | +| :----------------------------------- | :---: | :---------: | :---------- | +| tenant_id | URI |csapi:UUID | The tenant ID in a multi-tenancy cloud. +| sort (Optional) | query | xsd:string | Comma-separated list of sort keys and optional sort directions in the form of [:]. A valid direction is asc (ascending) or desc (descending). | +| limit (Optional) | query | xsd:int | Requests a specified page size of returned items from the query. Returns a number of items up to the specified limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request. | +|marker (Optional) |query |xsd:string| Specifies the ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request. +```json +{ + "transactions": [ + { + "id": "45baf976-c20a-4894-a7c3-c94b7376bf55", + "started_at": "2019-02-25T02:40:21.000000", + "status": "in progress", + "plugins": { + "protection_plugin_1":{ + "id": "123", + "name": "Cinder Volume S3 Backup", + "description": "Backs up cinder volumes to S3", + "version" "1.2.3", + "protection_definition_id": "45baf976-c20a-4894-3333-c94b7376bf55" + }, + { + ... + } + } + } + ] +} +``` + +`GET` : `/v1/{tenant_id}/{plan_id}/transaction/{transaction_id}/{protection_definition_id}`/` +##### Request parameters +| Parameter | Style | Type | Description | +| :----------------------------------- | :---: | :---------: | :---------- | +| tenant_id | URI |csapi:UUID | The tenant ID in a multi-tenancy cloud. +| sort (Optional) | query | xsd:string | Comma-separated list of sort keys and optional sort directions in the form of [:]. A valid direction is asc (ascending) or desc (descending). | +| limit (Optional) | query | xsd:int | Requests a specified page size of returned items from the query. Returns a number of items up to the specified limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request. | +|marker (Optional) |query |xsd:string| Specifies the ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request. + +```json +{ + "plugin": "plugin_1", + "dependencies": { + "vol1": "" + } +} +```