Zum Inhalt springen
NimbusNexus

Objektspeicher

Der Objektspeicher von NimbusNexus legt Dateien als Objekte in Containern ab, die zu Ihrem Projekt gehören. Beides verwalten Sie über /api/v1/object_storage/, mit denselben Credentials wie die übrige API.

Container

POST /api/v1/object_storage/ erstellt einen Container. Setzen Sie public_read: true, damit jeder einzelne Objekte lesen kann, deren URL er kennt, und fügen Sie public_listing: true hinzu, damit jeder auch den Inhalt des Containers auflisten kann; auf public_listing ohne public_read antwortet die API mit 400. Auf einen Namen, den es schon gibt, antwortet sie mit 409.

GET /api/v1/object_storage/ listet Ihre Container mit bytes und count auf. PATCH /api/v1/object_storage/{container_name} aktualisiert die Metadaten eines Containers, und DELETE /api/v1/object_storage/{container_name} löscht einen leeren Container; auf einen Container, der noch Objekte enthält, antwortet die API mit 409.

Container-Namen

Ein Container-Name besteht aus 3–63 Kleinbuchstaben, Ziffern und Bindestrichen und beginnt und endet mit einem Buchstaben oder einer Ziffer. Unterstriche, Punkte und Leerzeichen sind nicht erlaubt, ebenso wenig ein Name im Format einer IP-Adresse.

Objekte

  • POST /api/v1/object_storage/{container_name}/objects lädt ein neues Objekt als Multipart-Feld file hoch, benannt nach object_name oder, wenn dieser fehlt, nach der Datei. Auf einen Namen, den es schon gibt, antwortet die API mit 409.
  • PUT /api/v1/object_storage/{container_name}/objects/{object_name}/content ersetzt den Inhalt eines Objekts.
  • GET /api/v1/object_storage/{container_name}/objects/{object_name}/content lädt es herunter: Text als UTF-8, binäre Inhalte base64-kodiert.
  • GET und PATCH /api/v1/object_storage/{container_name}/objects/{object_name} lesen und aktualisieren seine Metadaten, und DELETE auf demselben Pfad löscht es.
  • POST /api/v1/object_storage/{container_name}/objects/{object_name}/copy und /move kopieren oder verschieben es unter einen neuen Namen oder in einen anderen Container.

Ein Objektname kann / enthalten; das wird als Ordnerpfad gelesen.

Auflisten und Paginierung

GET /api/v1/object_storage/{container_name}/objects listet die Objekte eines Containers auf. Paginieren Sie mit limit und marker (dem letzten Namen, den Sie gesehen haben), oder setzen Sie full_listing=true, um alle in einer Antwort zu erhalten. prefix behält nur die Namen, die damit beginnen.

Übergeben Sie delimiter=/ für eine Auflistung im Ordnerstil: Die Objekte auf dieser Ebene kommen in objects zurück, die Präfixe eine Ebene tiefer in subdirs.

Kurzlebige Credentials

POST /api/v1/object_storage/credentials stellt ein kurzlebiges, projektgebundenes Credential für das Projekt aus, für das Ihre Sitzung gilt, und gibt seine trust_id und sein expires_at zurück. Eine Lebensdauer können Sie mit ttl_seconds anfragen; der Server begrenzt sie. Ein eigenständiger Editor sendet die trust_id bei späteren Aufrufen an den Objektspeicher im Header X-Trust-Id und erreicht so den Speicher des Projekts, ohne Ihr vollständiges Token oder ein dauerhaftes Secret zu halten; jeder Aufruf authentifiziert sich trotzdem wie gewohnt. DELETE /api/v1/object_storage/credentials/{trust_id} widerruft es.

Nächste Schritte

  • Authentifizierung — API-Keys gehören in den Header X-API-Key.
  • Blockspeicher — wenn Sie ein Dateisystem statt eines Key-Value-Stores wollen oder POSIX-Semantik brauchen.
  • Mosaic-Editor — browserbasierter Editor für YAML-/JSON-/Markdown-Dateien in Ihren Containern.

Reference

GET/api/v1/object_storage/

List Containers

Lists the containers owned by the calling project together with their size and object counts.

Parameters

NameInTypeDescription
limitqueryinteger | nullMaximum number of containers to return
markerquerystring | nullMarker for pagination
end_markerquerystring | nullEnd marker for pagination
prefixquerystring | nullFilter containers by prefix

Responses

  • 200Successful Response
  • 400Bad Request
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflict
  • 422Validation error
  • 429Too Many Requests
  • 500Internal Server Error

Example

curl -X GET "https://api.nimbusnexus.net/api/v1/object_storage/" \
  -H "Authorization: Bearer $NIMBUS_KEY"
POST/api/v1/object_storage/

Create Container

Creates a new object storage container, optionally marking it publicly readable.

Request body

FieldTypeDescription
name*stringContainer name. Lowercase letters, numbers, and hyphens only.
public_readbooleanAllow anyone to read individual objects whose URL they know. Maps to Swift's `X-Container-Read: .r:*`.
public_listingbooleanAllow anyone to list the contents of the container (enumerate object names). Adds `.rlistings` to `X-Container-Read`. Requires `public_read=True` — the API rejects `public_listing` without `public_read` to match the UX convention that listing is a permission you grant on top of read.

Responses

  • 201Successful Response
  • 400Bad Request
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflict
  • 422Validation error
  • 429Too Many Requests
  • 500Internal Server Error

Example

curl -X POST "https://api.nimbusnexus.net/api/v1/object_storage/" \
  -H "Authorization: Bearer $NIMBUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Example"
  }'
POST/api/v1/object_storage/credentials

Mint Storage Credential

Mints a short-lived, project-scoped object-storage credential (a Keystone trust) for the caller's current project and returns its trust_id. A standalone editor presents that id via the X-Trust-Id header on subsequent object-storage calls, reaching this project's storage without holding the user's full token or any durable secret.

Request body

JSON body required.

Responses

  • 201Successful Response
  • 400Bad Request
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflict
  • 422Validation error
  • 429Too Many Requests
  • 500Internal Server Error

Example

curl -X POST "https://api.nimbusnexus.net/api/v1/object_storage/credentials" \
  -H "Authorization: Bearer $NIMBUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
DELETE/api/v1/object_storage/credentials/{trust_id}

Revoke Storage Credential

Revokes a previously minted object-storage credential (trust).

Parameters

NameInTypeDescription
trust_id*pathstring—

Responses

  • 204Successful Response
  • 400Bad Request
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflict
  • 422Validation error
  • 429Too Many Requests
  • 500Internal Server Error

Example

curl -X DELETE "https://api.nimbusnexus.net/api/v1/object_storage/credentials/<trust_id>" \
  -H "Authorization: Bearer $NIMBUS_KEY"
GET/api/v1/object_storage/{container_name}

Get Container Metadata

Returns the metadata headers describing the given container.

Parameters

NameInTypeDescription
container_name*pathstring—

Responses

  • 200Successful Response
  • 400Bad Request
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflict
  • 422Validation error
  • 429Too Many Requests
  • 500Internal Server Error

Example

curl -X GET "https://api.nimbusnexus.net/api/v1/object_storage/<container_name>" \
  -H "Authorization: Bearer $NIMBUS_KEY"
PATCH/api/v1/object_storage/{container_name}

Update Container Metadata

Updates the metadata headers attached to the given container.

Parameters

NameInTypeDescription
container_name*pathstring—

Request body

FieldTypeDescription
admin_domainstring | null—
admin_projectstring | null—
headers*objectMetadata keys (auto-prefixed with X-Container-Meta- if needed).

Responses

  • 200Successful Response
  • 400Bad Request
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflict
  • 422Validation error
  • 429Too Many Requests
  • 500Internal Server Error

Example

curl -X PATCH "https://api.nimbusnexus.net/api/v1/object_storage/<container_name>" \
  -H "Authorization: Bearer $NIMBUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "headers": {
      "environment": "production",
      "owner": "team-a"
    }
  }'
DELETE/api/v1/object_storage/{container_name}

Delete Container

Deletes the named container, rejecting the request if it still holds objects.

Parameters

NameInTypeDescription
container_name*pathstring—

Responses

  • 204Successful Response
  • 400Bad Request
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflict
  • 422Validation error
  • 429Too Many Requests
  • 500Internal Server Error

Example

curl -X DELETE "https://api.nimbusnexus.net/api/v1/object_storage/<container_name>" \
  -H "Authorization: Bearer $NIMBUS_KEY"
GET/api/v1/object_storage/{container_name}/objects

List Objects

Lists the objects stored within the given container.

Parameters

NameInTypeDescription
container_name*pathstring—
limitqueryinteger | nullMaximum number of objects to return
markerquerystring | nullMarker for pagination
end_markerquerystring | nullEnd marker for pagination
prefixquerystring | nullFilter objects by prefix
delimiterquerystring | nullDelimiter for hierarchical listing
version_markerquerystring | nullVersion marker for versioned objects
pathquerystring | nullPath within container
full_listingquerybooleanReturn all objects, paginating automatically
query_stringquerystring | nullAdditional query parameters

Responses

  • 200Successful Response
  • 400Bad Request
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflict
  • 422Validation error
  • 429Too Many Requests
  • 500Internal Server Error

Example

curl -X GET "https://api.nimbusnexus.net/api/v1/object_storage/<container_name>/objects" \
  -H "Authorization: Bearer $NIMBUS_KEY"
POST/api/v1/object_storage/{container_name}/objects

Upload Object

Uploads a new object into the given container from a multipart file upload.

Parameters

NameInTypeDescription
container_name*pathstring—

Request body

JSON body required.

Responses

  • 201Successful Response
  • 400Bad Request
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflict
  • 422Validation error
  • 429Too Many Requests
  • 500Internal Server Error

Example

curl -X POST "https://api.nimbusnexus.net/api/v1/object_storage/<container_name>/objects" \
  -H "Authorization: Bearer $NIMBUS_KEY"
GET/api/v1/object_storage/{container_name}/objects/{object_name}

Get Object Metadata

Returns the metadata headers describing the named object.

Parameters

NameInTypeDescription
container_name*pathstring—
object_name*pathstring—

Responses

  • 200Successful Response
  • 400Bad Request
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflict
  • 422Validation error
  • 429Too Many Requests
  • 500Internal Server Error

Example

curl -X GET "https://api.nimbusnexus.net/api/v1/object_storage/<container_name>/objects/<object_name>" \
  -H "Authorization: Bearer $NIMBUS_KEY"
PATCH/api/v1/object_storage/{container_name}/objects/{object_name}

Update Object Metadata

Updates the metadata headers attached to the named object.

Parameters

NameInTypeDescription
container_name*pathstring—
object_name*pathstring—

Request body

FieldTypeDescription
admin_domainstring | null—
admin_projectstring | null—
headers*objectMetadata keys (auto-prefixed with X-Object-Meta- if needed).

Responses

  • 200Successful Response
  • 400Bad Request
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflict
  • 422Validation error
  • 429Too Many Requests
  • 500Internal Server Error

Example

curl -X PATCH "https://api.nimbusnexus.net/api/v1/object_storage/<container_name>/objects/<object_name>" \
  -H "Authorization: Bearer $NIMBUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "headers": {
      "author": "user",
      "version": "1.0"
    }
  }'
DELETE/api/v1/object_storage/{container_name}/objects/{object_name}

Delete Object

Deletes the named object from its container.

Parameters

NameInTypeDescription
container_name*pathstring—
object_name*pathstring—

Responses

  • 204Successful Response
  • 400Bad Request
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflict
  • 422Validation error
  • 429Too Many Requests
  • 500Internal Server Error

Example

curl -X DELETE "https://api.nimbusnexus.net/api/v1/object_storage/<container_name>/objects/<object_name>" \
  -H "Authorization: Bearer $NIMBUS_KEY"
GET/api/v1/object_storage/{container_name}/objects/{object_name}/content

Get Object Content

Downloads the body of an object, decoding it as UTF-8 text or base64 when binary.

Parameters

NameInTypeDescription
container_name*pathstring—
object_name*pathstring—

Responses

  • 200Successful Response
  • 400Bad Request
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflict
  • 422Validation error
  • 429Too Many Requests
  • 500Internal Server Error

Example

curl -X GET "https://api.nimbusnexus.net/api/v1/object_storage/<container_name>/objects/<object_name>/content" \
  -H "Authorization: Bearer $NIMBUS_KEY"
PUT/api/v1/object_storage/{container_name}/objects/{object_name}/content

Put Object Content

Replaces the body of an existing object at the given path with the uploaded content.

Parameters

NameInTypeDescription
container_name*pathstring—
object_name*pathstring—

Request body

JSON body required.

Responses

  • 200Successful Response
  • 400Bad Request
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflict
  • 422Validation error
  • 429Too Many Requests
  • 500Internal Server Error

Example

curl -X PUT "https://api.nimbusnexus.net/api/v1/object_storage/<container_name>/objects/<object_name>/content" \
  -H "Authorization: Bearer $NIMBUS_KEY"
POST/api/v1/object_storage/{container_name}/objects/{object_name}/copy

Copy Object

Copies an object to a new name or path and returns where the copy landed. destination is relative to the source container; prefix it with '/' to name another container, which alone keeps the source object's name.

Parameters

NameInTypeDescription
container_name*pathstring—
object_name*pathstring—

Request body

FieldTypeDescription
admin_domainstring | null—
admin_projectstring | null—
destination*stringTarget object name/path in the source container; '/container/object_name' targets another container, and '/container' alone keeps the source name.
overwritebooleanWhether to overwrite the destination if it already exists.
fresh_metadatabooleanStart with fresh metadata
headersobject | null—

Responses

  • 201Successful Response
  • 400Bad Request
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflict
  • 422Validation error
  • 429Too Many Requests
  • 500Internal Server Error

Example

curl -X POST "https://api.nimbusnexus.net/api/v1/object_storage/<container_name>/objects/<object_name>/copy" \
  -H "Authorization: Bearer $NIMBUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "copy.jpg"
  }'
POST/api/v1/object_storage/{container_name}/objects/{object_name}/move

Move Object

Moves an object to a new container or name by copying it and deleting the source, and returns where it ended up.

Parameters

NameInTypeDescription
container_name*pathstring—
object_name*pathstring—

Request body

FieldTypeDescription
admin_domainstring | null—
admin_projectstring | null—
destination_containerstring | nullTarget container, without slashes. If omitted, uses the source container.
destination_object_name*stringTarget object name/path. Outer slashes are stripped; inner ones are folders.
overwritebooleanWhether to overwrite the destination if it already exists.

Responses

  • 200Successful Response
  • 400Bad Request
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflict
  • 422Validation error
  • 429Too Many Requests
  • 500Internal Server Error

Example

curl -X POST "https://api.nimbusnexus.net/api/v1/object_storage/<container_name>/objects/<object_name>/move" \
  -H "Authorization: Bearer $NIMBUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination_object_name": "picture1"
  }'

Need to make a real call? Try these endpoints in the live Swagger UI →