Strongbox Store API Version 1

API Endpoint

http://sbox00.databeam.de

Welcome to the Strongbox Store API, offering access to the Strongbox distributed object store. This document describes version 1 of the API.

Getting Started ¶

Transport ¶

The Strongbox store API is available via HTTP only. Both HTTP/1.1 and HTTP/2 are supported.

The base URI for all resources is:

http://{hostname}/v1

Authorization ¶

Requests are not authenticated nor authorized.

Rate Limiting ¶

Rate limiting is not used.

API Deprecation ¶

Over time, the backend may change and a new version of the API will be released. To inform developers and clients of upcoming changes, the server indicates API deprecation by sending a Warning header with warning-code 229.

Example:

Warning: 299 - “API Deprecation Warning: Support for this request will be dropped soon, please update your client.”

While API deprecation is indicated, the API call will still function as documented. At a later stage, support for individual API calls up to the complete API-path may be dropped. This is indicated by responding with HTTP status code 410 (see section ‘Error handling’).

Payload format ¶

Unless explicitely stated, request and response bodies are encoded in JSON format. Appropriate headers (Content-Type: application/json, Accept: application/json) must be set.

Timestamps are encoded in ISO 8601 format, including timezone offset from UTC. Example:

{ “validDate”: “2037-12-31T15:29:59+00:00” }

Error handling ¶

The API responds with different HTTP Status Codes and messages:

HTTP 400 Bad Request

The request cannot be processed for syntax reasons. This could be because of a missing field, an incorrect type or an invalid value. The error message might provide more information. Check your code against the documentation. Retrying the request will not improve your chances of success.

Example:
```
{
    "error": {
      "code": 400001,
      "message": "The request cannot be fulfilled.",
      "details": ["Invalid or unsupported value.", "Please consult the documentation."]
    }
  }
```
HTTP 401 Not Authorized

Your request is missing an authenticated session ID, your session ID has expired, or your user is not valid. Obtain a new session and/or authenticate it (see the AuthResource).
HTTP 403 Forbidden

Your request was syntactically correct, but violated somehing else. Possible reasons are feature- and/or contract-limitations, accessing someone else’s data without authorization. Retrying the request will lead to the same result. The details of the message will provide more details.

Example:
```
{
  "error": {
    "code": 403001,
    "message": "This request is forbidden.",
    "details": ["TTL is not acceptable"]
  }
}
```
HTTP 404 Not Found

The request could not be fulfilled, since the resource or entity at the URI does not exist (anymore). Retrying is futile.
HTTP 405 Method Not Allowed

The resource or entity does not support the HTTP method. Please consult the documentation.
HTTP 406 Not Acceptable

The backend cannot supply the response in the requested mediatype (as per the Accept request header). Please consult the documentation. You can retry your request, specifying appropriate headers.
HTTP 409 Conflict

The request was not successful, because the a persistence-opertion failed. This can be temporary, or because another operation has modified the data in the meantime. Reread your data again, apply your changes and retry the request. You haven’t broken anything yet.
HTTP 410 Gone

The request was once valid but is no longer acceptable. This is a permanent situation. It indicates that parts of the API have since been deprecated and support for them has been dropped. It is recommended to consult the documentation and update clients.
HTTP 413 Request Entity Too Large

The backend is unwilling or unable to process a request body of this size.
HTTP 415 Unsupported Mediatype

The backend does not support the request payload, as announced in the Content-Type header.
HTTP 416 Range Not Satisfiable

This occurs when an upload or download request does not provide acceptable values for headers Range or Content-Range.
HTTP 500 Server Error

Oops! It looks like something went horribly wrong in the backend. You might want to get in touch with us.
HTTP 503 Maintenance

The host you’re addressing is currently undergoing maintenance and is not serving requests. You can retry your request until is being accepted again.
HTTP 509 Rate Limit Exceeded

The request was not accepted because of a rate limit violation. The API is protected against overload and bruteforce attacks with rate limits. See the section on rate limiting for details. The response contains a Retry-After header (in seconds) to assist in retrying the request again.

Example:
```
Retry-After: 23
```

Ring ¶

Ring Environment ¶

GET http://sbox00.databeam.de/v1/ring

Responses200

Headers

Content-Type: application/json

Body

{
  "ringNodes": [
    {
      "uid": "node1",
      "baseUrl": "http://192.0.2.10:8094/",
      "status": "UNKNOWN"
    }
  ],
  "maxChunkSize": 4000000
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "ringNodes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "uid": {
            "type": "string",
            "enum": [
              "node1"
            ],
            "description": "The cluster-wide unique ID of the node. No whitespace allowed."
          },
          "baseUrl": {
            "type": "string",
            "enum": [
              "http://192.0.2.10:8094/"
            ],
            "description": "The URL where the ring node is listening for requests."
          },
          "status": {
            "type": "string",
            "enum": [
              "UNKNOWN",
              "DOWN",
              "ACTIVE",
              "DRAINING",
              "DRAINING_DOWN",
              "JOINING",
              "JOINING_DOWN"
            ],
            "description": "Status of the ring node."
          }
        },
        "required": [
          "uid",
          "baseUrl",
          "status"
        ],
        "additionalProperties": false
      },
      "description": "The list of ring nodes matching the request."
    },
    "maxChunkSize": {
      "type": "number",
      "description": "Max allows size of chunks in Bytes."
    }
  },
  "required": [
    "ringNodes",
    "maxChunkSize"
  ]
}

Get Complete Ring
GET`/v1/ring`

This request returns the complete ring, including information about the environment and settings.

GET http://sbox00.databeam.de/v1/ring/node

Responses200

Headers

Content-Type: application/json

Body

{
  "uid": "node1",
  "baseUrl": "http://192.0.2.10:8094/",
  "status": "UNKNOWN"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "uid": {
      "type": "string",
      "description": "The cluster-wide unique ID of the node. No whitespace allowed."
    },
    "baseUrl": {
      "type": "string",
      "description": "The URL where the ring node is listening for requests."
    },
    "status": {
      "type": "string",
      "enum": [
        "UNKNOWN",
        "DOWN",
        "ACTIVE",
        "DRAINING",
        "DRAINING_DOWN",
        "JOINING",
        "JOINING_DOWN"
      ],
      "description": "Status of the ring node."
    }
  },
  "required": [
    "uid",
    "baseUrl"
  ]
}

Get Node Status
GET`/v1/ring/node`

As part of a health-check, client can query each ring node for their status.

GET http://sbox00.databeam.de/v1/ring/locate/spaces01/8q_1n5vacqan910c/hd3sdliih15pbfdy7n6f

Responses200

Headers

Content-Type: application/json

Body

{
  "ringNodes": [
    {
      "uid": "node1",
      "baseUrl": "http://192.0.2.10:8094/",
      "status": "UNKNOWN"
    }
  ],
  "maxChunkSize": 4000000
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "ringNodes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "uid": {
            "type": "string",
            "enum": [
              "node1"
            ],
            "description": "The cluster-wide unique ID of the node. No whitespace allowed."
          },
          "baseUrl": {
            "type": "string",
            "enum": [
              "http://192.0.2.10:8094/"
            ],
            "description": "The URL where the ring node is listening for requests."
          },
          "status": {
            "type": "string",
            "enum": [
              "UNKNOWN",
              "DOWN",
              "ACTIVE",
              "DRAINING",
              "DRAINING_DOWN",
              "JOINING",
              "JOINING_DOWN"
            ],
            "description": "Status of the ring node."
          }
        },
        "required": [
          "uid",
          "baseUrl",
          "status"
        ],
        "additionalProperties": false
      },
      "description": "The list of ring nodes matching the request."
    },
    "maxChunkSize": {
      "type": "number",
      "description": "Max allows size of chunks in Bytes."
    }
  },
  "required": [
    "ringNodes",
    "maxChunkSize"
  ]
}

Locate Chunk
GET`/v1/ring/locate/{tenantUid}/{containerUid}/{chunkUid}`

Clients that did not implement the hash-ring themselves can query a ring node to lookup the ring nodes matching a chunk address.

URI Parameters

HideShow

tenantUid: string (required) Example: spaces01
The UID of the registered tenant
containerUid: string (required) Example: 8q_1n5vacqan910c
The UID of the containter
chunkUid: string (required) Example: hd3sdliih15pbfdy7n6f
The UID of the chunk

Container ¶

Container List ¶

GET http://sbox00.databeam.de/v1/store/spaces01/containers

Responses200403

List of container UIDs is being returned.

Headers

Content-Type: text/plain

Body

8q_1n5vacqan910c
y4d5u63nkfkyg3sj
5f5xhn7kmhlqc2fu
...
z9rkpar2qr46f_8y
20l.yvyekpb6d7tk

The tenant does not exist.

Headers

Content-Type: application/json

Body

{
  "error": {
    "code": 0,
    "message": "This request is forbidden.",
    "details": [
      "Hello, world!"
    ]
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "number",
          "description": "The error code"
        },
        "message": {
          "type": "string",
          "description": "English error message."
        },
        "details": {
          "type": "array",
          "description": "English details to error."
        }
      }
    }
  }
}

List all containers
GET`/v1/store/{tenantUid}/containers`

Returns a streaming list of all containers belonging to the given tenant.

URI Parameters

HideShow

tenantUid: string (required) Example: spaces01
The UID of the registered tenant

Container Management ¶

POST http://sbox00.databeam.de/v1/store/spaces01/containers/8q_1n5vacqan910c

Requestsexample 1

Headers

Content-Type: application/json

Body

{
  "name": "screenshot.png",
  "mimeType": "image/png"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "An optional filename or reference name."
    },
    "mimeType": {
      "type": "string",
      "description": "An optional mimeType of the object."
    }
  }
}

Responses201403409

The container has been created.

Headers

Content-Type: application/json
Location: /v1/store/spaces01/containers/8q_1n5vacqan910c

Body

{
  "name": "screenshot.png",
  "mimeType": "image/png",
  "uid": "8q_1n5vacqan910c",
  "size": 0,
  "blocked": false
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "An optional filename or reference name."
    },
    "mimeType": {
      "type": "string",
      "description": "An optional mimeType of the object."
    },
    "uid": {
      "type": "string",
      "description": "The tenant-unique ID of the container. No whitespace allowed."
    },
    "size": {
      "type": "number",
      "description": "The size of the payload stored in this container, in Bytes."
    },
    "blocked": {
      "type": "boolean",
      "description": "The value of the `blocked` status."
    }
  },
  "required": [
    "uid",
    "size",
    "blocked"
  ]
}

The tenant does not exist.

Headers

Content-Type: application/json

Body

{
  "error": {
    "code": 0,
    "message": "This request is forbidden.",
    "details": [
      "Hello, world!"
    ]
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "number",
          "description": "The error code"
        },
        "message": {
          "type": "string",
          "description": "English error message."
        },
        "details": {
          "type": "array",
          "description": "English details to error."
        }
      }
    }
  }
}

The container UID is in use already.

Headers

Content-Type: application/json

Body

{
  "error": {
    "code": 0,
    "message": "The data could not be stored.",
    "details": [
      "Hello, world!"
    ]
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "number",
          "description": "The error code"
        },
        "message": {
          "type": "string",
          "description": "English error message."
        },
        "details": {
          "type": "array",
          "description": "English details to error."
        }
      }
    }
  }
}

Create container
POST`/v1/store/{tenantUid}/containers/{containerUid}`

Creates a new container with optional metadata.

Note: this request is not strictly necessary. Containers will also get auto-created upon upload of first chunk.

URI Parameters

HideShow

tenantUid: string (required) Example: spaces01
The UID of the registered tenant
containerUid: string (required) Example: 8q_1n5vacqan910c
The UID of the container

HEAD http://sbox00.databeam.de/v1/store/spaces01/containers/8q_1n5vacqan910c

Responses200403404

The container exists.

The tenant does not exist.

Headers

Content-Type: application/json

Body

{
  "error": {
    "code": 0,
    "message": "This request is forbidden.",
    "details": [
      "Hello, world!"
    ]
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "number",
          "description": "The error code"
        },
        "message": {
          "type": "string",
          "description": "English error message."
        },
        "details": {
          "type": "array",
          "description": "English details to error."
        }
      }
    }
  }
}

The container does not exist.

Container exists
HEAD`/v1/store/{tenantUid}/containers/{containerUid}`

Checks if a container exists.

URI Parameters

HideShow

tenantUid: string (required) Example: spaces01
The UID of the registered tenant
containerUid: string (required) Example: 8q_1n5vacqan910c
The UID of the container

GET http://sbox00.databeam.de/v1/store/spaces01/containers/8q_1n5vacqan910c

Responses200403404

Headers

Content-Type: application/json

Body

{
  "name": "screenshot.png",
  "mimeType": "image/png",
  "uid": "8q_1n5vacqan910c",
  "size": 2960364,
  "blocked": false
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "An optional filename or reference name."
    },
    "mimeType": {
      "type": "string",
      "description": "An optional mimeType of the object."
    },
    "uid": {
      "type": "string",
      "description": "The tenant-unique ID of the container. No whitespace allowed."
    },
    "size": {
      "type": "number",
      "description": "The size of the payload stored in this container, in Bytes."
    },
    "blocked": {
      "type": "boolean",
      "description": "The value of the `blocked` status."
    }
  },
  "required": [
    "uid",
    "size",
    "blocked"
  ]
}

The tenant does not exist.

Headers

Content-Type: application/json

Body

{
  "error": {
    "code": 0,
    "message": "This request is forbidden.",
    "details": [
      "Hello, world!"
    ]
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "number",
          "description": "The error code"
        },
        "message": {
          "type": "string",
          "description": "English error message."
        },
        "details": {
          "type": "array",
          "description": "English details to error."
        }
      }
    }
  }
}

The tcontainer does not exist.

Headers

Content-Type: application/json

Body

{
  "error": {
    "code": 0,
    "message": "The requested object does not exist.",
    "details": [
      "Hello, world!"
    ]
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "number",
          "description": "The error code"
        },
        "message": {
          "type": "string",
          "description": "English error message."
        },
        "details": {
          "type": "array",
          "description": "English details to error."
        }
      }
    }
  }
}

Get container metadata
GET`/v1/store/{tenantUid}/containers/{containerUid}`

Fetches the metadata of a container.

URI Parameters

HideShow

tenantUid: string (required) Example: spaces01
The UID of the registered tenant
containerUid: string (required) Example: 8q_1n5vacqan910c
The UID of the container

PUT http://sbox00.databeam.de/v1/store/spaces01/containers/8q_1n5vacqan910c

Requestsexample 1

Headers

Content-Type: application/json

Body

{
  "name": "screenshot.png",
  "mimeType": "image/png"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "An optional filename or reference name."
    },
    "mimeType": {
      "type": "string",
      "description": "An optional mimeType of the object."
    }
  }
}

Responses200403404409

Headers

Content-Type: application/json

Body

{
  "name": "screenshot.png",
  "mimeType": "image/png",
  "uid": "8q_1n5vacqan910c",
  "size": 2960364,
  "blocked": false
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "An optional filename or reference name."
    },
    "mimeType": {
      "type": "string",
      "description": "An optional mimeType of the object."
    },
    "uid": {
      "type": "string",
      "description": "The tenant-unique ID of the container. No whitespace allowed."
    },
    "size": {
      "type": "number",
      "description": "The size of the payload stored in this container, in Bytes."
    },
    "blocked": {
      "type": "boolean",
      "description": "The value of the `blocked` status."
    }
  },
  "required": [
    "uid",
    "size",
    "blocked"
  ]
}

The tenant does not exist.

Headers

Content-Type: application/json

Body

{
  "error": {
    "code": 0,
    "message": "This request is forbidden.",
    "details": [
      "Hello, world!"
    ]
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "number",
          "description": "The error code"
        },
        "message": {
          "type": "string",
          "description": "English error message."
        },
        "details": {
          "type": "array",
          "description": "English details to error."
        }
      }
    }
  }
}

The container does not exist.

Headers

Content-Type: application/json

Body

{
  "error": {
    "code": 0,
    "message": "The requested object does not exist.",
    "details": [
      "Hello, world!"
    ]
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "number",
          "description": "The error code"
        },
        "message": {
          "type": "string",
          "description": "English error message."
        },
        "details": {
          "type": "array",
          "description": "English details to error."
        }
      }
    }
  }
}

A database error occured.

Headers

Content-Type: application/json

Body

{
  "error": {
    "code": 0,
    "message": "The data could not be stored.",
    "details": [
      "Hello, world!"
    ]
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "number",
          "description": "The error code"
        },
        "message": {
          "type": "string",
          "description": "English error message."
        },
        "details": {
          "type": "array",
          "description": "English details to error."
        }
      }
    }
  }
}

Update container metadata
PUT`/v1/store/{tenantUid}/containers/{containerUid}`

Updates the metadata of the container.

URI Parameters

HideShow

tenantUid: string (required) Example: spaces01
The UID of the registered tenant
containerUid: string (required) Example: 8q_1n5vacqan910c
The UID of the container

DELETE http://sbox00.databeam.de/v1/store/spaces01/containers/8q_1n5vacqan910c

Responses204403409

The container has been deleted.

The tenant does not exist.

Headers

Content-Type: application/json

Body

{
  "error": {
    "code": 0,
    "message": "This request is forbidden.",
    "details": [
      "Hello, world!"
    ]
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "number",
          "description": "The error code"
        },
        "message": {
          "type": "string",
          "description": "English error message."
        },
        "details": {
          "type": "array",
          "description": "English details to error."
        }
      }
    }
  }
}

A database error occured.

Headers

Content-Type: application/json

Body

{
  "error": {
    "code": 0,
    "message": "The data could not be stored.",
    "details": [
      "Hello, world!"
    ]
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "number",
          "description": "The error code"
        },
        "message": {
          "type": "string",
          "description": "English error message."
        },
        "details": {
          "type": "array",
          "description": "English details to error."
        }
      }
    }
  }
}

Delete container including payload
DELETE`/v1/store/{tenantUid}/containers/{containerUid}`

Deletes the container and all payload chunks. This operation is not recoverable.

URI Parameters

HideShow

tenantUid: string (required) Example: spaces01
The UID of the registered tenant
containerUid: string (required) Example: 8q_1n5vacqan910c
The UID of the container

Container Blocking ¶

GET http://sbox00.databeam.de/v1/store/spaces01/containers/8q_1n5vacqan910c/blocked

Responses204423403

The container is not blocked or does not exist.

The container is currently blocked.

The tenant does not exist.

Headers

Content-Type: application/json

Body

{
  "error": {
    "code": 0,
    "message": "This request is forbidden.",
    "details": [
      "Hello, world!"
    ]
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "number",
          "description": "The error code"
        },
        "message": {
          "type": "string",
          "description": "English error message."
        },
        "details": {
          "type": "array",
          "description": "English details to error."
        }
      }
    }
  }
}

Is container blocked
GET`/v1/store/{tenantUid}/containers/{containerUid}/blocked`

URI Parameters

HideShow

tenantUid: string (required) Example: spaces01
The UID of the registered tenant
containerUid: string (required) Example: 8q_1n5vacqan910c
The UID of the container

POST http://sbox00.databeam.de/v1/store/spaces01/containers/8q_1n5vacqan910c/blocked

Responses204403409

The container has been blocked.

The tenant does not exist.

Headers

Content-Type: application/json

Body

{
  "error": {
    "code": 0,
    "message": "This request is forbidden.",
    "details": [
      "Hello, world!"
    ]
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "number",
          "description": "The error code"
        },
        "message": {
          "type": "string",
          "description": "English error message."
        },
        "details": {
          "type": "array",
          "description": "English details to error."
        }
      }
    }
  }
}

A database error occured.

Headers

Content-Type: application/json

Body

{
  "error": {
    "code": 0,
    "message": "The data could not be stored.",
    "details": [
      "Hello, world!"
    ]
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "number",
          "description": "The error code"
        },
        "message": {
          "type": "string",
          "description": "English error message."
        },
        "details": {
          "type": "array",
          "description": "English details to error."
        }
      }
    }
  }
}

Block container
POST`/v1/store/{tenantUid}/containers/{containerUid}/blocked`

Note: If the container does not exist, it is automatically created before marking it as blocked…

URI Parameters

HideShow

tenantUid: string (required) Example: spaces01
The UID of the registered tenant
containerUid: string (required) Example: 8q_1n5vacqan910c
The UID of the container

DELETE http://sbox00.databeam.de/v1/store/spaces01/containers/8q_1n5vacqan910c/blocked

Responses204403409

The container has been unblocked or it does not exist.

The tenant does not exist.

Headers

Content-Type: application/json

Body

{
  "error": {
    "code": 0,
    "message": "This request is forbidden.",
    "details": [
      "Hello, world!"
    ]
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "number",
          "description": "The error code"
        },
        "message": {
          "type": "string",
          "description": "English error message."
        },
        "details": {
          "type": "array",
          "description": "English details to error."
        }
      }
    }
  }
}

A database error occured.

Headers

Content-Type: application/json

Body

{
  "error": {
    "code": 0,
    "message": "The data could not be stored.",
    "details": [
      "Hello, world!"
    ]
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "number",
          "description": "The error code"
        },
        "message": {
          "type": "string",
          "description": "English error message."
        },
        "details": {
          "type": "array",
          "description": "English details to error."
        }
      }
    }
  }
}

Unblock container
DELETE`/v1/store/{tenantUid}/containers/{containerUid}/blocked`

URI Parameters

HideShow

tenantUid: string (required) Example: spaces01
The UID of the registered tenant
containerUid: string (required) Example: 8q_1n5vacqan910c
The UID of the container

Chunk ¶

Chunk Matching ¶

GET http://sbox00.databeam.de/v1/store/spaces01/containers/8q_1n5vacqan910c/chunks

Requestsexample 1

Headers

Range: bytes=500-999

Responses200403404416

Headers

Content-Type: application/json

Body

{
  "chunks": [
    {
      "uid": "e2m73840udxsa84gx9f7",
      "start": 500,
      "end": 1000
    }
  ]
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "chunks": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "uid": {
            "type": "string",
            "enum": [
              "e2m73840udxsa84gx9f7"
            ],
            "description": "The container-unique ID of the chunk. No whitespace allowed."
          },
          "start": {
            "type": "number",
            "enum": [
              500
            ],
            "description": "Address of first Byte of this chunk in the context of the container."
          },
          "end": {
            "type": "number",
            "enum": [
              1000
            ],
            "description": "Address of the last Byte of this chunk in the context of the container."
          }
        },
        "required": [
          "uid",
          "start",
          "end"
        ],
        "additionalProperties": false
      },
      "description": "List of chunks of the container."
    }
  },
  "required": [
    "chunks"
  ]
}

The tenant does not exist.

Headers

Content-Type: application/json

Body

{
  "error": {
    "code": 0,
    "message": "This request is forbidden.",
    "details": [
      "Hello, world!"
    ]
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "number",
          "description": "The error code"
        },
        "message": {
          "type": "string",
          "description": "English error message."
        },
        "details": {
          "type": "array",
          "description": "English details to error."
        }
      }
    }
  }
}

The container does not exist.

Headers

Content-Type: application/json

Body

{
  "error": {
    "code": 0,
    "message": "The requested object does not exist.",
    "details": [
      "Hello, world!"
    ]
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "number",
          "description": "The error code"
        },
        "message": {
          "type": "string",
          "description": "English error message."
        },
        "details": {
          "type": "array",
          "description": "English details to error."
        }
      }
    }
  }
}

The requested range cannot be satisfied.

Headers

Content-Type: application/json

Body

{
  "error": {
    "code": 0,
    "message": "The requested range could not be statisfied.",
    "details": [
      "Hello, world!"
    ]
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "number",
          "description": "The error code"
        },
        "message": {
          "type": "string",
          "description": "English error message."
        },
        "details": {
          "type": "array",
          "description": "English details to error."
        }
      }
    }
  }
}

Get list of chunks
GET`/v1/store/{tenantUid}/containers/{containerUid}/chunks`

Returns the list of chunk UIDs of the container, matching the requested range.

URI Parameters

HideShow

tenantUid: string (required) Example: spaces01
The UID of the registered tenant
containerUid: string (required) Example: 8q_1n5vacqan910c
The UID of the container

Chunk Management ¶

POST http://sbox00.databeam.de/v1/store/spaces01/containers/8q_1n5vacqan910c/chunks/e2m73840udxsa84gx9f7

Requestsexample 1

Headers

Content-Range: 500-999/1000

Body

{.. payload ..}

Responses200400403404409

The chunk has been uploaded.

Headers

Content-Type: application/json

Body

{
  "uid": "e2m73840udxsa84gx9f7",
  "start": 500,
  "end": 1000
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "uid": {
      "type": "string",
      "description": "The container-unique ID of the chunk. No whitespace allowed."
    },
    "start": {
      "type": "number",
      "description": "Address of first Byte of this chunk in the context of the container."
    },
    "end": {
      "type": "number",
      "description": "Address of the last Byte of this chunk in the context of the container."
    }
  },
  "required": [
    "uid",
    "start",
    "end"
  ]
}

Headers are missing or cannot be parsed.

Headers

Content-Type: application/json

Body

{
  "error": {
    "code": 0,
    "message": "The request cannot be fulfilled.",
    "details": [
      "Hello, world!"
    ]
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "number",
          "description": "The error code"
        },
        "message": {
          "type": "string",
          "description": "English error message."
        },
        "details": {
          "type": "array",
          "description": "English details to error."
        }
      }
    }
  }
}

The tenant does not exist.

Headers

Content-Type: application/json

Body

{
  "error": {
    "code": 0,
    "message": "This request is forbidden.",
    "details": [
      "Hello, world!"
    ]
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "number",
          "description": "The error code"
        },
        "message": {
          "type": "string",
          "description": "English error message."
        },
        "details": {
          "type": "array",
          "description": "English details to error."
        }
      }
    }
  }
}

The container does not exist.

Headers

Content-Type: application/json

Body

{
  "error": {
    "code": 0,
    "message": "The requested object does not exist.",
    "details": [
      "Hello, world!"
    ]
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "number",
          "description": "The error code"
        },
        "message": {
          "type": "string",
          "description": "English error message."
        },
        "details": {
          "type": "array",
          "description": "English details to error."
        }
      }
    }
  }
}

The chunkUid is in use already.

Headers

Content-Type: application/json

Body

{
  "error": {
    "code": 0,
    "message": "The data could not be stored.",
    "details": [
      "Hello, world!"
    ]
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "number",
          "description": "The error code"
        },
        "message": {
          "type": "string",
          "description": "English error message."
        },
        "details": {
          "type": "array",
          "description": "English details to error."
        }
      }
    }
  }
}

Upload new chunk
POST`/v1/store/{tenantUid}/containers/{containerUid}/chunks/{chunkUid}`

Uploads a new chunk with the given range. The chunkUid must not be used yet.

URI Parameters

HideShow

tenantUid: string (required) Example: spaces01
The UID of the registered tenant
containerUid: string (required) Example: 8q_1n5vacqan910c
The UID of the container
chunkUid: string (required) Example: e2m73840udxsa84gx9f7
The UID of the chunk

PUT http://sbox00.databeam.de/v1/store/spaces01/containers/8q_1n5vacqan910c/chunks/e2m73840udxsa84gx9f7

Requestsexample 1

Headers

Content-Range: 500-999/1000

Body

{.. payload ..}

Responses200400403404409

The chunk has been uploaded.

Headers

Content-Type: application/json

Body

{
  "uid": "e2m73840udxsa84gx9f7",
  "start": 500,
  "end": 1000
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "uid": {
      "type": "string",
      "description": "The container-unique ID of the chunk. No whitespace allowed."
    },
    "start": {
      "type": "number",
      "description": "Address of first Byte of this chunk in the context of the container."
    },
    "end": {
      "type": "number",
      "description": "Address of the last Byte of this chunk in the context of the container."
    }
  },
  "required": [
    "uid",
    "start",
    "end"
  ]
}

Headers are missing or cannot be parsed.

Headers

Content-Type: application/json

Body

{
  "error": {
    "code": 0,
    "message": "The request cannot be fulfilled.",
    "details": [
      "Hello, world!"
    ]
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "number",
          "description": "The error code"
        },
        "message": {
          "type": "string",
          "description": "English error message."
        },
        "details": {
          "type": "array",
          "description": "English details to error."
        }
      }
    }
  }
}

The tenant does not exist.

Headers

Content-Type: application/json

Body

{
  "error": {
    "code": 0,
    "message": "This request is forbidden.",
    "details": [
      "Hello, world!"
    ]
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "number",
          "description": "The error code"
        },
        "message": {
          "type": "string",
          "description": "English error message."
        },
        "details": {
          "type": "array",
          "description": "English details to error."
        }
      }
    }
  }
}

The container or chunk does not exist.

Headers

Content-Type: application/json

Body

{
  "error": {
    "code": 0,
    "message": "The requested object does not exist.",
    "details": [
      "Hello, world!"
    ]
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "number",
          "description": "The error code"
        },
        "message": {
          "type": "string",
          "description": "English error message."
        },
        "details": {
          "type": "array",
          "description": "English details to error."
        }
      }
    }
  }
}

Possible reasons: The ring node is not responsible for the chunk. The replication was not sucessful due to checksum mismatch. A database error occured.

Headers

Content-Type: application/json

Body

{
  "error": {
    "code": 0,
    "message": "The data could not be stored.",
    "details": [
      "Hello, world!"
    ]
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "number",
          "description": "The error code"
        },
        "message": {
          "type": "string",
          "description": "English error message."
        },
        "details": {
          "type": "array",
          "description": "English details to error."
        }
      }
    }
  }
}

Replicate chunk
PUT`/v1/store/{tenantUid}/containers/{containerUid}/chunks/{chunkUid}`

Transfers the payload of a chunk to a ring node for replication purposes. The chunk must already exist in the database.

Note: This request is intended for store-to-store communication only. It is not required or even recommended for clients to implement this request.

URI Parameters

HideShow

tenantUid: string (required) Example: spaces01
The UID of the registered tenant
containerUid: string (required) Example: 8q_1n5vacqan910c
The UID of the container
chunkUid: string (required) Example: e2m73840udxsa84gx9f7
The UID of the chunk

GET http://sbox00.databeam.de/v1/store/spaces01/containers/8q_1n5vacqan910c/chunks/e2m73840udxsa84gx9f7?readrepair=true

Requestsexample 1

The optional range is relative to the start of the chunk, not its position in the stream or container.

Headers

Range: bytes=100-199

Responses200303403404409

The chunk, or requested range thereof, is returned.

Headers

Content-Type: application/octet-stream

Body

{.. payload ..}

The ring node is not responsible for the chunk. An alternative location is being suggested.

Headers

Location: http://192.2.0.20:8094/v1/store/spaces01/containers/8q_1n5vacqan910c/chunks/e2m73840udxsa84gx9f7

The tenant does not exist.

Headers

Content-Type: application/json

Body

{
  "error": {
    "code": 0,
    "message": "This request is forbidden.",
    "details": [
      "Hello, world!"
    ]
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "number",
          "description": "The error code"
        },
        "message": {
          "type": "string",
          "description": "English error message."
        },
        "details": {
          "type": "array",
          "description": "English details to error."
        }
      }
    }
  }
}

The container or chunk does not exist.

Headers

Content-Type: application/json

Body

{
  "error": {
    "code": 0,
    "message": "The requested object does not exist.",
    "details": [
      "Hello, world!"
    ]
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "number",
          "description": "The error code"
        },
        "message": {
          "type": "string",
          "description": "English error message."
        },
        "details": {
          "type": "array",
          "description": "English details to error."
        }
      }
    }
  }
}

The chunk is not available, although it should be. The client should retry the request at other ring nodes. If readrepair is true, the ring node will attempt to replicate the chunk to itself.

Headers

Content-Type: application/json

Body

{
  "error": {
    "code": 0,
    "message": "The data could not be stored.",
    "details": [
      "Hello, world!"
    ]
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "number",
          "description": "The error code"
        },
        "message": {
          "type": "string",
          "description": "English error message."
        },
        "details": {
          "type": "array",
          "description": "English details to error."
        }
      }
    }
  }
}

Download chunk
GET`/v1/store/{tenantUid}/containers/{containerUid}/chunks/{chunkUid}?readrepair={readrepair}`

Requests the payload of a chunk. If the ring node is not responsible for the chunk, the response will suggest a different location.

The request can be specified with an optional range, returning only the requested section of the chunk.

URI Parameters

HideShow

tenantUid: string (required) Example: spaces01
The UID of the registered tenant
containerUid: string (required) Example: 8q_1n5vacqan910c
The UID of the container
chunkUid: string (required) Example: e2m73840udxsa84gx9f7
The UID of the chunk
readrepair: boolean (optional) Example: true
If true, instructs the ring node to trigger self-replication for missing chunks. Default true.

HEAD http://sbox00.databeam.de/v1/store/spaces01/containers/8q_1n5vacqan910c/chunks/e2m73840udxsa84gx9f7?readrepair=true

Responses200303403404409

The chunk exists at the requested location.

The ring node is not responsible for the chunk. An alternative location is being suggested.

Headers

Location: http://192.2.0.20:8094/v1/store/spaces01/containers/8q_1n5vacqan910c/chunks/e2m73840udxsa84gx9f7

The tenant does not exist.

The container or chunk does not exist.

The chunk is not available, although it should be. If readrepair is true, the ring node will attempt to replicate the chunk to itself.

Chunk exists
HEAD`/v1/store/{tenantUid}/containers/{containerUid}/chunks/{chunkUid}?readrepair={readrepair}`

Checks if the requested chunk exists at this location. If the ring node is not responsible for the chunk, the response will suggest a different location.

URI Parameters

HideShow

tenantUid: string (required) Example: spaces01
The UID of the registered tenant
containerUid: string (required) Example: 8q_1n5vacqan910c
The UID of the container
chunkUid: string (required) Example: e2m73840udxsa84gx9f7
The UID of the chunk
readrepair: boolean (optional) Example: true
If true, instructs the ring node to trigger self-replication for missing chunks. Default true.

Maintenance ¶

Healthcheck ¶

GET http://sbox00.databeam.de/healthcheck

Responses204404

The server is in normal operation state.

The server is in maintenance mode.

Check node status
GET`/healthcheck`

Checks if the server is normal operation state. Typically used by monitoring applications or reverse proxies.

Configuration ¶

GET http://sbox00.databeam.de/config

Responses200

Headers

Content-Type: application/json

Body

{
  "jdbc.password": "....",
  "http.jmxEnabled": "false",
  "http.accessLogFormat": "%a %t \"%r\" %s (%D)",
  "jdbc.user": "strongbox",
  "http.maintenanceUri": "http://0.0.0.0:9999/",
  "http.accessLogEnabled": "false",
  "http.documentRoot": "/var/www",
  "messageBroker.url": "failover:(tcp://localhost:61616)?startupMaxReconnectAttempts=3",
  "http.allowCorsForAllRequests": "false",
  "jdbc.url": "jdbc:mysql://localhost:3306/strongbox",
  "http.accessLogFile": "/var/log/skp/server.access.log",
  "loadTimestamp": "1620292801172",
  "feature.checksumType": "adler32",
  "sfs.enabled": "true",
  "sfs.baseDir": "/srv/sfs/strongbox/data",
  "http.baseUri": "http://10.35.8.124:8094/",
  "jdbc.schedulerUrl": "jdbc:mysql://localhost:3306/strongbox",
  "feature.pushReplicationThreadPoolSize": "12",
  "messageBroker.destinationPrefix": "com.skalio.strongbox",
  "feature.backgroundOperationThreadPoolSize": "4",
  "node.uid": "store1",
  "sfs.chunkSize": "4194304",
  "sfs.minimumAvailableDiskspaceMB": "1000"
}

List current configuration
GET`/config`

Returns the current loaded configuration as key-value pairs.

POST http://sbox00.databeam.de/config/reload

Responses204

The configuration has been loaded.

Reload configuration
POST`/config/reload`

Triggers the server to reload its configuration from the config files.

Maintenance ¶

Manages the maintenance mode of the server.

GET http://sbox00.databeam.de/maintenance

Responses200

Headers

Content-Type: text/plain

Body

"STARTING_UP"

Schema

{
  "enum": [
    "STARTING_UP",
    "ADMIN_MAINTENANCE",
    "FORCED_MAINTENANCE",
    "NORMAL_OPERATION",
    "SHUTTING_DOWN"
  ],
  "$schema": "http://json-schema.org/draft-04/schema#"
}

Get status
GET`/maintenance`

Returns the current maintenance status.

POST http://sbox00.databeam.de/maintenance/enable

Responses204

This response has no content.

Enable maintenance
POST`/maintenance/enable`

Attempts to switch the server into maintenance mode.

POST http://sbox00.databeam.de/maintenance/disable

Responses204

This response has no content.

Disable maintenance
POST`/maintenance/disable`

Attempts to switch the server into maintenance mode.

Metrics ¶

Endpoint for Prometheus integration.

GET http://sbox00.databeam.de/metrics

Responses200

Headers

Content-Type: text/plain;charset=utf-8;version=0.0.4

Body

# HELP skp_uptime_seconds_total Uptime in seconds
# TYPE skp_uptime_seconds_total counter
skp_uptime_seconds_total{program="strongbox-store",} 691309.0
# HELP strongbox_requests_inprogress Number of requests currently in progress.
# TYPE strongbox_requests_inprogress gauge
strongbox_requests_inprogress{type="upload",} 0.0
strongbox_requests_inprogress{type="download",} 0.0
strongbox_requests_inprogress{type="replicateChunk",} 0.0

Fetch metrics
GET`/metrics`

Returns the current metrics for import into Prometheus.

Generated by aglio on 06 Mar 2024

API Endpoint

Getting Started ¶

Transport ¶

Authorization ¶

Rate Limiting ¶

API Deprecation ¶

Payload format ¶

Error handling ¶

Ring ¶

Ring Environment ¶

Headers

Body

Schema

Get Complete RingGET/v1/ring

Headers

Body

Schema

Get Node StatusGET/v1/ring/node

Headers

Body

Schema

Locate ChunkGET/v1/ring/locate/{tenantUid}/{containerUid}/{chunkUid}

Container ¶

Container List ¶

Headers

Body

Headers

Body

Schema

List all containersGET/v1/store/{tenantUid}/containers

Container Management ¶

Headers

Body

Schema

Headers

Body

Schema

Headers

Body

Schema

Headers

Body

Schema

Create containerPOST/v1/store/{tenantUid}/containers/{containerUid}

Headers

Body

Schema

Container existsHEAD/v1/store/{tenantUid}/containers/{containerUid}

Headers

Body

Schema

Headers

Body

Schema

Headers

Body

Schema

Get container metadataGET/v1/store/{tenantUid}/containers/{containerUid}

Headers

Body

Schema

Headers

Body

Schema

Headers

Body

Schema

Headers

Body

Schema

Headers

Body

Schema

Update container metadataPUT/v1/store/{tenantUid}/containers/{containerUid}

Headers

Body

Schema

Headers

Body

Schema

Get Complete Ring
GET`/v1/ring`

Get Node Status
GET`/v1/ring/node`

Locate Chunk
GET`/v1/ring/locate/{tenantUid}/{containerUid}/{chunkUid}`

List all containers
GET`/v1/store/{tenantUid}/containers`

Create container
POST`/v1/store/{tenantUid}/containers/{containerUid}`

Container exists
HEAD`/v1/store/{tenantUid}/containers/{containerUid}`

Get container metadata
GET`/v1/store/{tenantUid}/containers/{containerUid}`

Update container metadata
PUT`/v1/store/{tenantUid}/containers/{containerUid}`

Delete container including payload
DELETE`/v1/store/{tenantUid}/containers/{containerUid}`

Is container blocked
GET`/v1/store/{tenantUid}/containers/{containerUid}/blocked`

Block container
POST`/v1/store/{tenantUid}/containers/{containerUid}/blocked`

Unblock container
DELETE`/v1/store/{tenantUid}/containers/{containerUid}/blocked`

Get list of chunks
GET`/v1/store/{tenantUid}/containers/{containerUid}/chunks`

Upload new chunk
POST`/v1/store/{tenantUid}/containers/{containerUid}/chunks/{chunkUid}`