1. Overview

Sphereon Storage API provides an abstraction layer for storage of (virtual) folders and streams (files/contents) fully agnostic with respect to supported storage backends. This allows for easy uniform access to and manipulation of contents regardless of the content backend being used. Currently the following backends are supported: Sphereon Cloud Storage, Amazon S3, Azure Blob Storage, Google Cloud Storage or one of the Xillio supported content repositories like Documentum, Dropbox etc. For more information about this API please visit https://docs.sphereon.com/api/storage/0.8/

1.1. Version information

Version : 0.8

1.2. Contact information

Contact : Sphereon DevOps Team
Contact Email : dev@sphereon.com

1.3. License information

License : Apache License Version 2.0
License URL : http://www.apache.org/licenses/LICENSE-2.0
Terms of service : https://docs.sphereon.com/api/storage/0.8/

1.4. URI scheme

Host : gw.api.cloud.sphereon.com
BasePath : /bucket-storage/0.8
Schemes : HTTPS

1.5. Tags

  • Backend : Backend related API’s

  • Container : Container related API’s

  • Streams : Stream (file/folder) related API’s

  • storage-controller : API for Storage

2. Introduction

The Sphereon Storage API provides a storage agnostic cloud storage solution. The key benefits are:

  • Use and learn a single API regardless of the type or location of your content

  • Retrieve content from one backend and copy or migrate them in another location in same backend or another backend altogether

  • Backup content from you application using durable cloud storage

  • Exchange contents between applications easily

  • The Storage API can be used with most of our content services. This directly provides you with content functionality on your files

  • Files don’t have to be stored in our cloud for processing. Our content services retrieve an in memory stream of the content, process that and return the result to your storage location. You are in control of your files!

2.1. Integration with other API’s

Almost all of our Content API’s have uniform content access, meaning the storage API is the base for all content retrieval, manipulation and storage.

We provide you with 2 ways to interact with files and content.

2.1.1. Content manipulation from Content API itself

Every API has it’s own content upload and download endpoints directly in the content API. Files are stored in our cloud, or one your own storage locations. Behind the scenes we use our storage API’s. This allows for simple integrations on your behalf. Our PDF conversion API has simple multipart file upload capability for to be converted files, as wel as download capability for the result(s).

2.1.2. Pass in storage locations to the Content API

You use the Storage API directly to upload, download and delete content. The Storage API will provide you with Json objects for the storage location(s). You use these locations for initiating the specific content service.
This solution has the benefit that you don’t have to upload a file to our Content Service beforehand. We will retrieve the file when necessary.

All our API’s will always return information about stream and storage locations. This allows you to mix and match both approaches as you see fit.

2.2. Supported storage solutions

2.2.1. Cloud object/bucket storage

The API supports the object/bucket storage solutions of some large cloud vendors with characteristics like:

  • Durable

  • Scalable

Google Cloud Storage ®

Google Cloud Storage ® provides unified object storage for enterprises.
Our API supports GEO redundant storage and highly available storage of the Google Cloud Storage solution.

More info: https://cloud.google.com/storage/

Amazon S3 ®

Amazon S3 ® provides object storage in so called buckets that map to containers in our API. It has unparalleled GEO redundant storage support

More info: https://aws.amazon.com/s3

Azure Blob Store ®

Amazon S3 ® provides object storage in so called buckets that map to containers in our API. It has unparalleled GEO redundant storage support

More info: https://aws.amazon.com/s3

2.2.2. Sphereon Storage

Sphereon provides the possibility to store files in datacenters we use for our cloud platforms. This is a lower cost solution, but of course with redundant storage builtin

2.2.3. Xillio Engine’s ® Content Repositories

The Xillio Engine provides access to a slew of Content Repositories like

  • Dropbox

  • Documentum

  • Sharepoint

And many more. To benefit from these repositories you need an additional account at our partner Xillio. Of course we are happy to provide you with additional information.

More info: https://xillio.com

All other trademarks not owned by Sphereon that appear in this documentation are the property of their respective owners, not limited to
Google ® and Google Cloud Storage ® are registered trademarks of Google LLC.
Amazon ® and Amazon S3 ® are registered trademarks of Amazon
== SDKs

Our API’s are based on the OpenAPI specification (formerly known as Swagger specification). This means you can pickup our REST API definition file and generate classes for your favorite programming language.

2.3. Provided SDKs and generated SDKs

2.3.1. Provide SDKs

For some popular programming languages we provide you with an SDK implementation

2.3.2. Generate your own SDK

Please feel free to generate an SDK for your own programming language using our Swagger file. Please note that we do not officially support your SDK, but unofficially we are here to help of course.
You can use Swagger codegen for this (https://swagger.io/swagger-codegen). Swagger codegen support almost 100 programming languages.

Please use version 2.X of swagger codegen with our current API’s

2.4. Version compatibility between SDK and API

Al of our REST API’s follow the versioning scheme below

XX.YY

When the major number (XX) changes this means we completely redesign an API.
Minor number (YY) changes means smaller backwards comptible breaks within the API. An API can be changed forward compatible within the same minor number.

Our SDK follow the below versioning scheme

XX.YY.ZZ

The major (XX) and minor (YY) number always map directly to the accompanying REST API version.
The micro number (ZZ) is used if we add forward compatible changes to our REST API, or when bugs are encountered in a specific SDK.

3. Resources

3.1. Backend

Backend related API’s

3.1.1. Create a new backend

POST /backends
Description

Create a new backend

Parameters
Type Name Description Schema

Body

backendRequest
required

backendRequest

BackendRequest
Responses
HTTP Code Description Schema

201

Backend created

BackendResponse

400

Invalid backend request

ErrorResponse
Consumes

  • application/json;charset=UTF-8

Produces

  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global
Example Java SDK
Java
RequestCredentials requestCredentials = new RequestCredentials(); (1)
requestCredentials.credentialType(CredentialTypeEnum.OAUTHCREDENTIALS);
requestCredentials.setOauthCredentials(new OAuthCredentials()
    .accesskeyid("key-id")
    .secretkey("key")
    .authenticationProvider(AuthenticationProviderEnum.END_USER));

BackendRequest backendRequest = new BackendRequest(); (2)
backendRequest
    .name("example")
    .description("Example Backend")
    .backendType(BackendTypeEnum.AMAZON_S3);
backendRequest.requestCredentials(requestCredentials);

BackendResponse response = api.createBackend(backendRequest); (3)

  1. We need to supply credentials for the backend. Please consult your cloud provider authentication options

  2. Create the request for a new backend. An Id will be created automatically. The name your provide can be used for the lookup as well

  3. Create the backend

3.1.2. Get backend

GET /backends/{backendId}
Description

Get an existing backend. Please note that you can retrieve a backend both by it’s ID, which is globally unique among tenants and applications, as well as by name, which is unique within an application of a tenant

Parameters
Type Name Description Schema

Path

backendId
required

backendId

string
Responses
HTTP Code Description Schema

200

Container info returned

BackendResponse

400

Invalid backend name or id

ErrorResponse

404

Container does not exist

ErrorResponse
Consumes

  • application/json

Produces

  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

3.1.3. Update backend

PUT /backends/{backendId}
Description

Update backend with new information

Parameters
Type Name Description Schema

Path

backendId
required

backendId

string

Body

backendRequest
required

backendRequest

BackendRequest
Responses
HTTP Code Description Schema

200

Backend updated

BackendResponse

400

Invalid backend request

ErrorResponse

404

Backend was not found

ErrorResponse
Consumes

  • application/json;charset=UTF-8

Produces

  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

3.1.4. Delete a backend

DELETE /backends/{backendId}
Description

Delete an existing backend. Please note that you can delete a backend both by it’s ID, which is globally unique among tenants and applications, as well as by name, which is unique within an application of a tenant

Parameters
Type Name Description Schema

Path

backendId
required

backendId

string
Responses
HTTP Code Description Schema

200

Backend deleted

BackendResponse

404

Backend was already deleted or unknown backend

ErrorResponse
Consumes

  • application/json

Produces

  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

3.2. Container

Container related API’s

3.2.1. Create container

POST /containers
Description

Create a new container

Parameters
Type Name Description Schema

Body

containerRequest
required

containerRequest

ContainerRequest
Responses
HTTP Code Description Schema

201

Container created

ContainerResponse

400

Invalid Container request

ErrorResponse

404

Backend was not found

ErrorResponse
Consumes

  • application/json;charset=UTF-8

Produces

  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

3.2.2. Get container

GET /containers/{containerId}
Description

Get an existing container. Please note that you can retrieve a container both by it’s ID, which is globally unique among tenants and applications, as well as by name, which is unique within an application of a tenant

Parameters
Type Name Description Schema

Path

containerId
required

containerId

string
Responses
HTTP Code Description Schema

200

Container info returned

ContainerResponse

400

Invalid container name or id

ErrorResponse

404

Container does not exist

ErrorResponse
Consumes

  • application/json

Produces

  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

3.2.3. Update container

PUT /containers/{containerId}
Description

Update container with new information

Parameters
Type Name Description Schema

Path

containerId
required

containerId

string

Body

containerRequest
required

containerRequest

ContainerRequest
Responses
HTTP Code Description Schema

200

Container updated

ContainerResponse

400

Invalid Container request

ErrorResponse

404

Backend was not found

ErrorResponse
Consumes

  • application/json;charset=UTF-8

Produces

  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

3.2.4. Delete container

DELETE /containers/{containerId}
Description

Delete a container Please note that you can delete a container both by it’s ID, which is globally unique among tenants and applications, as well as by name, which is unique within an application of a tenant

Parameters
Type Name Description Schema

Path

containerId
required

containerId

string

Query

delete
optional

delete

enum (RECURSIVE, EMPTY_ONLY)
Responses
HTTP Code Description Schema

200

Container deleted

ContainerResponse

400

Invalid container name or container was not empty and recursion was not set

ErrorResponse

404

Container was not found

ErrorResponse
Consumes

  • application/json

Produces

  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

3.3. Streams

Stream (file/folder) related API’s

3.3.1. Get stream

POST /streams/location
Description

Get stream from a container using a StreamLocation

Parameters
Type Name Description Schema

Body

streamLocation
required

streamLocation

StreamLocation
Responses
HTTP Code Description Schema

200

Object retrieved

string (byte)

400

Invalid container or stream name

ErrorResponse

404

Object or container did not exist

ErrorResponse
Consumes

  • application/json;charset=UTF-8

Produces

  • application/octet-stream

  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

3.3.2. Create a new stream

POST /streams/path/{containerId}/{path}
Description

Create a new stream within a container. Query parameter creationMode accepts values NEW_ONLY to create a new stream, REQUIRE_EXISTING to update an stream and ALLOW_EXISTING to create a new stream or overwrite an existing stream.

Parameters
Type Name Description Schema

Path

containerId
required

containerId

string

Path

path
required

path

string

Query

propagationType
optional

propagationType

enum (NO, REQUIRE, ALLOW)

FormData

stream
required

stream

file
Responses
HTTP Code Description Schema

201

Object created

StreamResponse

400

Invalid container or stream request

ErrorResponse

404

Container was not found

ErrorResponse
Consumes

  • multipart/form-data

Produces

  • application/json

Security
Type Name Scopes

oauth2

oauth2schema

global

3.3.3. Get stream

GET /streams/path/{containerId}/{path}
Description

Get stream from a container using a path

Parameters
Type Name Description Schema

Path

containerId
required

containerId

string

Path

path
required

path

string
Responses
HTTP Code Description Schema

200

Object retrieved

string (byte)

400

Invalid container or stream name

ErrorResponse

404

Object or container did not exist

ErrorResponse
Consumes

  • application/json

Produces

  • application/octet-stream

  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

3.3.4. Update existing stream

PUT /streams/path/{containerId}/{path}
Description

Update stream within a container

Parameters
Type Name Description Schema

Path

containerId
required

containerId

string

Path

path
required

path

string

FormData

stream
required

stream

file
Responses
HTTP Code Description Schema

201

Object update

StreamResponse

400

Invalid container or stream request

ErrorResponse

404

Container was not found

ErrorResponse
Consumes

  • multipart/form-data

Produces

  • application/json

Security
Type Name Scopes

oauth2

oauth2schema

global

3.3.5. Delete existing stream

DELETE /streams/path/{containerId}/{path}
Description

Delete stream from a container. There is no request nor response body for a delete operation.

Parameters
Type Name Description Schema

Path

containerId
required

containerId

string

Path

path
required

path

string
Responses
HTTP Code Description Schema

200

Object deleted

No Content

400

Invalid container or stream name

ErrorResponse

404

Container or stream was not found

ErrorResponse
Consumes

  • application/json

Produces

  • /

Security
Type Name Scopes

oauth2

oauth2schema

global

3.4. Storage-controller

API for Storage

4. Security

4.1. oauth2schema

Type : oauth2
Flow : application
Token URL : https://gw.api.cloud.sphereon.com/token

Name Description

global

accessEverything

5. Definitions

5.1. Backend

Name Description Schema

backendType
required

The type of backend that is created. This field allows users to create a local backend or with supported 3rd parties.

enum (SPHEREON_CLOUD_STORAGE, AMAZON_S3, MS_AZURE_BLOB_STORAGE, GOOGLE_CLOUD_STORAGE, XILLIO_ENGINE)

credentials
optional

The credentials that are used to connect with the backend storage location.

< Credentials > array

description
optional

string

endpoint
optional

The endpoint for the backend. Please note that only a Xillio backend needs the endpoint configured for now. Other backends are resolved automatically

string

id
optional

string

name
required

string

parentId
optional

The backend that is used for when properties are not set. This allows usernamePasswordCredentials to be set at one backend and re-used by multiple backends.

string

region
optional

The storage region where the container and files are stored. This option is available for Google and Amazon Storage. For Azure is only possible to set the region when creating the storage account.

enum (AMAZON_S3_AP_NORTHEAST_1, AMAZON_S3_AP_NORTHEAST_2, AMAZON_S3_AP_SOUTH_1, AMAZON_S3_AP_SOUTHEAST_1, AMAZON_S3_AP_SOUTHEAST_2, AMAZON_S3_CA_CENTRAL_1, AMAZON_S3_CN_NORTH_1, AMAZON_S3_EU_CENTRAL_1, AMAZON_S3_EU_WEST_1, AMAZON_S3_EU_WEST_2, AMAZON_S3_SA_EAST_1, AMAZON_S3_US_EAST_1, AMAZON_S3_US_EAST_2, AMAZON_S3_US_STANDARD, AMAZON_S3_US_WEST_1, AMAZON_S3_US_WEST_2, GOOGLE_STORAGE_ASIA, GOOGLE_STORAGE_ASIA_EAST1, GOOGLE_STORAGE_EU, GOOGLE_STORAGE_US, GOOGLE_STORAGE_US_CENTRAL1, GOOGLE_STORAGE_US_CENTRAL2, GOOGLE_STORAGE_US_EAST1, GOOGLE_STORAGE_US_EAST2, GOOGLE_STORAGE_US_EAST3, GOOGLE_STORAGE_US_WEST1)

5.2. BackendRequest

Name Description Schema

backendType
required

The type of backend that is created. This field allows users to create a local backend or with supported 3rd parties.

enum (SPHEREON_CLOUD_STORAGE, AMAZON_S3, MS_AZURE_BLOB_STORAGE, GOOGLE_CLOUD_STORAGE, XILLIO_ENGINE)

credentials
required

The credentials details

CredentialsRequest

description
optional

string

endpoint
optional

The endpoint for the backend. Please note that only a Xillio backend needs the endpoint configured for now. Other backends are resolved automatically

string

name
required

string

parentId
optional

The backend that is used for when properties are not set. This allows usernamePasswordCredentials to be set at one backend and re-used by multiple backends.

string

region
optional

The storage region where the container and files are stored. This option is available for Google and Amazon Storage. For Azure is only possible to set the region when creating the storage account.

enum (AMAZON_S3_AP_NORTHEAST_1, AMAZON_S3_AP_NORTHEAST_2, AMAZON_S3_AP_SOUTH_1, AMAZON_S3_AP_SOUTHEAST_1, AMAZON_S3_AP_SOUTHEAST_2, AMAZON_S3_CA_CENTRAL_1, AMAZON_S3_CN_NORTH_1, AMAZON_S3_EU_CENTRAL_1, AMAZON_S3_EU_WEST_1, AMAZON_S3_EU_WEST_2, AMAZON_S3_SA_EAST_1, AMAZON_S3_US_EAST_1, AMAZON_S3_US_EAST_2, AMAZON_S3_US_STANDARD, AMAZON_S3_US_WEST_1, AMAZON_S3_US_WEST_2, GOOGLE_STORAGE_ASIA, GOOGLE_STORAGE_ASIA_EAST1, GOOGLE_STORAGE_EU, GOOGLE_STORAGE_US, GOOGLE_STORAGE_US_CENTRAL1, GOOGLE_STORAGE_US_CENTRAL2, GOOGLE_STORAGE_US_EAST1, GOOGLE_STORAGE_US_EAST2, GOOGLE_STORAGE_US_EAST3, GOOGLE_STORAGE_US_WEST1)

5.3. BackendResponse

Name Schema

backend
optional

Backend

containers
optional

< Container > array

state
optional

enum (REQUESTED, CREATED, UPDATED, DELETED)

5.4. BearerTokenCredentials

Name Description Schema

credentialType
optional

enum (NoCredentials, OAuthCredentials, BearerTokenCredentials, UsernamePasswordCredentials, OAuth2ClientCredentials)

token
optional

The bearer token.

string

5.5. Container

Name Description Schema

backendId
optional

The Sphereon backend in which the container will be stored or is stored.

string

description
optional

string

id
optional

string

name
optional

string

5.6. ContainerRequest

Name Description Schema

backendId
optional

The backend in which the container will be stored or is stored.

string

description
optional

string

name
optional

string

propagationType
optional

The way a container is creation. If propagation is no a new container will be created in the backend; If propagation is require a existing container is used from the backend. If propagation is allowed the a new container is created if the container does not exists.

enum (NO, REQUIRE, ALLOW)

5.7. ContainerResponse

Name Schema

container
optional

Container

state
optional

enum (REQUESTED, CREATED, UPDATED, DELETED)

5.8. Credentials

Name Schema

authenticationProvider
optional

enum (API_SUPPLIER, API_IMPLEMENTER)

credentialType
optional

enum (NoCredentials, OAuthCredentials, BearerTokenCredentials, UsernamePasswordCredentials, OAuth2ClientCredentials)

5.9. CredentialsRequest

Name Description Schema

bearerTokenCredentials
optional

The bearerTokenCredentials for this backend.

BearerTokenCredentials

credentials
optional

< Credentials > array

individualCredentials
optional

Credentials

oAuth2ClientCredentials
optional

The oAuth2 Client Credentials for this backend.

OAuth2ClientCredentials

oAuthCredentials
optional

The oAuth Credentials for this backend.

OAuthCredentials

usernamePasswordCredentials
optional

The usernamePasswordCredentials for this backend.

UsernamePasswordCredentials

5.10. Error

An error

Name Schema

cause
optional

Error

code
required

string

level
required

enum (INFO, WARNING, FATAL)

message
required

string

5.11. ErrorResponse

The error response

Name Schema

errors
optional

< Error > array

5.12. InfoResponse

Name Schema

streamInfos
optional

< StreamInfo > array

5.13. OAuth2ClientCredentials

Name Description Schema

client_id
optional

The clientId

string

client_secret
optional

The clientSecret.

string

credentialType
optional

enum (NoCredentials, OAuthCredentials, BearerTokenCredentials, UsernamePasswordCredentials, OAuth2ClientCredentials)

5.14. OAuthCredentials

Name Description Schema

accesskeyid
optional

The OAuth access key.

string

credentialType
optional

enum (NoCredentials, OAuthCredentials, BearerTokenCredentials, UsernamePasswordCredentials, OAuth2ClientCredentials)

secretkey
optional

The OAuth secret key.

string

5.15. StreamInfo

Information record from a data stream

Name Schema

containerName
optional

string

contentType
optional

string

etag
optional

string

providerId
optional

string

region
optional

enum (AMAZON_S3_AP_NORTHEAST_1, AMAZON_S3_AP_NORTHEAST_2, AMAZON_S3_AP_SOUTH_1, AMAZON_S3_AP_SOUTHEAST_1, AMAZON_S3_AP_SOUTHEAST_2, AMAZON_S3_CA_CENTRAL_1, AMAZON_S3_CN_NORTH_1, AMAZON_S3_EU_CENTRAL_1, AMAZON_S3_EU_WEST_1, AMAZON_S3_EU_WEST_2, AMAZON_S3_SA_EAST_1, AMAZON_S3_US_EAST_1, AMAZON_S3_US_EAST_2, AMAZON_S3_US_STANDARD, AMAZON_S3_US_WEST_1, AMAZON_S3_US_WEST_2, GOOGLE_STORAGE_ASIA, GOOGLE_STORAGE_ASIA_EAST1, GOOGLE_STORAGE_EU, GOOGLE_STORAGE_US, GOOGLE_STORAGE_US_CENTRAL1, GOOGLE_STORAGE_US_CENTRAL2, GOOGLE_STORAGE_US_EAST1, GOOGLE_STORAGE_US_EAST2, GOOGLE_STORAGE_US_EAST3, GOOGLE_STORAGE_US_WEST1)

streamLength
optional

integer (int64)

streamLocation
optional

StreamLocation

timeCreated
optional

string (date-time)

timeModified
optional

string (date-time)

userMetadata
optional

< string, string > map

5.16. StreamLocation

Location record of data stream

Name Schema

containerId
optional

string

filename
optional

string

folderPath
optional

string

id
optional
read-only

string

name
optional

string

originalFilename
optional

string

5.17. StreamResponse

Name Schema

contentLength
optional

integer (int64)

contentType
optional

string

state
optional

enum (REQUESTED, CREATED, UPDATED, DELETED)

streamLocation
optional

StreamLocation

5.18. UsernamePasswordCredentials

Name Description Schema

credentialType
optional

enum (NoCredentials, OAuthCredentials, BearerTokenCredentials, UsernamePasswordCredentials, OAuth2ClientCredentials)

domain
optional

The domain associated with the username.

string

password
optional

The password associated with the username.

string

userName
optional

The username.

string