{ "openapi": "3.0.0", "info": { "title": "COS Resource Configuration API", "description": "## Introduction\n\nThis is a new API for configuring IBM Cloud Object Storage buckets.\n\nThis API will evolve to cover the full suite of bucket configuration options provided today by extensions made to the modified S3 API. The COS Resource Configuration API now supports:\n\n* Viewing non-mutable bucket metadata (CRNs, timestamps, and usage info)\n* Viewing and setting IP address access filters.\n* Viewing and setting Activity Tracker events for object operations.\n\nThe Configuration API supports two request methods. The `Get bucket configuration` method reads a bucket's metadata, and returns an entity tag (`ETag`) header that identifies the current configuration. The tag is updated when some piece of mutable configuration metadata changes. Use the `ETag` with an `if-match` header in the `Update bucket configuration` method to ensure that you are overwriting the correct configuration.\n\n`PATCH` operations can update multiple fields in the same request.\n\nWhat is *mutable configuration metadata*? There's a lot of useful but *non-mutable* metadata associated with a bucket: its name, location, class, the service instance it belongs to, the number of objects it holds, and so on. None of those values can be directly edited by a user but are important for intelligent data management and are necessary for integration with other IBM Cloud services. In contrast, *mutable* bucket metadata adds functionality or alters behavior. In this initial version of the Configuration API, the only such metadata is a bucket's firewall, Activity Tracker, and Metrics Monitoring configurations.\n\nIn direct contrast to an S3 API, the Configuration API doesn't rely on separate methods to access different bucket parameters. For example, in an S3 API you might use these methods:\n1. Read the configuration of a bucket firewall by sending `GET {endpoint}/{bucket}?firewall`.\n2. Read the configuration location with `GET {endpoint}/{bucket}?location`.\n3. Check whether the configuration has Key Protect enabled by sending `HEAD {endpoint}/{bucket}` and reviewing the response headers.\n\nInstead, the Configuration API uses a single JSON document to describe all aspects of a bucket's metadata and configuration with the `Get the bucket configuration` method. To update the configuration, the Configuration API uses [JSON Merge Patch](https://tools.ietf.org/html/rfc7396) semantics to make updates directly to the bucket's metadata. Although you can only update a bucket's IP address access filter right now, the API might be updated to support making other updates. For example, you might be able to add a lifecycle rule, remove a firewall, and update a default retention period in a single request.\n\nSome IDEs (such as PyCharm) may produce warnings about unused classes or methods. This is an artifact of the code generation tooling that allows for the passing of objects in named parameters, but generates a docstring that causes some linting tools to raise a warning.\n\nJavaScript developers can use this SDK to interact with the Object Storage Resource Configuration API. For more information, see the [COS Resource Configuration SDK for Java API Reference](https://ibm.github.io/ibm-cos-sdk-java-config/).\n\nThe SDK is supported on Java versions 1.6 and later.\n\nThe code examples on this tab use the Resource Configuration client library that is provided for Java.\n\nMaven\n\n```xml\n\n com.ibm.cos.config\n ibm-cos-java-config\n\n```\n\nGitHub\n\n

\n https://github.com/IBM/ibm-cos-sdk-java-config\n

\n\nJavaScript developers can use this SDK to interact with the Object Storage Resource Configuration API. For more information, see the [COS Resource Configuration SDK for Java API Reference](https://ibm.github.io/ibm-cos-sdk-java-config/).\n\nThe SDK is supported on Node versions 8.x and later.\n\nThe code examples on this tab use the client library that is provided for Node.js.\n\nInstallation\n\n```bash\nnpm install ibm-cos-sdk-config\n```\n\nGitHub\n\n

\n https://github.com/IBM/ibm-cos-sdk-js-config\n

\n\nPython developers can use this SDK to interact with Object Storage Resource Configuration API. For more information, see the [COS Resource Configuration SDK for Python API Reference](https://ibm.github.io/ibm-cos-sdk-python-config/).\n\nThe code examples on this tab use the client library that is provided for Python.\n\nInstallation\n\n```bash\npip install --upgrade ibm-cos-sdk-config\n```\n\nGitHub\n\n

\n \n https://github.com/IBM/ibm-cos-sdk-python-config\n

\n\nGo developers can use this SDK to interact with Object Storage Resource Configuration API. For more information, see the [COS Resource Configuration SDK for Go API Reference](https://godoc.org/github.com/IBM/ibm-cos-sdk-go-config).\n\nThe SDK supports Go versions 1.12 and above.\n\nThe code examples on this tab use the client library that is provided for Go.\n\n```bash\ngo get -u github.com/IBM/ibm-cos-sdk-go-config\n```\n\nGitHub\n\n

\n https://github.com/IBM/ibm-cos-sdk-go-config\n

\n\n## Endpoint URLs\n\nUnlike the S3-compatible API for reading and writing data, the Configuration API uses a single, global service endpoint. Whether getting or updating metadata, for buckets located in the `eu` geo, `us-south` region, `ams01` zone, or any other storage location, the request uses the same endpoint URL: `https://config.cloud-object-storage.cloud.ibm.com/v1`.\n\nNote that the endpoint URL actually contains three parts: a protocol (`https://`), a host (`config.cloud-object-storage.cloud.ibm.com`), and a version (`v1`). The SDKs will construct this by default, but if sending requests using `curl` or any other REST API utility keep in mind that the endpoint requires both the protocol and version.\n\n## Error handling\n\nThis API uses standard HTTP response codes to indicate whether a method completed successfully. A `200` response indicates success. A `400` type response indicates a failure, and a `500` type response indicates an internal system error.\n\n| Element | Description |\n|----------------------| ------------------------------------------------------------------------------------|\n| `http_status_code` | HTTP status code for the response. Integer. Example: `200` |\n| `code` | Error code. String. Example: `AccessDenied` |\n| `message` | Error message. String. Example: `Access Denied` |\n| `resource` | Target of the failed request. String. Example: `Bucket123` |\n| `ibm_cos_request_id` | Unique identifier for this request. String. Example: `5043294b-de39-4034-881a-92afbed1453d` |\n\nExample error object:\n\n```json\n{\n \"http_status_code\": 403,\n \"code\": \"AccessDenied\",\n \"message\": \"Access Denied\",\n \"resource\": \"my-new-bucket\",\n \"ibm_cos_request_id\": \"9f39ff2e-55d1-461b-a6f1-2d0b75138861\"\n}\n```\n## Authentication\n\nTo work with the API, authenticate your app or service by including your IBM Cloud IAM access token.\n\nTo retrieve an access token:\n\n```bash\ncurl -X POST https://iam.cloud.ibm.com/identity/token \\\n -H \"content-type: application/x-www-form-urlencoded\" \\\n -H \"accept: application/json\" \\\n -d \"grant_type=urn%3Aibm%3Aparams%3Aoauth%3Agrant-type%3Aapikey&apikey=\"\n```\n\nReplace `` with your [service credentials](https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-iam-overview). Then use the full `IAM token` value, prefixed by the _Bearer_ token type, to authenticate your API requests.\n\nTo retrieve an access token:\n\n```bash\nTo be added\n```\n\nReplace `` with your [service credentials](https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-iam-overview). Then use the full `IAM token` value, prefixed by the _Bearer_ token type, to authenticate your API requests.\n\nTo create a client that will automatically handle token management:\n\n```javascript\nconst COS = require('ibm-cos-sdk-config/resource-configuration/v1')\nconst IAMAUTHENTICATOR = require('ibm-cos-sdk-config/auth');\n\nclientInfo = new IamAuthenticator({\n apikey: 'apikey',\n})\n\nconst client = new COS(clientInfo);\n```\n\nReplace `apikey` with an [API key](https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-iam-overview).\n\nNow `client` is ready to make requests.\n\nTo create a client that will automatically handle token management:\n\n```python\nfrom ibm_cos_sdk_config.resource_configuration_v1 import ResourceConfigurationV1\nfrom ibm_cloud_sdk_core.authenticators import IAMAuthenticator\n\nauthenticator = IAMAuthenticator(\n apikey = 'apikey'\n)\n\nclient = ResourceConfigurationV1(authenticator=api_key)\n```\n\nReplace `api_key` with a valid [API key](https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-iam-overview).\n\nNow `client` is ready to make requests.\n\nTo retrieve an access token:\n\n```bash\nTo be added\n```\n\nReplace `` with your [service credentials](https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-iam-overview). Then use the full `IAM token` value, prefixed by the _Bearer_ token type, to authenticate your API requests.\n\n## Additional headers\n\n| Request Parameter | Description |\n|-------------------|----------------------------------------------------------------------------|\n| `authorization` | **Required** IBM Cloud IAM bearer token. String. |\n| `content-type` | The content type of the request body. String. Example: `application/json`. |\n\n| Response Parameter | Description |\n|--------------------------|--------------------------------------------------------------------------------------------------------------------|\n| `Date` | Timestamp of the response. String. Example: `Sun, 13 Jan 2019 18:00:56 GMT` |\n| `Content-Type` | All responses are of type `application/json`. Only returned if there is a response body (such as `GET`). String. |\n| `Content-Length` | Length in bytes of the response body. Integer. Only returned if there is a response body (such as `GET`). Example: `255` |\n| `ETag` | Entity tag (per RFC 7232) of the current state of configuration. String. Example: `\"3ee236f6-0f8e-4171-8cec-050e4c87be48\"` |\n| `ibm-cos-config-api-ver` | The version of this API. String. Example: `1.0` |\n| `ibm-cos-request-id` | Unique identifier for this request. String. Example: `5043294b-de39-4034-881a-92afbed1453d` |", "version": "1.0.0", "x-alternate-name": "ResourceConfiguration", "x-codegen-config": { "java": { "apiPackage": "com.ibm.cloud.objectstorage.config" }, "go": { "apiPackage": "github.com/IBM/ibm-cos-sdk-go-config" } }, "x-sdk-supported-languages": [ "curl", "python", "node", "java", "go" ], "x-github": "https://github.ibm.com/cloud-api-docs/cos", "x-github-issues": "https://github.ibm.com/cloud-api-docs/cos/issues/new", "x-last-updated": "2025-05-28" }, "security": [ { "IAM": [] } ], "tags": [ { "name": "Backup Policy", "description": "New operations on the RC API for managing backup policies." }, { "name": "Backup Vault", "description": "Operations for creating and managing BackupVaults" }, { "name": "Recovery Ranges", "description": "Operations on the BackupVault for managing RecoveryRanges" }, { "name": "Restore", "description": "Operations on the BackupVault for triggering Restore operations" }, { "name": "buckets", "description": "Operations for configuring a bucket (not including)" } ], "servers": [ { "url": "https://config.cloud-object-storage.cloud.ibm.com/v1", "description": "Public RC API endpoint" }, { "url": "https://config.private.cloud-object-storage.cloud.ibm.com/v1", "description": "Private RC API endpoint" }, { "url": "https://config.direct.cloud-object-storage.cloud.ibm.com/v1", "description": "Direct RC API endpoint" } ], "paths": { "/b/{bucket}": { "parameters": [ { "description": "Name of a bucket.", "in": "path", "name": "bucket", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Returns metadata for the specified bucket", "description": "Returns metadata for the specified bucket.", "operationId": "getBucketConfig", "x-ibm-permissions": { "description": "Allows reading of bucket metadata.", "actions": [ { "name": "cloud-object-storage.bucket.list_bucket_crn" }, { "name": "cloud-object-storage.bucket.get_firewall" }, { "name": "cloud-object-storage.bucket.get_activity_tracking" }, { "name": "cloud-object-storage.bucket.get_metrics_monitoring" }, { "name": "cloud-object-storage.bucket.get_protection_management" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Fetch a bucket's metadata", "example": [ { "type": "code", "lang": "curl", "source": [ "curl https://config.cloud-object-storage.cloud.ibm.com/v1/b/my-bucket \\\n -H 'authorization: bearer $IAM_TOKEN'" ] } ] } ], "java": [ { "name": "Fetch a bucket's metadata", "example": [ { "type": "code", "lang": "java", "source": [ "import com.ibm.cloud.objectstorage.config.resource_configuration.v1.ResourceConfiguration;\nimport com.ibm.cloud.objectstorage.config.resource_configuration.v1.model.BucketPatch;\nimport com.ibm.cloud.sdk.core.security.IamAuthenticator;\n\npublic class GetMetadata {\n\n private static final String BUCKET_NAME = ;\n private static final String API_KEY = ;\n public static void main(String[] args) {\n IamAuthenticator authenticator = new IamAuthenticator.Builder()\n .apiKey(API_KEY)\n .build();\n ResourceConfiguration RC_CLIENT = new ResourceConfiguration(\"resource-configuration\", authenticator);\n GetBucketConfigOptions bucketOptions = new GetBucketConfigOptions.Builder(BUCKET_NAME).build();\n\n Bucket bucket = RC_CLIENT.getBucketConfig(bucketOptions).execute().getResult();\n ActivityTracking activityTrackingResponse = bucket.getActivityTracking();\n MetricsMonitoring metricsMonitoringResponse = bucket.getMetricsMonitoring();\n Firewall firewallResponse = bucket.getFirewall();\n ProtectionManagementResponse protectionManagementResponse = bucket.getProtectionManagement();\n }\n}" ] } ] } ], "python": [ { "name": "Fetch a bucket's metadata", "example": [ { "type": "code", "lang": "python", "source": [ "from ibm_cos_sdk_config.resource_configuration_v1 import ResourceConfigurationV1\nfrom ibm_cloud_sdk_core.authenticators import IAMAuthenticator\n\napi_key = ''\nbucket_name = ''\n\nauthenticator = IAMAuthenticator(\n apikey=api_key\n)\nrc_client = ResourceConfigurationV1(authenticator=authenticator)\nconfig = rc_client.get_bucket_config(bucket_name)\nprint(config)" ] } ] } ], "node": [ { "name": "Fetch a bucket's metadata", "example": [ { "type": "code", "lang": "node", "source": [ "const ResourceConfigurationV1 = require('ibm-cos-sdk-config/resource-configuration/v1');\nconst { IamAuthenticator } = require('ibm-cos-sdk-config/auth');\n\n// Replace with your API key and bucket name\nconst apiKey = 'api-key';\nconst bucketName = 'bucket-name';\n\nconst authenticator = new IamAuthenticator({\n apikey: apiKey\n});\n\nconst rcConfig = { authenticator: authenticator };\nconst client = new ResourceConfigurationV1(rcConfig);\nfunction getBucketMetadata() {\n console.log('Getting bucket metadata...');\n const params = { bucket: bucketName };\n client.getBucketConfig(params)\n .then(response => {\n console.log('Bucket Metadata:', response.result);\n })\n .catch(err => {\n console.error('Error retrieving bucket metadata:', err);\n });\n }\ngetBucketMetadata()" ] } ] } ], "go": [ { "name": "Fetch a bucket's metadata", "example": [ { "type": "code", "lang": "go", "source": [ "import (\n fmt\n \"github.com/IBM/go-sdk-core/core\"\n rc \"github.com/IBM/ibm-cos-sdk-go-config/v2/resourceconfigurationv1\"\n)\n\nconst (\n apiKey = ''\n bucketName = ''\n)\n\nauthenticator := &core.IamAuthenticator{\n ApiKey: apiKey,\n}\nservice, _ := rc.NewResourceConfigurationV1(&rc.ResourceConfigurationV1Options{\n Authenticator: authenticator,\n})\ngetBucketConfigOptions := &rc.GetBucketConfigOptions{\n Bucket: core.StringPtr(bucketName),\n}\nresult, response, _ := service.GetBucketConfig(getBucketConfigOptions)\nfmt.Println(result)\nfmt.Println(response)" ] } ] } ] } }, "responses": { "200": { "description": "Success", "headers": { "Etag": { "description": "Unique identifier for the bucket configuration.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bucket" }, "example": { "name": "my-new-bucket", "crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/ 3bf0d9003abfb5d29761c3e97696b71c:xxxxxxx-6c4f-4a62-a165-696756d63903:bucket:my-new-bucket", "service_instance_id": "xxxxxxx-6c4f-4a62-a165-696756d63903", "service_instance_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/3bf0d9003abfb5d29761c3e97696b71c:xxxxxxx-6c4f-4a62-a165-696756d63903::", "time_created": "2018-03-26T16:23:36.980Z", "time_updated": "2018-10-17T19:29:10.117Z", "object_count": 764265234, "bytes_used": 28198745752445144 } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "http_status_code": 400, "code": "InvalidRequest", "message": "The request contains invalid elements.", "resource": "my-new-bucket", "ibm_cos_request_id": "9f39ff2e-55d1-461b-a6f1-2d0b75138861" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "Unauthorized", "message": "The token provided is not valid.", "resource": "my-new-bucket", "ibm_cos_request_id": "9f39ff2e-55d1-461b-a6f1-2d0b75138861", "http_status_code": 401 } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "AccessDenied", "message": "Access Denied", "resource": "my-new-bucket", "ibm_cos_request_id": "9f39ff2e-55d1-461b-a6f1-2d0b75138861", "http_status_code": 403 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "NoSuchBucket", "message": "The specified bucket does not exist.", "resource": "my-new-bucket", "ibm_cos_request_id": "9f39ff2e-55d1-461b-a6f1-2d0b75138861", "http_status_code": 404 } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "InternalError", "message": "Internal server error.", "resource": "my-new-bucket", "ibm_cos_request_id": "9f39ff2e-55d1-461b-a6f1-2d0b75138861", "http_status_code": 500 } } } } }, "tags": [ "buckets" ] }, "patch": { "summary": "Make changes to a bucket's configuration", "description": "Updates a bucket using [JSON Merge Patch](https://tools.ietf.org/html/rfc7396). This request is used to add functionality (like an IP access filter) or to update existing parameters. **Primitives are overwritten and replaced in their entirety. It is not possible to append a new (or to delete a specific) value to an array.** Arrays can be cleared by updating the parameter with an empty array `[]`. A `PATCH` operation only updates specified mutable fields. Please don't use `PATCH` trying to update the number of objects in a bucket, any timestamps, or other non-mutable fields.", "operationId": "updateBucketConfig", "parameters": [ { "description": "An Etag previously returned in a header when fetching or updating a bucket's metadata. If this value does not match the active Etag, the request will fail.", "in": "header", "name": "If-Match", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/merge-patch+json": { "schema": { "$ref": "#/components/schemas/BucketPatch" }, "examples": { "firewall": { "value": { "firewall": { "allowed_ip": [ "10.142.175.0/22", "10.198.243.79" ] } } }, "activity_tracking": { "value": { "activity_tracking": { "read_object_events": false, "write_object_events": true, "management_events": true } } } } } }, "description": "An object containing new configuration metadata." }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Enable a firewall", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X PATCH https://config.cloud-object-storage.cloud.ibm.com/v1/b/my-bucket \\\n -H 'authorization: bearer $IAM_TOKEN' \\\n -d '{\"firewall\": {\"allowed_ip\": [\"10.142.175.0/22\", \"10.198.243.79\"]}}'" ] } ] }, { "name": "Enable activity tracking", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X PATCH https://config.cloud-object-storage.cloud.ibm.com/v1/b/my-bucket \\\n -H 'authorization: bearer $IAM_TOKEN' \\\n -d '{\"activity_tracking\": { \\\n \"read_data_events\": true, \\\n \"write_data_events\": true, \\\n \"management_events\": true}'" ] } ] }, { "name": "Enable metrics monitoring", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X PATCH https://config.cloud-object-storage.cloud.ibm.com/v1/b/my-bucket \\\n -H 'authorization: bearer $IAM_TOKEN' \\\n -d '{\"metrics_monitoring\": { \\\n \"usage_metrics_enabled\": true}'" ] } ] }, { "name": "Activate protection management", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X PATCH https://config.cloud-object-storage.cloud.ibm.com/v1/b/my-bucket \\\n -H 'authorization: bearer $IAM_TOKEN' \\\n -d '{\"protection_management\": { \\\n \"requested_state\": \"activate\", \\\n \"protection_management_token\": $PM_TOKEN}}'" ] } ] } ], "java": [ { "name": "Enable firewall", "example": [ { "type": "code", "lang": "java", "source": [ "import com.ibm.cloud.objectstorage.config.resource_configuration.v1.ResourceConfiguration;\nimport com.ibm.cloud.objectstorage.config.resource_configuration.v1.model.BucketPatch;\nimport com.ibm.cloud.sdk.core.security.IamAuthenticator;\n\nimport java.util.Arrays;\n\npublic class FirewallExample {\n\n private static final String BUCKET_NAME = ;\n private static final String API_KEY = ;\n private static List IP_ARRAY = new ArrayList();\n IP_ARRAY.add(\"x.x.x.x\");\n IP_ARRAY.add(\"y.y.y.y\");\n\n public static void main(String[] args) {\n IamAuthenticator authenticator = new IamAuthenticator.Builder()\n .apiKey(API_KEY)\n .build();\n\n ResourceConfiguration RC_CLIENT = new ResourceConfiguration(\"resource-configuration\", authenticator);\n Firewall firewallConfig = new Firewall.Builder().allowedIp(IP_ARRAY).build();\n BucketPatch bucketPatch = new BucketPatch.Builder().firewall(firewallConfig).build();\n UpdateBucketConfigOptions update = new UpdateBucketConfigOptions\n .Builder(BUCKET_NAME)\n .bucketPatch(bucketPatch.asPatch())\n .build();\n RC_CLIENT.updateBucketConfig(update).execute();\n GetBucketConfigOptions bucketOptions = new GetBucketConfigOptions.Builder(BUCKET_NAME).build();\n Bucket bucket = RC_CLIENT.getBucketConfig(bucketOptions).execute().getResult();\n Firewall firewallResponse = bucket.getFirewall();\n for(String ip: firewallResponse.allowedIp()){\n System.out.println(ip)\n }\n }\n}" ] } ] }, { "name": "Enable activity tracking", "example": [ { "type": "code", "lang": "java", "source": [ "import com.ibm.cloud.objectstorage.config.resource_configuration.v1.ResourceConfiguration;\nimport com.ibm.cloud.objectstorage.config.resource_configuration.v1.model.BucketPatch;\nimport com.ibm.cloud.sdk.core.security.IamAuthenticator;\n\npublic class ActivityTrackerExample {\n\n private static final String BUCKET_NAME = ;\n private static final String API_KEY = ;\n\n public static void main(String[] args) {\n IamAuthenticator authenticator = new IamAuthenticator.Builder()\n .apiKey(API_KEY)\n .build();\n ResourceConfiguration RC_CLIENT = new ResourceConfiguration(\"resource-configuration\", authenticator);\n ActivityTracking activityTrackingConfig = new ActivityTracking().Builder()\n .readDataEvents(true)\n .writeDataEvents(true)\n .managementEvents(true)\n .build();\n BucketPatch bucketPatch = new BucketPatch.Builder().activityTracking(activityTrackingConfig).build();\n UpdateBucketConfigOptions update = new UpdateBucketConfigOptions\n .Builder(BUCKET_NAME)\n .bucketPatch(bucketPatch.asPatch())\n .build();\n\n RC_CLIENT.updateBucketConfig(update).execute();\n GetBucketConfigOptions bucketOptions = new GetBucketConfigOptions.Builder(BUCKET_NAME).build();\n Bucket bucket = RC_CLIENT.getBucketConfig(bucketOptions).execute().getResult();\n\n ActivityTracking activityTrackingResponse = bucket.getActivityTracking();\n System.out.println(\"Read Data Events : \" + activityTrackingResponse.readDataEvents());\n System.out.println(\"Write Data Events : \" + activityTrackingResponse.writeDataEvents());\n System.out.println(\"Management Events : \" + activityTrackingResponse.managementEvents());\n }\n}" ] } ] }, { "name": "Enable metrics monitoring", "example": [ { "type": "code", "lang": "java", "source": [ "import com.ibm.cloud.objectstorage.config.resource_configuration.v1.ResourceConfiguration;\nimport com.ibm.cloud.objectstorage.config.resource_configuration.v1.model.BucketPatch;\nimport com.ibm.cloud.sdk.core.security.IamAuthenticator;\n\npublic class MetricsMonitoringExample {\n\n private static final String BUCKET_NAME = ;\n private static final String API_KEY = ;\n\n public static void main(String[] args) {\n IamAuthenticator authenticator = new IamAuthenticator.Builder()\n .apiKey(API_KEY)\n .build();\n ResourceConfiguration RC_CLIENT = new ResourceConfiguration(\"resource-configuration\", authenticator);\n MetricsMonitoring metricsMonitoringConfig = new MetricsMonitoring().Builder()\n .requestMetricsEnabled(true)\n .usageMetricsEnabled(true)\n .build();\n BucketPatch bucketPatch = new BucketPatch.Builder().metricsMonitoring(metricsMonitoringConfig).build();\n UpdateBucketConfigOptions update = new UpdateBucketConfigOptions\n .Builder(BUCKET_NAME)\n .bucketPatch(bucketPatch.asPatch())\n .build();\n RC_CLIENT.updateBucketConfig(update).execute();\n\n GetBucketConfigOptions bucketOptions = new GetBucketConfigOptions.Builder(BUCKET_NAME).build();\n Bucket bucket = RC_CLIENT.getBucketConfig(bucketOptions).execute().getResult();\n MetricsMonitoring metricsMonitoringResponse = bucket.getMetricsMonitoring();\n System.out.println(\"Usage Metrics Enabled : \" + metricsMonitoringResponse.usageMetricsEnabled());\n System.out.println(\"Request Metrics Enabled : \" + metricsMonitoringResponse.requestMetricsEnabled());\n }\n}" ] } ] }, { "name": "Enable protection management", "example": [ { "type": "code", "lang": "java", "source": [ "import com.ibm.cloud.objectstorage.config.resource_configuration.v1.ResourceConfiguration;\nimport com.ibm.cloud.objectstorage.config.resource_configuration.v1.model.BucketPatch;\nimport com.ibm.cloud.sdk.core.security.IamAuthenticator;\n\npublic class ProtectionManagementExample {\n\n private static final String BUCKET_NAME = ;\n private static final String API_KEY = ;\n private static final String PM_TOKEN = ;\n\n public static void main(String[] args) {\n IamAuthenticator authenticator = new IamAuthenticator.Builder()\n .apiKey(API_KEY)\n .build();\n ResourceConfiguration RC_CLIENT = new ResourceConfiguration(\"resource-configuration\", authenticator);\n ProtectionManagement protectionManagementConfig = new ProtectionManagement.Builder()\n .requestedState(\"activate\")\n .protectionManagementToken(PM_TOKEN)\n .build();\n BucketPatch bucketPatch = new BucketPatch.Builder().protectionManagement(protectionManagementConfig).build();\n UpdateBucketConfigOptions update = new UpdateBucketConfigOptions\n .Builder(BUCKET_NAME)\n .bucketPatch(bucketPatch.asPatch())\n .build();\n RC_CLIENT.updateBucketConfig(update).execute();\n\n GetBucketConfigOptions bucketOptions = new GetBucketConfigOptions.Builder(BUCKET_NAME).build();\n Bucket bucket = RC_CLIENT.getBucketConfig(bucketOptions).execute().getResult();\n ProtectionManagementResponse protectionManagementResponse = bucket.getProtectionManagement();\n List ProtectionManagementResponseTokenEntries = protectionManagementResponse.tokenEntries();\n System.out.println(\"Token Applied Counter: \" + protectionManagementResponse.tokenAppliedCounter());\n for(ProtectionManagementResponseTokenEntry tokenEntry: ProtectionManagementResponseTokenEntries) {\n System.out.println(\"Token Reference Id: \" + tokenEntry.getTokenReferenceId());\n }\n }\n}" ] } ] } ], "python": [ { "name": "Enable a firewall", "example": [ { "type": "code", "lang": "python", "source": [ "from ibm_cos_sdk_config.resource_configuration_v1 import ResourceConfigurationV1\nfrom ibm_cloud_sdk_core.authenticators import IAMAuthenticator\n\napi_key = \"\"\nbucket_name = \"\"\nip_array = [\"x.x.x.x\", \"y.y.y.y\"]\n\nauthenticator = IAMAuthenticator(apikey=api_key)\nclient = ResourceConfigurationV1(authenticator=authenticator)\nfirewall_config = {'firewall': {\"allowed_ip\": ip_array}}\nclient.update_bucket_config(bucket_name, bucket_patch=firewall_config)" ] } ] }, { "name": "Enable activity tracking", "example": [ { "type": "code", "lang": "python", "source": [ "from ibm_cos_sdk_config.resource_configuration_v1 import ResourceConfigurationV1\nfrom ibm_cloud_sdk_core.authenticators import IAMAuthenticator\n\napi_key = \"\"\nbucket_name = \"\"\n\nauthenticator = IAMAuthenticator(apikey=api_key)\nclient = ResourceConfigurationV1(authenticator=authenticator)\nactivity_tracking_config = {'activity_tracking':{'read_data_events':True, 'write_data_events':True, 'management_events':True}}\nclient.update_bucket_config(bucket_name, bucket_patch=activity_tracking_config)" ] } ] }, { "name": "Enable metrics monitoring", "example": [ { "type": "code", "lang": "python", "source": [ "from ibm_cos_sdk_config.resource_configuration_v1 import ResourceConfigurationV1\nfrom ibm_cloud_sdk_core.authenticators import IAMAuthenticator\n\napi_key = \"\"\nbucket_name = \"\"\n\nauthenticator = IAMAuthenticator(apikey=api_key)\nclient = ResourceConfigurationV1(authenticator=authenticator)\nmetrics_monitoring_config = {'metrics_monitoring': {'request_metrics_enabled':True, 'usage_metrics_enabled':True}}\nclient.update_bucket_config(bucket_name, bucket_patch=metrics_monitoring_config)" ] } ] }, { "name": "Enable protection management", "example": [ { "type": "code", "lang": "python", "source": [ "from ibm_cos_sdk_config.resource_configuration_v1 import ResourceConfigurationV1\nfrom ibm_cloud_sdk_core.authenticators import IAMAuthenticator\n\napi_key = \"\"\nbucket_name = \"\"\npm_token = \"\"\n\nauthenticator = IAMAuthenticator(apikey=api_key)\nclient = ResourceConfigurationV1(authenticator=authenticator)\nprotection_management_config = {'protection_management': {'requested_state': 'activate', 'protection_management_token': pm_token}}\nclient.update_bucket_config(bucket_name, bucket_patch=protection_management_config)" ] } ] } ], "node": [ { "name": "Enable a firewall", "example": [ { "type": "code", "lang": "node", "source": [ "const ResourceConfigurationV1 = require('ibm-cos-sdk-config/resource-configuration/v1');\nIamAuthenticator = require('ibm-cos-sdk-config/auth');\n\nvar apiKey = \"\"\nvar bucketName = \"\"\nvar allowedIP = [\"56.131.110.60\"]\n\nauthenticator = new IamAuthenticator({apikey: apiKey})\nrcConfig = {authenticator: authenticator}\nconst client = new ResourceConfigurationV1(rcConfig);\n\nfunction addFirewall() {\n console.log('Updating bucket metadata...');\n\n var params = {\n bucket: bucketName,\n firewall: {\n allowed_ip: allowedIP\n }\n };\n\n client.updateBucketConfig(params, function (err, response) {\n if (err) {\n console.log(\"ERROR: \" + err);\n } else {\n console.log(response.result);\n }\n });\n}\n\naddFirewall()" ] } ] }, { "name": "Enable activity tracking", "example": [ { "type": "code", "lang": "node", "source": [ "const ResourceConfigurationV1 = require('ibm-cos-sdk-config/resource-configuration/v1');\nIamAuthenticator = require('ibm-cos-sdk-config/auth');\n\nvar apiKey = \"\"\nvar bucketName = \"\"\n\nauthenticator = new IamAuthenticator({apikey: apiKey})\nrcConfig = {authenticator: authenticator}\nconst client = new ResourceConfigurationV1(rcConfig);\n\nfunction addAT() {\n console.log('Updating bucket metadata...');\n\n var params = {\n bucket: bucketName,\n activityTracking: {\n \"read_data_events\": true,\n \"write_data_events\": true,\n \"management_events\": true\n }\n };\n\n client.updateBucketConfig(params, function (err, response) {\n if (err) {\n console.log(\"ERROR: \" + err);\n } else {\n console.log(response.result);\n }\n });\n}\n\naddAT()" ] } ] }, { "name": "Enable metrics monitoring", "example": [ { "type": "code", "lang": "node", "source": [ "const ResourceConfigurationV1 = require('ibm-cos-sdk-config/resource-configuration/v1');\nIamAuthenticator = require('ibm-cos-sdk-config/auth');\n\nvar apiKey = \"\"\nvar bucketName = \"\"\n\nauthenticator = new IamAuthenticator({apikey: apiKey})\nrcConfig = {authenticator: authenticator}\nconst client = new ResourceConfigurationV1(rcConfig);\n\nfunction addMM() {\n console.log('Updating bucket metadata...');\n\n var params = {\n bucket: bucketName,\n metricsMonitoring: {\n \"request_metrics_enabled\": true,\n \"usage_metrics_enabled\": true\n }\n };\n\n client.updateBucketConfig(params, function (err, response) {\n if (err) {\n console.log(\"ERROR: \" + err);\n } else {\n console.log(response.result);\n }\n });\n}\n\naddMM()" ] } ] }, { "name": "Enable protection management", "example": [ { "type": "code", "lang": "node", "source": [ "const ResourceConfigurationV1 = require('ibm-cos-sdk-config/resource-configuration/v1');\nconst { IamAuthenticator } = require('ibm-cos-sdk-config/auth');\n\nvar apiKey = \"\"\nvar bucketName = \"\"\nvar pmToken = \"\"\n\nconst authenticator = new IamAuthenticator({apikey: apiKey})\nconst rcConfig = {authenticator: authenticator}\nconst client = new ResourceConfigurationV1(rcConfig);\n\nfunction addPM() {\n var params = {\n bucket: bucketName,\n protectionManagement: {\n \"requested_state\": \"activate\",\n \"protection_management_token\": pmToken\n }\n };\n\n client.updateBucketConfig(params, function (err, data) {\n if (err) {\n console.log(\"ERROR: \" + err);\n } else {\n console.log(data);\n }\n });\n}\n\naddPM()" ] } ] } ], "go": [ { "name": "Enable a firewall", "example": [ { "type": "code", "lang": "go", "source": [ "import (\n\"github.com/IBM/go-sdk-core/core\"\nrc \"github.com/IBM/ibm-cos-sdk-go-config/v2/resourceconfigurationv1\"\n)\n\napiKey := \"\"\nbucketName := \"\"\n\nauthenticator := new(core.IamAuthenticator)\nauthenticator.ApiKey = apiKey\noptionsRC := new(rc.ResourceConfigurationV1Options)\noptionsRC.Authenticator = authenticator\nrcClient, _ := rc.NewResourceConfigurationV1(optionsRC)\n\npatchNameMap := make(map[string]interface{})\npatchNameMap[\"firewall\"] = &rc.Firewall{\n AllowedIp: []string{\"192.168.1.100\"}\n}\nupdateBucketConfigOptions := &rc.UpdateBucketConfigOptions{\n Bucket: core.StringPtr(bucketName),\n BucketPatch: patchNameMap,\n}\nrcClient.UpdateBucketConfig(updateBucketConfigOptions)" ] } ] }, { "name": "Enable activity tracking", "example": [ { "type": "code", "lang": "go", "source": [ "import (\n\"github.com/IBM/go-sdk-core/core\"\nrc \"github.com/IBM/ibm-cos-sdk-go-config/v2/resourceconfigurationv1\"\n)\n\napiKey := \"\"\nbucketName := \"\"\n\nauthenticator := new(core.IamAuthenticator)\nauthenticator.ApiKey = apiKey\noptionsRC := new(rc.ResourceConfigurationV1Options)\noptionsRC.Authenticator = authenticator\nrcClient, _ := rc.NewResourceConfigurationV1(optionsRC)\n\npatchNameMap := make(map[string]interface{})\npatchNameMap[\"activity_tracking\"] = &rc.ActivityTracking{\n ReadDataEvents: core.BoolPtr(true),\n WriteDataEvents: core.BoolPtr(true),\n ManagementEvents: core.BoolPtr(true)\n}\nupdateBucketConfigOptions := &rc.UpdateBucketConfigOptions{\n Bucket: core.StringPtr(bucketName),\n BucketPatch: patchNameMap,\n}\nrcClient.UpdateBucketConfig(updateBucketConfigOptions)" ] } ] }, { "name": "Enable metrics monitoring", "example": [ { "type": "code", "lang": "go", "source": [ "import (\n\"github.com/IBM/go-sdk-core/core\"\nrc \"github.com/IBM/ibm-cos-sdk-go-config/v2/resourceconfigurationv1\"\n)\n\napiKey := \"\"\nbucketName := \"\"\n\nauthenticator := new(core.IamAuthenticator)\nauthenticator.ApiKey = apiKey\noptionsRC := new(rc.ResourceConfigurationV1Options)\noptionsRC.Authenticator = authenticator\nrcClient, _ := rc.NewResourceConfigurationV1(optionsRC)\n\npatchNameMap := make(map[string]interface{})\npatchNameMap[\"metrics_monitoring\"] = &rc.MetricsMonitoring{\n RequestMetricsEnabled: core.BoolPtr(true),\n UsageMetricsEnabled: core.BoolPtr(true)\n}\nupdateBucketConfigOptions := &rc.UpdateBucketConfigOptions{\n Bucket: core.StringPtr(bucketName),\n BucketPatch: patchNameMap,\n}\nrcClient.UpdateBucketConfig(updateBucketConfigOptions)" ] } ] }, { "name": "Enable protection management", "example": [ { "type": "code", "lang": "go", "source": [ "import (\n\"github.com/IBM/go-sdk-core/core\"\nrc \"github.com/IBM/ibm-cos-sdk-go-config/v2/resourceconfigurationv1\"\n)\n\napiKey := \"\"\nbucketName := \"\"\npmToken := \"\"\n\nauthenticator := new(core.IamAuthenticator)\nauthenticator.ApiKey = apiKey\noptionsRC := new(rc.ResourceConfigurationV1Options)\noptionsRC.Authenticator = authenticator\nrcClient, _ := rc.NewResourceConfigurationV1(optionsRC)\n\npatchNameMap := make(map[string]interface{})\npatchNameMap[\"protection_management\"] = &rc.ProtectionManagement{\n RequestedState: core.StringPtr(\"activate\"),\n ProtectionManagementToken: core.StringPtr(pmToken),\n}\nupdateBucketConfigOptions := &rc.UpdateBucketConfigOptions{\n Bucket: core.StringPtr(bucketName),\n BucketPatch: patchNameMap,\n}\nrcClient.UpdateBucketConfig(updateBucketConfigOptions)" ] } ] } ] } }, "responses": { "200": { "description": "Success", "headers": { "Etag": { "description": "Unique identifier for the bucket configuration.", "schema": { "type": "string" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "InvalidRequest", "message": "The request contains invalid elements.", "resource": "my-new-bucket", "ibm_cos_request_id": "9f39ff2e-55d1-461b-a6f1-2d0b75138861", "http_status_code": 400 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "Unauthorized", "message": "The token provided is not valid.", "resource": "my-new-bucket", "ibm_cos_request_id": "9f39ff2e-55d1-461b-a6f1-2d0b75138861", "http_status_code": 401 } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "AccessDenied", "message": "Access Denied", "resource": "my-new-bucket", "ibm_cos_request_id": "9f39ff2e-55d1-461b-a6f1-2d0b75138861", "http_status_code": 403 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "NoSuchBucket", "message": "The specified bucket does not exist.", "resource": "my-new-bucket", "ibm_cos_request_id": "9f39ff2e-55d1-461b-a6f1-2d0b75138861", "http_status_code": 404 } } } }, "412": { "description": "Precondition Failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "http_status_code": 412, "code": "PreconditionFailed", "message": "At least one of the preconditions specified were not met.", "resource": "my-new-bucket", "ibm_cos_request_id": "9f39ff2e-55d1-461b-a6f1-2d0b75138861" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "http_status_code": 500, "code": "InternalError", "message": "Internal server error.", "resource": "my-new-bucket", "ibm_cos_request_id": "9f39ff2e-55d1-461b-a6f1-2d0b75138861" } } } } }, "tags": [ "buckets" ] } }, "/buckets/{bucket}/backup_policies": { "parameters": [ { "name": "bucket", "in": "path", "description": "Name of the COS Bucket name.", "required": true, "schema": { "$ref": "#/components/schemas/BucketName" } } ], "post": { "operationId": "create_backup_policy", "tags": [ "Backup Policy" ], "parameters": [ { "name": "MD5", "in": "header", "description": "MD5 hash of content. If provided, the hash of the request must match.", "required": false, "schema": { "$ref": "#/components/schemas/MD5" } } ], "summary": "Add a new backup policy to the COS Bucket", "description": "\nAttach a new Backup Policy on a bucket.\n\nThis request results in the creation of a single, new RecoveryRange on the destination BackupVault.\n\nDeletion and re-creation of a BackupPolicy to the same BackupVault destination will generate a new RecoveryRange.\n\nThe following shall be validated. Any failure to validate shall cause a HTTP 400 to be returned.\n\n * the source-bucket must have `cloud-object-storage.backup_vault.sync` permissions on the Backup Vault\n * the source-bucket must have versioning-on\n * the Backup Vault must exist and be able to be contacted by the source-bucket\n * the source-bucket must not have an existing BackupPolicy targeting the Backup Vault\n * the source-bucket must not have a BackupPolicy with the same policy_name\n * the source-bucket must have fewer than 3 total BackupPolicies", "x-ibm-permissions": { "description": "Allows for creation of a bucket backup policy.", "actions": [ { "name": "cloud-object-storage.bucket.post_backup_policy" } ] }, "x-ibm-events": { "events": [ { "name": "cloud-object-storage.bucket-backup-policy.create" } ] }, "requestBody": { "description": "A backup policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupPolicyPrototype" } } }, "required": true }, "responses": { "201": { "description": "Successful operation", "headers": { "Location": { "schema": { "$ref": "#/components/schemas/Location" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupPolicy" }, "example": { "policy_name": "myBackupPolicy", "initial_retention": { "delete_after_days": 10 }, "backup_type": "continuous", "policy_id": "44d3dd41-d616-4d25-911a-9ef7fbf28aef", "policy_status": "pending", "target_backup_vault_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:1a0ec336-f391-4091-a6fb-5e084a4c56f4:backup-vault:backup-vault-name" } } } }, "400": { "description": "Bad Request, or the Backup feature has not been enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "500": { "description": "Internal Service Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "503": { "description": "Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } } } }, "get": { "operationId": "list_backup_policies", "tags": [ "Backup Policy" ], "summary": "List BackupPolicies", "description": "Get all backup policies on a bucket.\n\nThis request generates the \"cloud-object-storage.bucket-backup-policy.list\" ActivityTracking event. ", "x-ibm-permissions": { "description": "Allows for listing of bucket backup policies.", "actions": [ { "name": "cloud-object-storage.bucket.list_backup_policies" } ] }, "x-ibm-events": { "events": [ { "name": "cloud-object-storage.bucket-backup-policy.list" } ] }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupPolicyCollection" }, "example": [ { "policy_name": "myBackupPolicy", "initial_retention": { "delete_after_days": 10 }, "backup_type": "continuous", "policy_id": "44d3dd41-d616-4d25-911a-9ef7fbf28aef", "policy_status": "active", "target_backup_vault_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4e6a740e3866020847e525436:backup-vault:backup-vault-name" } ] } } }, "400": { "description": "Bad Request, or the Backup feature has not been enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "500": { "description": "Internal Service Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "503": { "description": "Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } } } } }, "/buckets/{bucket}/backup_policies/{policy_id}": { "parameters": [ { "name": "bucket", "in": "path", "description": "name of the bucket affected", "required": true, "schema": { "$ref": "#/components/schemas/BucketName" } }, { "name": "policy_id", "in": "path", "description": "uuid of the BackupPolicy", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } } ], "get": { "operationId": "get_backup_policy", "tags": [ "Backup Policy" ], "summary": "Get BackupPolicy", "description": "Read a specific backup policy on a bucket.", "x-ibm-permissions": { "description": "Allows for viewing a bucket backup policy.", "actions": [ { "name": "cloud-object-storage.bucket.get_backup_policy" } ] }, "x-ibm-events": { "events": [ { "name": "cloud-object-storage.bucket-backup-policy.read" } ] }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupPolicy" }, "example": { "policy_name": "myBackupPolicy", "backup_type": "continuous", "policy_id": "44d3dd41-d616-4d25-911a-9ef7fbf28aef", "policy_status": "active", "target_backup_vault_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:1a0ec336-f391-4091-a6fb-5e084a4c56f4:backup-vault:backup-vault-name", "initial_retention": { "delete_after_days": 10 } } } } }, "400": { "description": "Bad Request, or the Backup feature has not been enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "500": { "description": "Internal Service Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "503": { "description": "Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } } } }, "delete": { "operationId": "delete_backup_policy", "tags": [ "Backup Policy" ], "summary": "Delete a BackupPolicy", "description": "Delete a specific BackupPolicy.", "x-ibm-permissions": { "description": "Allows for deleting a bucket backup policy.", "actions": [ { "name": "cloud-object-storage.bucket.delete_backup_policy" } ] }, "x-ibm-events": { "events": [ { "name": "cloud-object-storage.bucket-backup-policy.delete" } ] }, "responses": { "204": { "description": "Successful operation" }, "400": { "description": "Bad Request, or the Backup feature has not been enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "500": { "description": "Internal Service Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "503": { "description": "Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } } } } }, "/backup_vaults": { "parameters": [ { "name": "service_instance_id", "in": "query", "description": "Name of the service_instance to list BackupVaults for.", "required": true, "schema": { "$ref": "#/components/schemas/ServiceInstanceID" } } ], "get": { "operationId": "list_backup_vaults", "parameters": [ { "name": "token", "in": "query", "description": "the continuation token for controlling pagination", "required": false, "schema": { "$ref": "#/components/schemas/Token" } } ], "tags": [ "Backup Vault" ], "summary": "list BackupVaults", "description": "Returns a list of BackupVault CRNs owned by the account.", "x-ibm-permissions": { "description": "Allows for listing all the backup vaults in a service instance.", "actions": [ { "name": "cloud-object-storage.backup_vault.list_account_backup_vaults" } ] }, "x-ibm-events": { "events": [ { "name": "cloud-object-storage.backup-vault.list" } ] }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupVaultCollection" }, "example": { "next": { "token": "SWYwNTZMflFmZUgheGNcNHMuIm9OMTFz", "href": "config.cloud-object-storage.cloud.ibm.com/v1/backup_vaults?token=1znNRhmyheG-pm6mlMKFsoxcKXFnW1hgBb2_6ZReqHduL3rivfeBWHeyL-OaJvtfVZjKrgRVmODtOdVeQEXkKCxDWpA5hRWuv9WgTPR2eLIN9fbEaTxqdNO4dp0sQeHh4HO-13nTgRV_1QGiR1QFzREHX3wzquLn9o_1DZZAEP-vAY2V8d6BCA1z2krhpMfswKJ8r6UynUc0W5JHSH4auwJ6jC-h8sc8NEcQpHUx2Ep4oxebmtJMaycQSjLA3J2fdcYuysKq3YIcszDnPte0zwr25x5_GmBrxlgd2oesjfyTaLHfIg1g4TD0uH9m9aEAv" }, "backup_vaults": [ "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4-e6a7-40e3-8660-20847e525436:backup-vault:otherbackupvault", "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4-e6a7-40e3-8660-20847e525436:backup-vault:backupvault" ] } } } }, "400": { "description": "Bad Request, service_instance_id header param is missing, or the Backup feature has not been enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "500": { "description": "Internal Service Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "503": { "description": "Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } } } }, "post": { "operationId": "create_backup_vault", "tags": [ "Backup Vault" ], "summary": "create a BackupVault", "description": "Creates a BackupVault.\n\nCertain fields will be returned only if the user has specific permissions:\n - `activity_tracking` requires `cloud-object-storage.backup_vault.put_activity_tracking`\n - `metrics_monitoring` requires `cloud-object-storage.backup_vault.put_metrics_monitoring`", "x-ibm-permissions": { "description": "Allows for creating a backup vault in a service instance.", "actions": [ { "name": "cloud-object-storage.backup_vault.post_backup_vault" }, { "name": "cloud-object-storage.backup_vault.put_activity_tracking" }, { "name": "cloud-object-storage.backup_vault.put_metrics_monitoring" } ] }, "x-ibm-events": { "events": [ { "name": "cloud-object-storage.backup-vault.create" } ] }, "requestBody": { "description": "A Backup Vault config object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupVaultPrototype" } } }, "required": true }, "responses": { "201": { "description": "Successful operation", "headers": { "Location": { "schema": { "$ref": "#/components/schemas/Location" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupVault" } } } }, "400": { "description": "Bad Request, or the Backup feature has not been enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "500": { "description": "Internal Service Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "503": { "description": "Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } } } } }, "/backup_vaults/{backup_vault_name}": { "parameters": [ { "name": "backup_vault_name", "in": "path", "description": "Name of the backup-vault to create or update.", "required": true, "schema": { "$ref": "#/components/schemas/BackupVaultName" } } ], "get": { "operationId": "get_backup_vault", "tags": [ "Backup Vault" ], "summary": "get the config for a Backup Vault", "description": "Gets configuration information for a Backup Vault.\n\nCertain fields will be returned only if the user has specific permissions:\n - `activity_tracking` requires `cloud-object-storage.backup_vault.get_activity_tracking`\n - `metrics_monitoring` requires `cloud-object-storage.backup_vault.get_metrics_monitoring`\n - `sse_kp_customer_root_key_crn` requires `cloud-object-storage.backup_vault.get_crk_id`", "x-ibm-permissions": { "description": "Allows for reading backup vault configuration.", "actions": [ { "name": "cloud-object-storage.backup_vault.get_basic" }, { "name": "cloud-object-storage.backup_vault.get_activity_tracking" }, { "name": "cloud-object-storage.backup_vault.get_metrics_monitoring" }, { "name": "cloud-object-storage.backup_vault.get_crk_id" } ] }, "x-ibm-events": { "events": [ { "name": "cloud-object-storage.backup-vault-configuration.read" } ] }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupVault" } } }, "headers": { "ETag": { "schema": { "$ref": "#/components/schemas/MD5" }, "description": "ETag (entity tag) that identifies the newly altered version of the Backup Vault resource" } } }, "400": { "description": "Bad Request, or the Backup feature has not been enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "500": { "description": "Internal Service Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "503": { "description": "Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } } } }, "patch": { "operationId": "update_backup_vault", "tags": [ "Backup Vault" ], "summary": "Update the config on a Backup Vault", "description": "Update the Backup Vault config via JSON Merge Patch update semantics.\n\nIn particular, note that providing an empty object (`{}`) to either field in the request body will\nremove any existing configuration.\n\nRequires that the user have specific permissions depending on what is being changed: \n - `activity_tracking` requires `cloud-object-storage.backup_vault.put_activity_tracking`\n - `metrics_monitoring` requires `cloud-object-storage.backup_vault.put_metrics_monitoring`", "x-ibm-permissions": { "description": "Allows for updating specific backup vault configurations.", "actions": [ { "name": "cloud-object-storage.backup_vault.put_activity_tracking" }, { "name": "cloud-object-storage.backup_vault.put_metrics_monitoring" } ] }, "x-ibm-events": { "events": [ { "name": "cloud-object-storage.backup-vault-configuration.update" } ] }, "requestBody": { "description": "A Backup Vault config object containing changes to apply to the existing Backup Vault config.\n", "content": { "application/merge-patch+json": { "schema": { "$ref": "#/components/schemas/BackupVaultPatch" } } }, "required": true }, "parameters": [ { "name": "If-Match", "in": "header", "schema": { "$ref": "#/components/schemas/MD5" }, "required": false, "description": "Conditionally update the Backup Vault config if and only if the ETag\nof the existing config exactly matches the provided If-Match MD5.\n" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupVault" } } }, "headers": { "ETag": { "schema": { "$ref": "#/components/schemas/MD5" } } } }, "400": { "description": "Bad Request, or the Backup feature has not been enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "500": { "description": "Internal Service Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "503": { "description": "Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } } } }, "delete": { "operationId": "delete_backup_vault", "tags": [ "Backup Vault" ], "summary": "Delete an empty Backup Vault", "description": "Delete the Backup Vault.\n\nRequires that the BackupVault not contain any RecoveryRanges. ", "x-ibm-permissions": { "description": "Allows for deleting a backup vault.", "actions": [ { "name": "cloud-object-storage.backup_vault.delete_backup_vault" } ] }, "x-ibm-events": { "events": [ { "name": "cloud-object-storage.backup-vault.delete" } ] }, "responses": { "204": { "description": "Successful operation" }, "400": { "description": "Bad Request, or the Backup feature has not been enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "500": { "description": "Internal Service Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "503": { "description": "Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } } } } }, "/backup_vaults/{backup_vault_name}/recovery_ranges": { "parameters": [ { "name": "backup_vault_name", "in": "path", "description": "name of BackupVault", "required": true, "schema": { "$ref": "#/components/schemas/BackupVaultName" } }, { "name": "source_resource_crn", "in": "query", "description": "CRN of source resource to filter on. This limits ranges returned to only ranges where the source_resource_crn matches the parameter value.", "required": false, "schema": { "$ref": "#/components/schemas/BucketCRN" } }, { "name": "latest", "in": "query", "schema": { "$ref": "#/components/schemas/Latest" }, "description": "If \"true\", then return only the latest RecoveryRange for each source-resource that is backed up. \n\nIf \"false\" or not specified, then the default behavior is produced. \n\nValue is can insensative. If any value is provided other than \"true\" or \"false\" then return 400. " } ], "get": { "operationId": "list_recovery_ranges", "tags": [ "Recovery Ranges" ], "parameters": [ { "name": "token", "in": "query", "description": "the continuation token for controlling pagination.", "required": false, "schema": { "$ref": "#/components/schemas/Token" } } ], "summary": "List RecoveryRanges on a backup vault", "description": "List RecoveryRanges on a backup vault. Lists all available ranges for\nall source resources by default. The `?source_resource_crn` query parameter will\nlimit the list to only ranges for the specified resource.", "x-ibm-permissions": { "description": "Allows for listing the recovery ranges in a backup vault.", "actions": [ { "name": "cloud-object-storage.backup_vault.list_recovery_ranges" } ] }, "x-ibm-events": { "events": [ { "name": "cloud-object-storage.backup-recovery-range.list" } ] }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryRangeCollection" }, "example": { "next": { "token": "SWYwNTZMflFmZUgheGNcNHMuIm9OMTFz", "href": "config.cloud-object-storage.cloud.ibm.com/v1/backup_vaults/mybackupvault/recovery_ranges?token=1znNRhmyheG-pm6mlMKFsoxcKXFnW1hgBb2_6ZReqHduL3rivfeBWHeyL-OaJvtfVZjKrgRVmODtOdVeQEXkKCxDWpA5hRWuv9WgTPR2eLIN9fbEaTxqdNO4dp0sQeHh4HO-13nTgRV_1QGiR1QFzREHX3wzquLn9o_1DZZAEP-vAY2V8d6BCA1z2krhpMfswKJ8r6UynUc0W5JHSH4auwJ6jC-h8sc8NEcQpHUx2Ep4oxebmtJMaycQSjLA3J2fdcYuysKq3YIcszDnPte0zwr25x5_GmBrxlgd2oesjfyTaLHfIg1g4TD0uH9m9aEAv" }, "recovery_ranges": [ { "recovery_range_id": "44d3dd41-d616-4d25-911a-9ef7fbf28aef", "source_resource_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4e6a740e3866020847e525436:bucket:sourcebucket", "backup_policy_name": "myBackupPolicy", "range_start_time": "2024-06-02T12:00:00.000Z", "range_end_time": "2024-06-03T12:00:00.000Z", "range_create_time": "2024-06-02T12:00:00.000Z", "retention": { "delete_after_days": 100 } }, { "recovery_range_id": "6ff0d31c-7583-4463-8ae5-208752f5769c", "source_resource_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4e6a740e3866020847e525436:bucket:sourcebucket", "backup_policy_name": "myBackupPolicy", "range_start_time": "2024-06-04T12:00:00.000Z", "range_end_time": "2024-06-05T12:00:00.000Z", "range_create_time": "2024-06-04T12:00:00.000Z", "retention": { "delete_after_days": 100 } } ] } } } }, "400": { "description": "Bad Request, or the Backup feature has not been enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "500": { "description": "Internal Service Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "503": { "description": "Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } } } } }, "/backup_vaults/{backup_vault_name}/recovery_ranges/{recovery_range_id}": { "parameters": [ { "name": "backup_vault_name", "in": "path", "description": "name of BackupVault to update", "required": true, "schema": { "$ref": "#/components/schemas/BackupVaultName" } }, { "name": "recovery_range_id", "in": "path", "description": "ID of the RecoveryRange to update", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } } ], "get": { "operationId": "get_source_resource_recovery_range", "tags": [ "Recovery Ranges" ], "summary": "get RecoveryRange info", "description": "Get info for a specific RecoveryRange. ", "x-ibm-permissions": { "description": "Allows for viewing a recovery range a backup vault.", "actions": [ { "name": "cloud-object-storage.backup_vault.get_recovery_range" } ] }, "x-ibm-events": { "events": [ { "name": "cloud-object-storage.backup-recovery-range.read" } ] }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryRange" }, "example": { "recovery_range_id": "6ff0d31c-7583-4463-8ae5-208752f5769c", "source_resource_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4e6a740e3866020847e525436:bucket:sourcebucket", "backup_policy_name": "myBackupPolicy", "range_start_time": "2024-06-04T12:00:00.000Z", "range_end_time": "2024-06-05T12:00:00.000Z", "range_create_time": "2024-06-04T12:00:00.000Z", "retention": { "delete_after_days": 100 } } } } }, "400": { "description": "Bad Request, or the Backup feature has not been enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "500": { "description": "Internal Service Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "503": { "description": "Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } } } }, "patch": { "operationId": "update_source_resource_recovery_range", "tags": [ "Recovery Ranges" ], "summary": "patch RecoveryRange info", "description": "Update a RecoveryRange via JSON-merge-patch semantics.\n\nThis request only supports increasing the `retention.delete_after_days` value. ", "x-ibm-permissions": { "description": "Allows for updating a recovery range on a backup vault.", "actions": [ { "name": "cloud-object-storage.backup_vault.put_retention" } ] }, "x-ibm-events": { "events": [ { "name": "cloud-object-storage.backup-recovery-range.update" } ] }, "requestBody": { "description": "The RecoveryRange configuration elements that are to be changed. \n", "content": { "application/merge-patch+json": { "schema": { "$ref": "#/components/schemas/RecoveryRangePatch" } } }, "required": true }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryRange" }, "example": { "retention": { "delete_after_days": 200 } } } } }, "400": { "description": "Bad Request, or the Backup feature has not been enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "500": { "description": "Internal Service Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "503": { "description": "Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } } } } }, "/backup_vaults/{backup_vault_name}/restores": { "parameters": [ { "name": "backup_vault_name", "in": "path", "description": "name of BackupVault to restore from", "required": true, "schema": { "$ref": "#/components/schemas/BackupVaultName" } } ], "post": { "operationId": "create_restore", "tags": [ "Restore" ], "summary": "Initiate a Restore", "description": "Initiates a restore operation against some RecoveryRange to some destination bucket.\n\nThe following shall be validated. Any failure to validate shall cause a HTTP 400 to be returned.\n\n * The specified RecoveryRange must exist\n * The restore time must be within the RecoveryRange\n * the target-bucket must exist and be able to be contacted by the Backup Vault\n * target-bucket must have versioning-on\n * the Backup Vault must have `cloud-object-storage.bucket.restore_sync` permissions on the target-bucket", "x-ibm-permissions": { "description": "Allows for triggering a restore on a backup vault.", "actions": [ { "name": "cloud-object-storage.backup-vault.post_restore" } ] }, "x-ibm-events": { "events": [ { "name": "cloud-object-storage.backup-restore.create" } ] }, "requestBody": { "description": "A restore config", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestorePrototype" }, "example": { "recovery_range_id": "6ff0d31c-7583-4463-8ae5-208752f5769c", "restore_point_in_time": "2024-06-04T12:12:00.000Z", "restore_type": "in_place", "target_resource_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4e6a740e3866020847e525436:bucket:targetbucket" } } }, "required": true }, "responses": { "201": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Restore" }, "example": { "recovery_range_id": "6ff0d31c-7583-4463-8ae5-208752f5769c", "source_resource_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4e6a740e3866020847e525436:bucket:sourcebucket", "restore_point_in_time": "2024-06-04T12:12:00.000Z", "restore_type": "in_place", "target_resource_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4e6a740e3866020847e525436:bucket:targetbucket", "restore_id": "b0bcb32b-0fa9-423c-b10b-9d4328e5fc63", "restore_status": "initializing", "init_time": "2024-06-10T12:12:00.000Z" } } }, "headers": { "Location": { "schema": { "$ref": "#/components/schemas/Location" }, "description": "the location at which the new policy can be found" } } }, "400": { "description": "Bad Request, or the Backup feature has not been enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "500": { "description": "Internal Service Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "503": { "description": "Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } } } }, "get": { "operationId": "list_restores", "tags": [ "Restore" ], "summary": "List Restores", "description": "List all current and complete restores. ", "x-ibm-permissions": { "description": "Allows for listing restores on a backup vault.", "actions": [ { "name": "cloud-object-storage.backup_vault.list_restores" } ] }, "x-ibm-events": { "events": [ { "name": "cloud-object-storage.backup-restore.list" } ] }, "parameters": [ { "name": "token", "in": "query", "description": "the continuation token for controlling pagination.", "required": false, "schema": { "$ref": "#/components/schemas/Token" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestoreCollection" }, "example": { "next": { "token": "SWYwNTZMflFmZUgheGNcNHMuIm9OMTFz", "href": "config.cloud-object-storage.cloud.ibm.com/v1/backup_vaults/mybackupvault/restores?Token=SWYwNTZMflFmZUgheGNcNHMuIm9OMTFz" }, "restores": [ { "restore_id": "b0bcb32b-0fa9-423c-b10b-9d4328e5fc63", "recovery_range_id": "6ff0d31c-7583-4463-8ae5-208752f5769c", "source_resource_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4e6a740e3866020847e525436:bucket:sourcebucket", "restore_point_in_time": "2024-06-04T12:12:00.000Z", "restore_type": "in_place", "target_resource_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4e6a740e3866020847e525436:bucket:targetbucket", "restore_status": "running", "restore_percent_progress": 50, "init_time": "2024-06-10T12:12:00.000Z" }, { "restore_id": "3deefef0-3ed7-492c-8828-00fb33e64f88", "recovery_range_id": "6ff0d31c-7583-4463-8ae5-208752f5769c", "source_resource_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4e6a740e3866020847e525436:bucket:sourcebucket", "restore_point_in_time": "2024-06-04T12:12:00.000Z", "restore_type": "in_place", "target_resource_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4e6a740e3866020847e525436:bucket:othertargetbucket", "restore_status": "initializing", "init_time": "2024-06-10T12:24:00.000Z" } ] } } } }, "400": { "description": "Bad Request, or the Backup feature has not been enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "500": { "description": "Internal Service Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "503": { "description": "Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } } } } }, "/backup_vaults/{backup_vault_name}/restores/{restore_id}": { "parameters": [ { "name": "backup_vault_name", "in": "path", "description": "name of BackupVault that the restore occured on", "required": true, "schema": { "$ref": "#/components/schemas/BackupVaultName" } }, { "name": "restore_id", "in": "path", "description": "id of the restore to introspect on", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } } ], "get": { "operationId": "get_restore", "tags": [ "Restore" ], "summary": "Get Restore", "description": "Introspect on a specific restore.", "x-ibm-permissions": { "description": "Allows for viewing a restore on a backup vault.", "actions": [ { "name": "cloud-object-storage.backup_vault.get_restore" } ] }, "x-ibm-events": { "events": [ { "name": "cloud-object-storage.backup-restore.read" } ] }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Restore" }, "example": { "restore_id": "b0bcb32b-0fa9-423c-b10b-9d4328e5fc63", "recovery_range_id": "6ff0d31c-7583-4463-8ae5-208752f5769c", "source_resource_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4e6a740e3866020847e525436:bucket:sourcebucket", "restore_point_in_time": "2024-06-04T12:12:00.000Z", "restore_type": "in_place", "target_resource_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4e6a740e3866020847e525436:bucket:targetbucket", "restore_status": "running", "restore_percent_progress": 50, "init_time": "2024-06-10T12:12:00.000Z" } } } }, "400": { "description": "Bad Request, or the Backup feature has not been enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "500": { "description": "Internal Service Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } }, "503": { "description": "Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } } } } } } }, "components": { "securitySchemes": { "IAM": { "type": "apiKey", "name": "Authorization", "in": "header" } }, "schemas": { "ActivityTracking": { "description": "Enables sending log data to IBM Cloud Activity Tracker Event Routing to provide visibility into bucket management, object read and write events. (Recommended) When the `activity_tracker_crn` is not populated, then enabled events are sent to the Activity Tracker Event Routing instance at the container's location unless otherwise specified in the Activity Tracker Event Routing Event Routing service configuration. (Legacy) When the `activity_tracker_crn` is populated, then enabled events are sent to the Activity Tracker Event Routing instance specified.", "properties": { "read_data_events": { "description": "If set to `true`, all object read events (i.e. downloads) will be sent to Activity Tracker Event Routing.", "type": "boolean", "default": false }, "write_data_events": { "description": "If set to `true`, all object write events (i.e. uploads) will be sent to Activity Tracker Event Routing.", "type": "boolean", "default": false }, "activity_tracker_crn": { "description": "When the `activity_tracker_crn` is not populated, then enabled events are sent to the Activity Tracker Event Routing instance associated to the container's location unless otherwise specified in the Activity Tracker Event Routing Event Routing service configuration. If `activity_tracker_crn` is populated, then enabled events are sent to the Activity Tracker Event Routing instance specified and bucket management events are always enabled.", "type": "string" }, "management_events": { "description": "This field only applies if `activity_tracker_crn` is not populated. If set to `true`, all bucket management events will be sent to Activity Tracker Event Routing.", "type": "boolean", "default": false } }, "example": { "activity_tracking": { "read_data_events": false, "write_data_events": true, "management_events": true } }, "type": "object" }, "Bucket": { "description": "A bucket.", "properties": { "name": { "description": "The name of the bucket. Non-mutable.", "type": "string", "example": "my-new-bucket" }, "crn": { "description": "The service instance that holds the bucket. Non-mutable.", "type": "string", "example": "crn:v1:bluemix:public:cloud-object-storage:global:a/3bf0d9003abfb5d29761c3e97696b71c:xxxxxxx-6c4f-4a62-a165-696756d63903:bucket:my-new-bucket" }, "service_instance_id": { "description": "The service instance that holds the bucket. Non-mutable.", "type": "string", "example": "d6f04d83-6c4f-4a62-a165-696756d63903" }, "service_instance_crn": { "description": "The service instance that holds the bucket. Non-mutable.", "type": "string", "example": "crn:v1:bluemix:public:cloud-object-storage:global:a/3bf0d9003abfb5d29761c3e97696b71c:xxxxxxx-6c4f-4a62-a165-696756d63903::" }, "time_created": { "description": "The creation time of the bucket in RFC 3339 format. Non-mutable.", "format": "date-time", "type": "string", "example": "2018-03-26T16:23:36.980Z" }, "time_updated": { "description": "The modification time of the bucket in RFC 3339 format. Non-mutable.", "format": "date-time", "type": "string", "example": "2018-10-17T19:29:10.117Z" }, "object_count": { "description": "Total number of objects in the bucket. Non-mutable.", "type": "integer", "format": "int64", "example": 764265234 }, "bytes_used": { "description": "Total size of all objects in the bucket. Non-mutable.", "type": "integer", "format": "int64", "example": 28198745752445144 }, "noncurrent_object_count": { "description": "Number of non-current object versions in the bucket. Non-mutable.", "type": "integer", "format": "int64", "example": 764265234 }, "noncurrent_bytes_used": { "description": "Total size of all non-current object versions in the bucket. Non-mutable.", "type": "integer", "format": "int64", "example": 844239234 }, "delete_marker_count": { "description": "Total number of delete markers in the bucket. Non-mutable.", "type": "integer", "format": "int64", "example": 827201 }, "firewall": { "$ref": "#/components/schemas/Firewall" }, "activity_tracking": { "$ref": "#/components/schemas/ActivityTracking" }, "metrics_monitoring": { "$ref": "#/components/schemas/MetricsMonitoring" }, "hard_quota": { "$ref": "#/components/schemas/HardQuota" }, "protection_management": { "$ref": "#/components/schemas/ProtectionManagementResponse" } }, "type": "object" }, "BucketPatch": { "description": "An object containing new bucket metadata.", "x-java-builder": true, "properties": { "firewall": { "$ref": "#/components/schemas/Firewall" }, "activity_tracking": { "$ref": "#/components/schemas/ActivityTracking" }, "metrics_monitoring": { "$ref": "#/components/schemas/MetricsMonitoring" }, "hard_quota": { "$ref": "#/components/schemas/HardQuota" }, "protection_management": { "$ref": "#/components/schemas/ProtectionManagement" } }, "type": "object" }, "Error": { "type": "object", "description": "A container for error messages.", "properties": { "http_status_code": { "description": "HTTP status code for the response.", "type": "integer" }, "code": { "description": "The category of the error.", "type": "string" }, "message": { "description": "A short description of the error.", "type": "string" }, "resource": { "description": "Target of the failed request.", "type": "string" }, "ibm_cos_request_id": { "description": "The UUID of the failed request.", "type": "string" } }, "required": [ "http_status_code", "code", "message", "resource", "ibm_cos_request_id" ] }, "Firewall": { "description": "An access control mechanism based on the network (IP address) where request originated. Requests not originating from IP addresses listed in the `allowed_ip` field will be denied regardless of any access policies (including public access) that might otherwise permit the request. Viewing or updating the `Firewall` element requires the requester to have the `manager` role.", "properties": { "allowed_ip": { "description": "List of IPv4 or IPv6 addresses in CIDR notation to be affected by firewall in CIDR notation is supported. Passing an empty array will lift the IP address filter. The `allowed_ip` array can contain a maximum of 1000 items.", "type": "array", "items": { "description": "Individual IP address or range of IP addresses. The entire array will be overwritten in a `PATCH` operation.", "type": "string" } }, "denied_ip": { "description": "List of IPv4 or IPv6 addresses in CIDR notation to be affected by firewall in CIDR notation is supported. Passing an empty array will lift the IP address filter. The `denied_ip` array can contain a maximum of 1000 items.", "type": "array", "items": { "description": "Individual IP address or range of IP addresses. The entire array will be overwritten in a `PATCH` operation.", "type": "string" } }, "allowed_network_type": { "description": "Indicates which network types are allowed for bucket access. May contain `public`, `private`, and/or `direct` elements. Setting `allowed_network_type` to only `private` will prevent access to object storage from outside of the IBM Cloud. The entire array will be overwritten in a `PATCH` operation. For more information on network types, [see the documentation](https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-endpoints#advanced-endpoint-types).", "type": "array", "items": { "description": "May contain `public`, `private`, and/or `direct` elements. Setting `allowed_network_type` to only `private` will prevent access to object storage from outside of the IBM Cloud. The entire array will be overwritten in a `PATCH` operation. For more information on network types, [see the documentation](https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-endpoints#advanced-endpoint-types).", "type": "string", "enum": [ "public", "private", "direct" ] } } }, "example": { "firewall": { "allowed_ip": [ "10.13.175.0/22", "10.198.243.79" ], "allowed_network_type": [ "private" ] } }, "type": "object" }, "HardQuota": { "description": "Maximum bytes for this bucket.", "type": "integer", "format": "int64", "example": 28198745752445144 }, "MetricsMonitoring": { "description": "Enables sending metrics to IBM Cloud Monitoring. All metrics are opt-in. (Recommended) When the `metrics_monitoring_crn` is not populated, then enabled metrics are sent to the Monitoring instance at the container's location unless otherwise specified in the Metrics Router service configuration. (Legacy) When the `metrics_monitoring_crn` is populated, then enabled metrics are sent to the Monitoring instance defined in the `metrics_monitoring_crn` field.", "properties": { "usage_metrics_enabled": { "description": "If set to `true`, all usage metrics (i.e. `bytes_used`) will be sent to the monitoring service.", "type": "boolean", "default": false }, "request_metrics_enabled": { "description": "If set to `true`, all request metrics (i.e. `rest.object.head`) will be sent to the monitoring service.", "type": "boolean", "default": false }, "metrics_monitoring_crn": { "description": "When the `metrics_monitoring_crn` is not populated, then enabled metrics are sent to the monitoring instance associated to the container's location unless otherwise specified in the Metrics Router service configuration. If `metrics_monitoring_crn` is populated, then enabled events are sent to the Metrics Monitoring instance specified.", "type": "string" } }, "example": { "metrics_monitoring": { "usage_metrics_enabled": true, "request_metrics_enabled": true } }, "type": "object" }, "ProtectionManagement": { "description": "Data structure holding protection management operations.", "properties": { "requested_state": { "description": "If set to `activate`, protection management action on the bucket is being activated.", "type": "string", "enum": [ "activate", "deactivate" ] }, "protection_management_token": { "description": "This field is required when using requested_state\\:`activate` and holds a JWT that is provided by the Cloud Operator. This should be the encoded JWT.", "type": "string" } }, "example": { "protection_management": { "requested_state": "activate", "protection_management_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJDT1MgT3BlcmF0b3IiLCJleHAiOiIyMDIyLTEwLTEzVDE1OjA0OjQ4LjQ5M1oiLCJqdGkiOjE1MTYyMzkwMjIsImxlZ2FsX2lkIjoiU29tZSBMZWdhbCBJZCIsInN1c3BlbmRfcHJvdGVjdGlvbl91bnRpbF9kYXRlIjoiMjAyMi0xMC0xM1QxNTowNDo0OC40OTNaIiwiY29udGFpbmVyX25hbWUiOiJteS1uZXctYnVja2V0Iiwic3VzcGVuZF9sZWdhbF9ob2xkc19mbGFnIjpmYWxzZX0.zfpOHt-wBt-fSXyJcjtR1KD12jeQN2_8afxND_moc3g" } }, "type": "object" }, "ProtectionManagementResponse": { "description": "Data structure holding protection management response.", "x-java-builder": true, "properties": { "token_applied_counter": { "description": "Indicates the X number of protection management tokens that have been applied to the bucket in its lifetime.", "type": "string" }, "token_entries": { "type": "array", "description": "The 'protection management token list' holding a recent list of applied tokens. This list may contain a subset of all tokens applied to the bucket, as indicated by the counter.", "items": { "$ref": "#/components/schemas/ProtectionManagementResponseTokenEntry" } } }, "type": "object" }, "ProtectionManagementResponseTokenEntry": { "description": "Data structure holding protection management token.", "type": "object" }, "Config": { "description": "Response body.", "properties": { "next": { "$ref": "#/components/schemas/Next" }, "account_id": { "description": "IBM account id from the request", "type": "string", "example": "7b941703467622470da7bcb4b98b6a3e" }, "config_request_id": { "description": "The service instance that holds the bucket. Non-mutable.", "type": "string", "example": "1234" }, "service_name": { "description": "The service instance that holds the bucket. Non-mutable.", "type": "string", "example": "cloud-object-storage" }, "resource_kind": { "description": "The creation time of the bucket in RFC 3339 format. Non-mutable.", "format": "date-time", "type": "string", "example": "2023-10-09T12:34:56Z" }, "timestamp": { "description": "The modification time of the bucket in RFC 3339 format. Non-mutable.", "format": "date-time", "type": "string", "example": "2020-07-22T17:49:50.52Z" }, "config_state": { "$ref": "#/components/schemas/ConfigState" } }, "type": "object" }, "Next": { "description": "Container for specifying the next page link to be called when response is paginated", "properties": { "href": { "description": "URI for the next page. The URI should be the same as the request URI with a token request parameter added at the end. Token is used to identify the next resource (bucket) from where COS will continue. This may be the bucket name that has been base64 encoded.", "type": "string", "example": "config.cloud-object-storage.cloud.ibm.com/ibm/v1/config?account-id=7b941703467622470da7bcb4b98b6a3e&config_request_id=1234&resource_kind=bucket&service_instance-crn=crn%3Av1%3Abluemix%3Apublic%3Acloud-object-storage%3Aglobal%3Aa%2F7b941703467622470da7bcb4b98b6a3e%3Af9537502-7f5d-492f-b796-e21b1aa09374%3A%3A&resource_group_id=8c72100193f2429c83fccda6718f13ca?token=" } }, "type": "object" }, "ConfigState": { "description": "Container for resource configuration state. One entry per resource (bucket)", "properties": { "resource_crn": { "description": "CRN of the resource (bucket) for which the configuration properties are being provided", "type": "string", "example": "crn:v1:bluemix:public:cloud-object-storage:global:a/7b941703467622470da7bcb4b98b6a3e:f9537502-7f5d-492f-b796-e21b1aa09374:bucket:bucket-1" }, "resource_group_id": { "description": "Resource group id that resource belongs to. Resource group id from the request.", "type": "string", "example": "8c72100193f2429c83fccda6718f13ca" }, "additional_target_attributes": { "$ref": "#/components/schemas/AdditionalTargetAttributes" }, "trace": { "description": "String to uniquely identify the request. Set to request_id in the access log.", "type": "string", "example": "9f39ff2e-55d1-461b-a6f1-2d0b75138861" }, "current_config": { "$ref": "#/components/schemas/CurrentConfig" }, "errors": { "$ref": "#/components/schemas/Errors" } }, "type": "object" }, "AdditionalTargetAttributes": { "description": "Container for bucket properties that can be used as targets when specifying rules", "properties": { "resource_id": { "description": "Resource identifier (bucket name)", "type": "string", "example": "bucket-1" }, "location": { "description": "Location where the resource (bucket) is located", "type": "string", "example": "us-geo" } } }, "CurrentConfig": { "description": "Container for properties of the resource. One entry per property.", "properties": { "property": { "description": "Name of the property for which value is being provided", "type": "string", "example": "storage_class" }, "value": { "description": "Value of the property", "type": "object", "example": { "property_value": "standard" } }, "properties": { "description": "Container for nested properties", "type": "object", "example": "[ { \"property\": \"block_public_acls\", \"value\": \"true\" }, { \"property\": \"ignore_public_acls\", \"value\": \"true\" } ]" } } }, "Errors": { "description": "Container for error details encountered when gathering state information for the resource (bucket)", "properties": { "code": { "description": "Snake case string identifying the problem", "type": "string", "example": "INTERNAL_SERVER_ERROR" }, "message": { "description": "Details of the error in plain English that can help debug the error", "type": "string", "example": "Unable to access container configuration" } } }, "MD5": { "description": "The MD5 format used for MD5, Etag and If-Match request and response headers.", "type": "string", "pattern": "^[a-fA-F0-9]{32}$", "minLength": 36, "maxLength": 36 }, "Location": { "type": "string", "description": "The Location at which the created resource can be found.", "pattern": "^[\\w\\d:\\/\\-\\.]*$", "minLength": 282, "maxLength": 400 }, "Token": { "type": "string", "description": "The continuation token utilized for paginated results.", "pattern": "^[A-Za-z0-9-\\_\\=]{1,1600}$", "minLength": 1, "maxLength": 1600 }, "Href": { "type": "string", "description": "A URL to the continuation of results.", "pattern": "^.*$", "minLength": 1, "maxLength": 3000 }, "NextPagination": { "description": "Pagination response body", "required": [ "href", "token" ], "properties": { "href": { "$ref": "#/components/schemas/Href" }, "token": { "$ref": "#/components/schemas/Token" } } }, "BackupVaultName": { "description": "The name given to a BackupVault.\n\nBackupVault names must be between 3 and 63 characters long must be made of lowercase letters, numbers, dots (periods), and dashes (hyphens). BackupVault names must begin and end with a lowercase letter or number. BackupVault names can’t contain consecutive dots or dashes. BackupVault names that resemble IP addresses are not allowed. \n\nBucket and BackupVault names exist in a global namespace and therefore must be unique.", "type": "string", "minLength": 3, "maxLength": 63, "pattern": "^(?!^((25[0-5]|(2[0-4]|1\\d|[1-9]|)\\d)\\.?\\b){4}$)(^[a-z0-9][a-z0-9\\-\\.]{1,61}[a-z0-9]$)$" }, "BucketName": { "description": "The name given to a Bucket.\n\nBucket names must be between 3 and 63 characters long must be made of lowercase letters, numbers, dots (periods), and dashes (hyphens). Bucket names must begin and end with a lowercase letter or number. Bucket names can’t contain consecutive dots or dashes. Bucket names that resemble IP addresses are not allowed. \n\nBucket and BackupVault names exist in a global namespace and therefore must be unique.", "type": "string", "minLength": 3, "maxLength": 63, "pattern": "^(?!^((25[0-5]|(2[0-4]|1\\d|[1-9]|)\\d)\\.?\\b){4}$)(^[a-z0-9][a-z0-9\\-\\.]{1,61}[a-z0-9]$)$" }, "Uuid": { "type": "string", "description": "A UUID that uniquely identifies a resource.", "minLength": 36, "maxLength": 36, "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "BucketCRN": { "type": "string", "description": "The CRN for a COS Bucket.\n\nNote that Softlayer CRNs do not contain dashes within the service_instance_id, whereas regular CRNs do. Although bucket backup is not supported for softlayer accounts, this need not be enforced at the CRN parsing level.", "pattern": "^crn:v1:bluemix:public:cloud-object-storage:global:[0-9a-f]{8}:[0-9a-f\\-]{32,36}:bucket:[a-z0-9][a-z0-9\\-\\.]{3,63}$", "minLength": 107, "maxLength": 140 }, "Latest": { "type": "string", "description": "String representation of boolean values: \"true\" and \"false\". Case insensitive.", "pattern": "^(T|t)(R|r)(U|u)(E|e)|(F|f)(A|a)(L|l)(S|s)(E|e)$", "minLength": 4, "maxLength": 5 }, "BackupVaultCRN": { "type": "string", "description": "The CRN for a COS BackupVault.", "pattern": "^crn:v1:bluemix:public:cloud-object-storage:global:[0-9a-f]{8}:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}:backup-vault:[a-z0-9][a-z0-9\\-\\.]{3,63}$", "minLength": 102, "maxLength": 135 }, "ServiceInstanceID": { "description": "A COS ServiceInstance ID.", "type": "string", "pattern": "^[0-9a-f]{32}$", "minLength": 32, "maxLength": 32 }, "ServiceInstanceCRN": { "description": "A COS ServiceInstance CRN.", "type": "string", "pattern": "^crn:v1:bluemix:public:cloud-object-storage:global:[0-9a-f]{8}:[0-9a-f]{32}::$", "minLength": 93, "maxLength": 93 }, "DateTime": { "type": "string", "minLength": 19, "maxLength": 29, "format": "date-time", "pattern": "^[\\d]{4}\\-[\\d]{2}\\-[\\d]{2}T[\\d]{2}\\:[\\d]{2}\\:[\\d]{2}[\\dzZ\\:\\-\\+\\.]*$", "description": "Timestamp format used throughout the API.\n\nAccepts the following formats:\n\nYYYY-MM-DDTHH:mm:ssZ\nYYYY-MM-DDTHH:mm:ss\nYYYY-MM-DDTHH:mm:ss-hh:mm\nYYYY-MM-DDTHH:mm:ss+hh:mm\nYYYY-MM-DDTHH:mm:ss.sssZ\nYYYY-MM-DDTHH:mm:ss.sss\nYYYY-MM-DDTHH:mm:ss.sss-hh:mm\nYYYY-MM-DDTHH:mm:ss.sss+hh:mm" }, "BackupType": { "description": "The type of backup to support. For LA+GA this is limited to \"continuous\"", "enum": [ "continuous" ], "example": "continuous" }, "PolicyStatus": { "description": "The current status of the backup policy.\n\npending : the policy has been received and has begun processing.\ninitializing : pre-existing objects are being sync to the backup vault.\nactive : the policy is active and healthy.\naction_needed : the policy is unhealthy and requires some intervention to recover\ndegraded : the policy is unhealthy\nfailed : the policy has failed unrecoverably", "enum": [ "pending", "initializing", "active", "action_needed", "degraded", "failed" ], "example": "pending" }, "BackupPolicyName": { "pattern": "^[\\w\\d\\-\\_\\.]*$", "type": "string", "minLength": 1, "maxLength": 64, "example": "myBackupPolicy", "description": "The name granted to the policy.\nValidation :\n * chars limited to alphanumeric, underscore, hyphen and period" }, "BackupPolicyPrototype": { "description": "A policy that defines backup coverage for a COS Bucket.", "required": [ "policy_name", "target_backup_vault_crn", "backup_type", "initial_retention" ], "properties": { "initial_retention": { "allOf": [ { "$ref": "#/components/schemas/DeleteAfterDays" } ], "description": "This is the initial retention configuration set onto the RecoveryRange created by this policy. \nOnce created, this retention value can be changed on the RecoveryRange itself. Such changes will not be reflected in the value reported here." }, "policy_name": { "$ref": "#/components/schemas/BackupPolicyName" }, "target_backup_vault_crn": { "$ref": "#/components/schemas/BackupVaultCRN" }, "backup_type": { "$ref": "#/components/schemas/BackupType" } } }, "BackupPolicy": { "description": "The current backup coverage for a COS Bucket.", "required": [ "policy_status", "policy_id" ], "allOf": [ { "$ref": "#/components/schemas/BackupPolicyPrototype" }, { "properties": { "policy_id": { "$ref": "#/components/schemas/Uuid" }, "policy_status": { "$ref": "#/components/schemas/PolicyStatus" }, "initial_sync_progress": { "type": "number", "format": "double", "description": "Reports percent-doneness of init.\nOnly present when policy_status=INITIALIZING/PENDING.", "maximum": 100, "minimum": 0, "example": 50 }, "error_cause": { "type": "string", "pattern": "^[\\w\\d\\-\\_\\.\\s]*$", "minLength": 1, "maxLength": 4096, "example": "Some error has occurred that prevents backup coverage from being created.", "description": "reports error cause. Only present when policy_status=ERROR/FAILED." } } } ] }, "BackupPolicyCollection": { "description": "A collection of backup policies.", "required": [ "backup_policies" ], "properties": { "backup_policies": { "minItems": 0, "maxItems": 3, "description": "A collection of backup policies.", "type": "array", "items": { "$ref": "#/components/schemas/BackupPolicy" } } } }, "BackupVaultCollection": { "description": "A listing of backup vaults", "required": [ "backup_vaults" ], "properties": { "next": { "$ref": "#/components/schemas/NextPagination" }, "backup_vaults": { "type": "array", "minItems": 0, "maxItems": 100, "description": "List of Backup Vaults. If no Backup Vaults exist, this array will be empty.", "items": { "$ref": "#/components/schemas/BackupVaultCRN" } } } }, "RecoveryRangePatch": { "description": "The retention configuration for a RecoveryRange.", "type": "object", "properties": { "retention": { "allOf": [ { "$ref": "#/components/schemas/DeleteAfterDays" } ], "description": "This value can only be extended." } } }, "DeleteAfterDays": { "description": "The number of days to retain data within a RecoveryRange.", "type": "object", "required": [ "delete_after_days" ], "properties": { "delete_after_days": { "description": "The number of days to retain data within a RecoveryRange.", "type": "integer", "minimum": 1, "maximum": 36500, "example": 10 } } }, "DeleteAfterDaysWithIndefinite": { "description": "The retention configuration for a RecoveryRange. This variant allows for indefinite retention to be reported.", "type": "object", "required": [ "delete_after_days" ], "properties": { "delete_after_days": { "description": "The number of days to retain data within a RecoveryRange. -1 is a special value that denotes \"indefinite\" retention. This value can only be set implicitly via a policy created during the LA release being upgraded to the GA release.", "type": "integer", "minimum": -1, "maximum": 36500, "example": 10 } } }, "RecoveryRange": { "description": "Metadata associated with a recovery range.", "required": [ "source_resource_crn", "backup_policy_name", "range_start_time", "range_end_time", "range_create_time", "retention", "recovery_range_id" ], "allOf": [ { "type": "object", "properties": { "source_resource_crn": { "$ref": "#/components/schemas/BucketCRN" }, "backup_policy_name": { "$ref": "#/components/schemas/BackupPolicyName" }, "range_start_time": { "type": "string", "format": "date-time", "description": "The point in time at which backup coverage of the sourceResource begins. \n\nReturns \"YYYY-MM-DDTHH:mm:ss.sssZ\" timestamp format", "minLength": 24, "maxLength": 24 }, "range_end_time": { "type": "string", "format": "date-time", "description": "the point in time at which backup coverage of the sourceResource ends.\nReturns \"YYYY-MM-DDTHH:mm:ss.sssZ\" timestamp format.", "minLength": 24, "maxLength": 24 }, "range_create_time": { "type": "string", "format": "date-time", "description": "The time at which this recoveryRange was initially created.\n\nReturns \"YYYY-MM-DDTHH:mm:ss.sssZ\" timestamp format\n\nNOTE : this can be before the start-time. ", "minLength": 24, "maxLength": 24 }, "retention": { "$ref": "#/components/schemas/DeleteAfterDaysWithIndefinite" }, "recovery_range_id": { "$ref": "#/components/schemas/Uuid" } } } ] }, "RecoveryRangeCollection": { "description": "A collection of recovery ranges", "required": [ "recovery_ranges" ], "properties": { "next": { "$ref": "#/components/schemas/NextPagination" }, "recovery_ranges": { "description": "A list of recovery ranges", "type": "array", "minItems": 0, "maxItems": 1000, "items": { "$ref": "#/components/schemas/RecoveryRange" } } } }, "RestoreType": { "enum": [ "in_place" ], "description": "The type of restore to support. More options will be available in the future. " }, "RestorePrototype": { "description": "Metadata associated with a restore request.", "type": "object", "required": [ "restore_point_in_time", "target_resource_crn", "recovery_range_id", "restore_type" ], "properties": { "recovery_range_id": { "$ref": "#/components/schemas/Uuid" }, "restore_type": { "$ref": "#/components/schemas/RestoreType" }, "restore_point_in_time": { "$ref": "#/components/schemas/DateTime" }, "target_resource_crn": { "$ref": "#/components/schemas/BucketCRN" } } }, "RestoreStatus": { "enum": [ "initializing", "running", "complete", "failed" ], "description": "The current status for this restore operation. \n\ninitializing: The operation is initializing. Do not expect to see restored objects on the target bucket. \nrunning : The operation is ongoing. Expect to see some restored objects on the target bucket. \ncomplete: The operation has completed successfully. \nfailed: The operation has completed unsuccessfully." }, "Restore": { "description": "Metadata associated with a requested restore operation.", "required": [ "source_resource_crn", "restore_id", "restore_status", "init_time" ], "allOf": [ { "$ref": "#/components/schemas/RestorePrototype" }, { "properties": { "source_resource_crn": { "$ref": "#/components/schemas/BucketCRN" }, "restore_id": { "$ref": "#/components/schemas/Uuid" }, "restore_status": { "$ref": "#/components/schemas/RestoreStatus" }, "init_time": { "type": "string", "format": "date-time", "description": "The time at which this restore was initiated\nReturns \"YYYY-MM-DDTHH:mm:ss.sssZ\" timestamp format.", "minLength": 24, "maxLength": 24 }, "complete_time": { "type": "string", "format": "date-time", "description": "The time at which this restore ended (in both success and error cases)\nReturns \"YYYY-MM-DDTHH:mm:ss.sssZ\" timestamp format.", "minLength": 24, "maxLength": 24 }, "restore_percent_progress": { "type": "integer", "description": "reports percent-doneness of init. Only present when restore_status=running.", "maximum": 100, "minimum": 1 }, "error_cause": { "type": "string", "description": "Only present when restore_status=failed.", "minLength": 0, "maxLength": 1024, "pattern": "^.$" } } } ] }, "RestoreCollection": { "description": "A list of restore operations.", "required": [ "restores" ], "properties": { "next": { "$ref": "#/components/schemas/NextPagination" }, "restores": { "description": "A collection of active and completed restore operations.", "type": "array", "minItems": 0, "maxItems": 1000, "items": { "$ref": "#/components/schemas/Restore" } } } }, "BackupVaultActivityTracking": { "type": "object", "description": "Activity Tracking configuration. An empty object (`{}`) indicates no configuration, and no events will be sent (This is the same behavior as `{\"management_events\":false}`). Note that read/write events cannot be enabled, and events cannot be routed to a non-default Activity Tracker instance.", "properties": { "management_events": { "type": "boolean", "description": "Whether to send notifications for management events on the BackupVault." } } }, "BackupVaultMetricsMonitoring": { "description": "Metrics Monitoring configuration. An empty object (`{}`) indicates no configuration, and no metrics will be collected (This is the same behavior as `{\"usage_metrics_enabled\":false}`). Note that request metrics cannot be enabled, and metrics cannot be routed to a non-default metrics router instance.", "properties": { "usage_metrics_enabled": { "type": "boolean", "description": "Whether usage metrics are collected for this BackupVault." } } }, "BackupVaultPatch": { "description": "Metadata elements on a backup vault that can be updated.", "properties": { "activity_tracking": { "$ref": "#/components/schemas/BackupVaultActivityTracking" }, "metrics_monitoring": { "$ref": "#/components/schemas/BackupVaultMetricsMonitoring" } } }, "BackupVaultPrototype": { "description": "Request elements for backup vault creation.", "required": [ "backup_vault_name", "region" ], "allOf": [ { "$ref": "#/components/schemas/BackupVaultPatch" }, { "properties": { "backup_vault_name": { "$ref": "#/components/schemas/BucketName" }, "region": { "type": "string", "pattern": "^[\\w\\-]*$", "minLength": 5, "maxLength": 30, "description": "the region in which this backup-vault should be created within." }, "sse_kp_customer_root_key_crn": { "type": "string", "description": "The CRN for a KeyProtect root key.", "pattern": "^[\\w\\d\\-\\_\\.\\:]*$", "minLength": 1, "maxLength": 1024 } } } ] }, "BackupVault": { "description": "Metadata associated with a backup vault.", "example": { "crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4-e6a7-40e3-8660-20847e525436:backup-vault:mybackupvault", "service_instance_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4e6a740e3866020847e525436::", "time_created": "2024-06-02T12:00:00.000Z", "time_updated": "2024-06-02T12:00:00.000Z", "bytes_used": 0, "region": "us-south", "backup_vault_name": "mybackupvault" }, "required": [ "crn", "service_instance_crn", "time_created", "time_updated", "bytes_used" ], "allOf": [ { "$ref": "#/components/schemas/BackupVaultPrototype" }, { "properties": { "crn": { "$ref": "#/components/schemas/BackupVaultCRN" }, "service_instance_crn": { "$ref": "#/components/schemas/ServiceInstanceCRN" }, "time_created": { "type": "string", "format": "date-time", "description": "creation time of the backup-vault.\nReturns \"YYYY-MM-DDTHH:mm:ss.sssZ\" timestamp format.", "minLength": 24, "maxLength": 24 }, "time_updated": { "type": "string", "format": "date-time", "description": "time of last update to the backup-vault\nReturns \"YYYY-MM-DDTHH:mm:ss.sssZ\" timestamp format.", "minLength": 24, "maxLength": 24 }, "bytes_used": { "type": "integer", "minimum": 0, "maximum": 10000000000000000, "description": "byte useage of the backup-vault. This should include all usage, including non-current versions. A maximum value is not defined." } } } ] }, "ReqError": { "properties": { "code": { "type": "string", "description": "A code given to the error encountered.", "minLength": 0, "maxLength": 1024 }, "message": { "description": "A message describing the error encountered.", "type": "string", "minLength": 0, "maxLength": 16384 } } }, "RequestError": { "description": "Returned to users upon request failure.", "required": [ "errors", "status_code" ], "properties": { "status_code": { "type": "integer", "minimum": 0, "maximum": 999, "description": "The HTTP status code returned." }, "trace": { "type": "string", "description": "A.K.A. request-id", "minLength": 0, "maxLength": 10000000000000000, "pattern": "^.$" }, "errors": { "description": "a Container of errors.", "type": "array", "minItems": 0, "maxItems": 100, "items": { "$ref": "#/components/schemas/ReqError" } } } } } } }