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:

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
• Node.js
• Ruby

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:

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
• Node.js
• Ruby

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
• Node.js
• Ruby

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:

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
• Node.js
• Ruby

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
• Node.js
• Ruby

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:

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
• Node.js
• Ruby

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:

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
• Node.js
• Ruby

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
• Node.js
• Ruby

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:

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
• Node.js
• Ruby

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
• Node.js
• Ruby

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)