Ir para o conteúdo
NimbusNexus

Armazenamento de objetos

O armazenamento de objetos da NimbusNexus guarda arquivos como objetos em contêineres que pertencem ao seu projeto. Você gerencia os dois por /api/v1/object_storage/, com as mesmas credenciais do resto da API.

Contêineres

POST /api/v1/object_storage/ cria um contêiner. Defina public_read: true para deixar qualquer pessoa ler objetos individuais cuja URL ela conheça, e acrescente public_listing: true para deixar qualquer pessoa listar também o conteúdo do contêiner; public_listing sem public_read retorna 400. Um nome que já existe retorna 409.

GET /api/v1/object_storage/ lista os seus contêineres com o bytes e o count de cada um. PATCH /api/v1/object_storage/{container_name} atualiza os metadados de um contêiner, e DELETE /api/v1/object_storage/{container_name} exclui um contêiner vazio; um contêiner que ainda tem objetos retorna 409.

Nomes de contêineres

Um nome de contêiner tem de 3 a 63 caracteres entre letras minúsculas, dígitos e hífens, e começa e termina com uma letra ou um dígito. Sublinhados, pontos e espaços não são permitidos, nem um nome formatado como um endereço IP.

Objetos

  • POST /api/v1/object_storage/{container_name}/objects envia um novo objeto como file multipart, com o nome object_name ou, sem ele, com o nome do arquivo. Um nome que já existe retorna 409.
  • PUT /api/v1/object_storage/{container_name}/objects/{object_name}/content substitui o conteúdo de um objeto.
  • GET /api/v1/object_storage/{container_name}/objects/{object_name}/content baixa o objeto: texto como UTF-8, conteúdo binário codificado em base64.
  • GET e PATCH /api/v1/object_storage/{container_name}/objects/{object_name} leem e atualizam os metadados dele, e DELETE no mesmo caminho o exclui.
  • POST /api/v1/object_storage/{container_name}/objects/{object_name}/copy e /move copiam ou movem o objeto para um novo nome ou para outro contêiner.

Um nome de objeto pode conter /, que é lido como um caminho de pastas.

Listagem e paginação

GET /api/v1/object_storage/{container_name}/objects lista os objetos de um contêiner. Pagine com limit e marker (o último nome que você viu), ou defina full_listing=true para receber todos em uma única resposta. prefix mantém só os nomes que começam com ele.

Passe delimiter=/ para uma listagem no estilo de pastas: os objetos deste nível vêm em objects, e os prefixos um nível abaixo, em subdirs.

Credenciais de curta duração

POST /api/v1/object_storage/credentials emite uma credencial de curta duração, com escopo de projeto, para o projeto do escopo atual da sua sessão, e retorna o trust_id e o expires_at dela. Você pode pedir uma duração com ttl_seconds; o servidor impõe um teto. Um editor independente envia o trust_id em um header X-Trust-Id nas chamadas seguintes ao armazenamento de objetos e, assim, chega ao armazenamento do projeto sem ter o seu token completo nem nenhum segredo duradouro; cada chamada continua sendo autenticada normalmente. DELETE /api/v1/object_storage/credentials/{trust_id} a revoga.

Próximos passos

  • Autenticação — as chaves de API vão no header X-API-Key.
  • Armazenamento em blocos — quando você quer um sistema de arquivos em vez de um armazenamento chave-valor, ou precisa de semântica POSIX.
  • Editor Mosaic — editor no navegador para arquivos YAML/JSON/Markdown dentro dos seus contêineres.

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 →