Object Stores

Object stores allow you to store unstructured data that can be accessed on demand. Object stores on Civo are S3-compatible. Once created, an object store can be accessed using the S3 API, with the appropriate credentials, at the object store's endpoint URL.

Create an object store

Any user can create an object store, providing it's within their quota. The size of an object store is an integer value of Gigabytes, and object stores are hosted in specific regions.

Object stores are created by sending a POST request to https://api.civo.com/v2/objectstores.

Request

The following parameter(s) should be sent along with the request:

Name	Description
name	(required) a unique name to identify the object store bucket. e.g. "bucketA"
region	(required) the identifier for the region, from the current region list
size	(optional) integer value of Gigabytes to reserve for the Object Store. If not provided, uses a default value of 500GB. e.g. "500"
access_key_id	(optional) Access key for the Object Store. If not provided, one will be autogenerated. e.g. "ABCDE-1234-foo"

Response

The response is a JSON object that describes the initial setup of the object store. These details may not be returned in future calls to list all object stores.

{
  "id": "5cc0696d-6663-48a9-8123-87adb997138c",
  "name": "bucketA",
  "max_size_gb": 500,
  "owner_info": {
    "name": "creds",
    "access_key_id": "ABCDE-1234-foo"
  },
  "status": "ready",
  "objectstore_endpoint": "https://objectstore.civo.com/bucketA-zqws"
}

Example of creating an object store

curl -H "Authorization: bearer 12345" https://api.civo.com/v2/objectstores \
  -d "name=bucketA&size=500&region=LON1"

// At a shell prompt run:
// npm init -y
// npm i --save request

var request = require('request');

request.post(
  'https://api.civo.com/v2/objectstores',
  {
    form: {
      name: "bucketA",
      size: 500,
      region: "LON1"
    }
  },
  function (error, response, body) {
    if (!error && response.statusCode == 200) {
      console.log(body)
    }
  }
).auth(null, null, true, '12345');

require 'net/http'

http = Net::HTTP.new('api.civo.com', 443)
http.use_ssl = true

headers = {
  'Authorization' => 'bearer 12345',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = http.post('/v2/objectstores', 'name=bucketA&size=500&region=LON1', headers)

List object stores

A list of object stores accessible for an account in a given region is available by sending a GET request to https://api.civo.com/v2/objectstores.

Request

The following parameters can be sent along with the request:

Name	Description
region	(required) the identifier for the region, from the current region list
page	(optional) which page of results to return (defaults to 1)
per_page	(optional) how many results to return per page (defaults to 20)

Response

The response is a paginated JSON array of objects that describes summary details for each object store.

{
    "page": 1,
    "per_page": null,
    "pages": 1,
    "items": [
      {
        "id": "5cc0696d-6663-48a9-8123-87adb997138c",
        "name": "bucketA",
        "max_size_gb": 500,
        "owner_info": {
          "name": "creds",
          "access_key_id": "AJHDKLSLKSJ"
        },
        "status": "ready",
        "objectstore_endpoint": "https://objectstore.civo.com/bucketA-zqws"
      }
    ]
}

Example of listing object stores

curl -H "Authorization: bearer 12345" https://api.civo.com/v2/objectstores?region=LON1

// At a shell prompt run:
// npm init -y
// npm i --save request

var request = require('request');

request.get(
  'https://api.civo.com/v2/objectstores',
  {
    form: {
      region: "LON1"
    }
  },
  function (error, response, body) {
    if (!error && response.statusCode == 200) {
      console.log(body)
    }
  }
).auth(null, null, true, '12345');

require 'net/http'

http = Net::HTTP.new('api.civo.com', 443)
http.use_ssl = true

headers = {
  'Authorization' => 'bearer 12345',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = http.get('/v2/objectstores', 'region=LON1', headers)

Retrieving details of an object store

A single object store's details are available by sending a GET request to https://api.civo.com/v2/objectstores/:id.

Request

This request requires the ID parameter in the URL (query string) as well as a region parameter containing the name of the region where the object store is situated.

Response

The response is a JSON object that describes the details for the object store.

{
  "id": "5cc0696d-6663-48a9-8123-87adb997138c",
  "name": "bucketA",
  "max_size_gb": 500,
  "owner_info": {
    "name": "creds",
    "access_key_id": "ABCDE-1234-foo"
  },
  "status": "ready",
  "objectstore_endpoint": "https://objectstore.civo.com/bucketA-zqws"
}

Example of retrieving an object store

curl -H "Authorization: bearer 12345" https://api.civo.com/v2/objectstores/12345?region=NYC1

// At a shell prompt run:
// npm init -y
// npm i --save request

var request = require('request');

request.get(
  'https://api.civo.com/v2/objectstores/12345?region=NYC1',
  {},
  function (error, response, body) {
    if (!error && response.statusCode == 200) {
      console.log(body)
    }
  }
).auth(null, null, true, '12345');

require 'net/http'

http = Net::HTTP.new('api.civo.com', 443)
http.use_ssl = true

headers = {
  'Authorization' => 'bearer 12345',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = http.get('/v2/objectstores/12345?region=NYC1', headers)

Updating an object store

An object store bucket can be updated by sending a PATCH request to https://api.civo.com/v2/objectstores/:id.

Request

The following parameter(s) should be sent along with the request:

Name	Description
id	(required) The object store's ID in the URL (query string)
region	(required) the identifier for the region, from the current region list
max_size_gb	(optional) integer value of Gigabytes to reserve for the Object Store. e.g. 1000
access_key_id	(optional) Access key for the object store. Used to update the access key id of that particular store immediately. e.g. "ABCDE-1234-foo"

Response

The response is a JSON object that describes the details for the object store.

{
  "id": "5cc0696d-6663-48a9-8123-87adb997138c",
  "name": "bucketA",
  "max_size_gb": 1000,
  "owner_info": {
    "name": "creds",
    "access_key_id": "ABCDE-1234-foo"
  },
  "status": "ready",
  "objectstore_endpoint": "https://objectstore.civo.com/bucketA-zqws"
}

Example of updating an object store

curl -H "Authorization: bearer 12345" \
  -H 'Content-Type: application/json' \
  -X PATCH https://api.civo.com/v2/objectstores/1234 \
  -d '{
    "region": "NYC1",
    "max_size_gb": 1000
}'

// At a shell prompt run:
// npm init -y
// npm i --save request

var request = require('request');

request.patch(
  'https://api.civo.com/v2/objectstores/1234',
  {
    "region": "NYC1",
    "max_size_gb": 1000
  },
).auth(null, null, true, '12345');

require 'net/http'
require 'json'

url = URI("https://api.civo.com/v2/objectstores/1234")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = "Bearer 12345"
request["Content-Type"] = "application/json"
request.body = JSON.dump({
  "region": "NYC1",
  "max_size_gb": 1000
})
response = https.request(request)

Deleting an object store

An object store can be deleted by sending a DELETE request to https://api.civo.com/v2/objectstores/:id.

Request

This request requires the ID parameter in the URL (query string) as well as a region parameter containing the name of the region where the object store is located. No confirmation step is required; this step will remove the object store and all of its contents immediately.

Response

The response from the server will be a JSON block. The response will include a result field and the HTTP status will be 200 OK.

{
    "result": "success"
}

Example of deleting an object store

curl -H "Authorization: bearer 12345" \
  -X DELETE https://api.civo.com/v2/objectstores/b177be0e-61fa-11b5-ae02-5cf1329be414?region=NYC1

// At a shell prompt run:
// npm init -y
// npm i --save request

var request = require('request');

request.del(
  'https://api.civo.com/v2/objectstores/b177be0e-61fa-11b5-ae02-5cf1329be414?region=NYC1',
  function (error, response, body) {
    if (!error && response.statusCode == 200) {
      console.log(body)
    }
  }
).auth(null, null, true, '12345');

require 'net/http'

http = Net::HTTP.new('api.civo.com', 443)
http.use_ssl = true

headers = {
  'Authorization' => 'bearer 12345',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = http.delete('/v2/objectstores/b177be0e-61fa-11b5-ae02-5cf1329be414?region=NYC1', headers)

Create an object store credential

Any user can create an object store credential, providing it's within their quota. Credentials can be assigned privileges in each object store you create, and are specific to regions.

Object store credentials are created by sending a POST request to https://api.civo.com/v2/objectstore/credentials.

Request

The following parameter(s) should be sent along with the request:

Name	Description
name	(required) a unique name to identify the object store credential. e.g. "My-credentials"
region	(required) the identifier for the region, from the current region list
access_key_id	(optional) An access key id (string). If not provided, one will be autogenerated. e.g. "ABCDE-1234-foo"
secret_access_key_id	(optional) Access key secret for the credential being created (string). If not provided, one will be autogenerated. e.g. "GaNKNUTMr5AuLWOY6VOVAFaW53RGBypPlMPqGe2l"

Response

The response is a JSON object that describes the initial state of the credential that was created.

{
  "id": "5cc0696d-6663-48a9-8123-87adb997138c",
  "name": "Test-ObjectStore-Credential",
  "access_key_id": "string",
  "secret_access_key_id": "string-foo",
}

Example of creating an object store credential

curl -H "Authorization: bearer 12345" https://api.civo.com/v2/objectstore/credentials \
  -d "name=Test-ObjectStore-Credential&region=LON1"

// At a shell prompt run:
// npm init -y
// npm i --save request

var request = require('request');

request.post(
  'https://api.civo.com/v2/objectstore/credentials/',
  {
    form: {
      name: "Test-ObjectStore-Credential",
      region: "LON1"
    }
  },
  function (error, response, body) {
    if (!error && response.statusCode == 200) {
      console.log(body)
    }
  }
).auth(null, null, true, '12345');

require 'net/http'

http = Net::HTTP.new('api.civo.com', 443)
http.use_ssl = true

headers = {
  'Authorization' => 'bearer 12345',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = http.post('/v2/objectstore/credentials/', 'name=Test-ObjectStore-Credential&region=LON1', headers)

List object store credentials

A list of object store credentials accessible for an account in a given region is available by sending a GET request to https://api.civo.com/v2/objectstore/credentials.

Request

The following parameters can be sent along with the request:

Name	Description
region	(required) the identifier for the region, from the current region list
page	(optional) which page of results to return (defaults to 1)
per_page	(optional) how many results to return per page (defaults to 20)

Response

The response is a paginated JSON array of objects that describes summary details for each object store.

{
    "page": 1,
    "per_page": null,
    "pages": 1,
    "items": [
      {
        "id": "5cc0696d-6663-48a9-8123-87adb997138c",
        "name": "Test-ObjectStore-Credential",
        "access_key_id": "string",
        "secret_access_key_id": "string",
        "max_size_gb": 500,
        "suspended": false,
        "state": "pending"
      }
    ]
}

Example of listing object store credentials

curl -H "Authorization: bearer 12345" https://api.civo.com/v2/objectstore/credentials?region=LON1

// At a shell prompt run:
// npm init -y
// npm i --save request

var request = require('request');

request.get(
  'https://api.civo.com/v2/objectstore/credentials',
  {
    form: {
      region: "LON1"
    }
  },
  function (error, response, body) {
    if (!error && response.statusCode == 200) {
      console.log(body)
    }
  }
).auth(null, null, true, '12345');

require 'net/http'

http = Net::HTTP.new('api.civo.com', 443)
http.use_ssl = true

headers = {
  'Authorization' => 'bearer 12345',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = http.get('/v2/objectstore/credentials', 'region=LON1', headers)

Retrieving details of an object store credential

A single object store credential's details are available by sending a GET request to https://api.civo.com/v2/objectstore/credentials/:id.

Request

This request requires the ID parameter in the URL (query string) as well as a region parameter containing the name of the region where the object store is situated.

Response

The response is a JSON object that describes the details for the object store.

{
  
  "id": "5cc0696d-6663-48a9-8123-87adb997138c",
  "name": "Test-ObjectStore-Credential",
  "access_key_id": "string",
  "secret_access_key_id": "string",
  "max_size_gb": 500,
  "suspended": false,
  "state": "pending"
}

Example of retrieving an object store credential

curl -H "Authorization: bearer 12345" https://api.civo.com/v2/objectstore/credentials/12345?region=NYC1

// At a shell prompt run:
// npm init -y
// npm i --save request

var request = require('request');

request.get(
  'https://api.civo.com/v2/objectstore/credentials/12345?region=NYC1',
  {},
  function (error, response, body) {
    if (!error && response.statusCode == 200) {
      console.log(body)
    }
  }
).auth(null, null, true, '12345');

require 'net/http'

http = Net::HTTP.new('api.civo.com', 443)
http.use_ssl = true

headers = {
  'Authorization' => 'bearer 12345',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = http.get('/v2/objectstore/credentials/12345?region=NYC1', headers)

Updating an object store credential

An object store credential can be updated by sending a PATCH request to https://api.civo.com/v2/objectstore/credentials/:id.

Request

The following parameter(s) should be sent along with the request:

Name	Description
id	(required) The credential's ID parameter in the URL (query string)
region	(required) the identifier for the region, from the current region list
max_size_gb	(optional) integer value of Gigabytes to permit for the credential. e.g. 1000
suspended	(optional) boolean value (true/false) of whether the credential is active. e.g. true
access_key_id	(optional) Access key for the credential. Used to update the access key id of that particular credential immediately. e.g. "ABCDE-1234-foo"
secret_access_key_id	(optional) Secret key for the credential. Used to update the secret key of that particular credential immediately. e.g. "ufJDAAbe5lLop9eigttyu8auASv8APOJ44bklss489g"

Response

The response is a JSON object that describes the details for the object store.

{
  
  "id": "5cc0696d-6663-48a9-8123-87adb997138c",
  "name": "Test-ObjectStore-Credential",
  "access_key_id": "string",
  "secret_access_key_id": "string",
  "max_size_gb": 1000,
  "suspended": false,
  "state": "pending"
}

Example of updating an object store credential

curl -H "Authorization: bearer 12345" \
  -H 'Content-Type: application/json' \
  -X PATCH https://api.civo.com/v2/objectstore/credentials/1234 \
  -d '{
    "region": "NYC1",
    "suspended": true
}'

// At a shell prompt run:
// npm init -y
// npm i --save request

var request = require('request');

request.patch(
  'https://api.civo.com/v2/objectstore/credentials/1234',
  {
    "region": "NYC1",
    "suspended": true
  },
).auth(null, null, true, '12345');

require 'net/http'
require 'json'

url = URI("https://api.civo.com/v2/objectstore/credentials/1234")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = "Bearer 12345"
request["Content-Type"] = "application/json"
request.body = JSON.dump({
  "region": "NYC1",
  "suspended": true
})
response = https.request(request)

Deleting an object store credential

A credential can be deleted by sending a DELETE request to https://api.civo.com/v2/objectstore/credentials/:id.

Request

This request requires the ID parameter in the URL (query string) as well as a region parameter containing the name of the region where the credential was created. No confirmation step is required.

Response

The response from the server will be a JSON block. The response will include a result field and the HTTP status will be 200 OK.

{
    "result": "success"
}

Example of deleting an object store credential

curl -H "Authorization: bearer 12345" \
  -X DELETE https://api.civo.com/v2/objectstore/credentials/a244ddfd-41af-44b5-ea41-5cf1329be414?region=NYC1

// At a shell prompt run:
// npm init -y
// npm i --save request

var request = require('request');

request.del(
  'https://api.civo.com/v2/objectstore/credentials/a244ddfd-41af-44b5-ea41-5cf1329be414?region=NYC1',
  function (error, response, body) {
    if (!error && response.statusCode == 200) {
      console.log(body)
    }
  }
).auth(null, null, true, '12345');

require 'net/http'

http = Net::HTTP.new('api.civo.com', 443)
http.use_ssl = true

headers = {
  'Authorization' => 'bearer 12345',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = http.delete('/v2/objectstore/credentials/a244ddfd-41af-44b5-ea41-5cf1329be414?region=NYC1', headers)

Kubernetes

Compute

Databases

CivoStack Enterprise

Civo FlexCore

CivoStack for Service Providers

Cloud GPU

Carbon neutral GPU

Kubeflow as a Service

Startups

Small & mid-market

SaaS companies

CI / Testing

Move to Kubernetes

Case studies & testimonials

Learn

Blog

White papers

Documentation

Civo news

Meetups

Marketplace

Use Civo for your demos

API

Object Stores

Create an object store

Request

Response

Example of creating an object store

List object stores

Request

Response

Example of listing object stores

Retrieving details of an object store

Request

Response

Example of retrieving an object store

Updating an object store

Request

Response

Example of updating an object store

Deleting an object store

Request

Response

Example of deleting an object store

Create an object store credential

Request

Response

Example of creating an object store credential

List object store credentials

Request

Response

Example of listing object store credentials

Retrieving details of an object store credential

Request

Response

Example of retrieving an object store credential

Updating an object store credential

Request

Response

Example of updating an object store credential

Deleting an object store credential

Request

Response

Example of deleting an object store credential