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 |
backendRequest |
Responses
HTTP Code | Description | Schema |
---|---|---|
201 |
Backend created |
|
400 |
Invalid backend request |
Consumes
-
application/json;charset=UTF-8
Produces
-
application/json;charset=UTF-8
Security
Type | Name | Scopes |
---|---|---|
oauth2 |
global |
Example Java SDK
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)
-
We need to supply credentials for the backend. Please consult your cloud provider authentication options
-
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
-
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 |
backendId |
string |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
Container info returned |
|
400 |
Invalid backend name or id |
|
404 |
Container does not exist |
Consumes
-
application/json
Produces
-
application/json;charset=UTF-8
Security
Type | Name | Scopes |
---|---|---|
oauth2 |
global |
3.1.3. Update backend
PUT /backends/{backendId}
Description
Update backend with new information
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Path |
backendId |
backendId |
string |
Body |
backendRequest |
backendRequest |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
Backend updated |
|
400 |
Invalid backend request |
|
404 |
Backend was not found |
Consumes
-
application/json;charset=UTF-8
Produces
-
application/json;charset=UTF-8
Security
Type | Name | Scopes |
---|---|---|
oauth2 |
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 |
backendId |
string |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
Backend deleted |
|
404 |
Backend was already deleted or unknown backend |
Consumes
-
application/json
Produces
-
application/json;charset=UTF-8
Security
Type | Name | Scopes |
---|---|---|
oauth2 |
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 |
containerRequest |
Responses
HTTP Code | Description | Schema |
---|---|---|
201 |
Container created |
|
400 |
Invalid Container request |
|
404 |
Backend was not found |
Consumes
-
application/json;charset=UTF-8
Produces
-
application/json;charset=UTF-8
Security
Type | Name | Scopes |
---|---|---|
oauth2 |
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 |
containerId |
string |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
Container info returned |
|
400 |
Invalid container name or id |
|
404 |
Container does not exist |
Consumes
-
application/json
Produces
-
application/json;charset=UTF-8
Security
Type | Name | Scopes |
---|---|---|
oauth2 |
global |
3.2.3. Update container
PUT /containers/{containerId}
Description
Update container with new information
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Path |
containerId |
containerId |
string |
Body |
containerRequest |
containerRequest |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
Container updated |
|
400 |
Invalid Container request |
|
404 |
Backend was not found |
Consumes
-
application/json;charset=UTF-8
Produces
-
application/json;charset=UTF-8
Security
Type | Name | Scopes |
---|---|---|
oauth2 |
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 |
containerId |
string |
Query |
delete |
delete |
enum (RECURSIVE, EMPTY_ONLY) |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
Container deleted |
|
400 |
Invalid container name or container was not empty and recursion was not set |
|
404 |
Container was not found |
Consumes
-
application/json
Produces
-
application/json;charset=UTF-8
Security
Type | Name | Scopes |
---|---|---|
oauth2 |
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 |
streamLocation |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
Object retrieved |
string (byte) |
400 |
Invalid container or stream name |
|
404 |
Object or container did not exist |
Consumes
-
application/json;charset=UTF-8
Produces
-
application/octet-stream
-
application/json;charset=UTF-8
Security
Type | Name | Scopes |
---|---|---|
oauth2 |
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 |
containerId |
string |
Path |
path |
path |
string |
Query |
propagationType |
propagationType |
enum (NO, REQUIRE, ALLOW) |
FormData |
stream |
stream |
file |
Responses
HTTP Code | Description | Schema |
---|---|---|
201 |
Object created |
|
400 |
Invalid container or stream request |
|
404 |
Container was not found |
Consumes
-
multipart/form-data
Produces
-
application/json
Security
Type | Name | Scopes |
---|---|---|
oauth2 |
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 |
containerId |
string |
Path |
path |
path |
string |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
Object retrieved |
string (byte) |
400 |
Invalid container or stream name |
|
404 |
Object or container did not exist |
Consumes
-
application/json
Produces
-
application/octet-stream
-
application/json;charset=UTF-8
Security
Type | Name | Scopes |
---|---|---|
oauth2 |
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 |
containerId |
string |
Path |
path |
path |
string |
FormData |
stream |
stream |
file |
Responses
HTTP Code | Description | Schema |
---|---|---|
201 |
Object update |
|
400 |
Invalid container or stream request |
|
404 |
Container was not found |
Consumes
-
multipart/form-data
Produces
-
application/json
Security
Type | Name | Scopes |
---|---|---|
oauth2 |
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 |
containerId |
string |
Path |
path |
path |
string |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
Object deleted |
No Content |
400 |
Invalid container or stream name |
|
404 |
Container or stream was not found |
Consumes
-
application/json
Produces
-
/
Security
Type | Name | Scopes |
---|---|---|
oauth2 |
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 |
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 |
The credentials that are used to connect with the backend storage location. |
< Credentials > array |
description |
string |
|
endpoint |
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 |
string |
|
name |
string |
|
parentId |
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 |
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 |
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 |
The credentials details |
|
description |
string |
|
endpoint |
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 |
string |
|
parentId |
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 |
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 |
|
containers |
< Container > array |
state |
enum (REQUESTED, CREATED, UPDATED, DELETED) |
5.4. BearerTokenCredentials
Name | Description | Schema |
---|---|---|
credentialType |
enum (NoCredentials, OAuthCredentials, BearerTokenCredentials, UsernamePasswordCredentials, OAuth2ClientCredentials) |
|
token |
The bearer token. |
string |
5.5. Container
Name | Description | Schema |
---|---|---|
backendId |
The Sphereon backend in which the container will be stored or is stored. |
string |
description |
string |
|
id |
string |
|
name |
string |
5.6. ContainerRequest
Name | Description | Schema |
---|---|---|
backendId |
The backend in which the container will be stored or is stored. |
string |
description |
string |
|
name |
string |
|
propagationType |
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 |
|
state |
enum (REQUESTED, CREATED, UPDATED, DELETED) |
5.8. Credentials
Name | Schema |
---|---|
authenticationProvider |
enum (API_SUPPLIER, API_IMPLEMENTER) |
credentialType |
enum (NoCredentials, OAuthCredentials, BearerTokenCredentials, UsernamePasswordCredentials, OAuth2ClientCredentials) |
5.9. CredentialsRequest
Name | Description | Schema |
---|---|---|
bearerTokenCredentials |
The bearerTokenCredentials for this backend. |
|
credentials |
< Credentials > array |
|
individualCredentials |
||
oAuth2ClientCredentials |
The oAuth2 Client Credentials for this backend. |
|
oAuthCredentials |
The oAuth Credentials for this backend. |
|
usernamePasswordCredentials |
The usernamePasswordCredentials for this backend. |
5.10. Error
An error
Name | Schema |
---|---|
cause |
|
code |
string |
level |
enum (INFO, WARNING, FATAL) |
message |
string |
5.12. InfoResponse
Name | Schema |
---|---|
streamInfos |
< StreamInfo > array |
5.13. OAuth2ClientCredentials
Name | Description | Schema |
---|---|---|
client_id |
The clientId |
string |
client_secret |
The clientSecret. |
string |
credentialType |
enum (NoCredentials, OAuthCredentials, BearerTokenCredentials, UsernamePasswordCredentials, OAuth2ClientCredentials) |
5.14. OAuthCredentials
Name | Description | Schema |
---|---|---|
accesskeyid |
The OAuth access key. |
string |
credentialType |
enum (NoCredentials, OAuthCredentials, BearerTokenCredentials, UsernamePasswordCredentials, OAuth2ClientCredentials) |
|
secretkey |
The OAuth secret key. |
string |
5.15. StreamInfo
Information record from a data stream
Name | Schema |
---|---|
containerName |
string |
contentType |
string |
etag |
string |
providerId |
string |
region |
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 |
integer (int64) |
streamLocation |
|
timeCreated |
string (date-time) |
timeModified |
string (date-time) |
userMetadata |
< string, string > map |
5.16. StreamLocation
Location record of data stream
Name | Schema |
---|---|
containerId |
string |
filename |
string |
folderPath |
string |
id |
string |
name |
string |
originalFilename |
string |
5.17. StreamResponse
Name | Schema |
---|---|
contentLength |
integer (int64) |
contentType |
string |
state |
enum (REQUESTED, CREATED, UPDATED, DELETED) |
streamLocation |
5.18. UsernamePasswordCredentials
Name | Description | Schema |
---|---|---|
credentialType |
enum (NoCredentials, OAuthCredentials, BearerTokenCredentials, UsernamePasswordCredentials, OAuth2ClientCredentials) |
|
domain |
The domain associated with the username. |
string |
password |
The password associated with the username. |
string |
userName |
The username. |
string |