Documentación / Referencia / API Reference

API Reference (S3)

Catálogo de operaciones de la API compatible con S3 que admite OtterStorage, con su endpoint, autenticación y ejemplos.

OtterStorage expone una API compatible con S3, por lo que puedes usar el SDK de AWS, la CLI o cualquier cliente compatible sin software propietario. Esta referencia enumera las operaciones soportadas, agrupadas por ámbito (servicio, bucket, objeto, versionado, multiparte y Object Lock), e indica cómo autenticarte y a qué endpoint dirigir tus peticiones. Recuerda que no cobramos por peticiones ni por borrados, así que puedes listar, consultar y limpiar sin coste por operación.

Endpoint y región

Todas las peticiones se dirigen al endpoint base de OtterStorage:

https://s3.otterstorage.io

Endpoint base: https://s3.otterstorage.io (HTTPS obligatorio).
Región de ejemplo: eu-mad. Indícala en la configuración de tu cliente y en LocationConstraint al crear buckets.
Credenciales: un access key y un secret key por bucket, emitidos desde el panel.

Estilo de direccionamiento

OtterStorage admite path-style, es decir, el nombre del bucket forma parte de la ruta y no del subdominio:

https://s3.otterstorage.io/mi-bucket/ruta/objeto.txt

El estilo path-style funciona con cualquier nombre de bucket, incluidos los que contienen puntos, y es el más sencillo de usar tras un proxy o en entornos de desarrollo. Si tu cliente usa por defecto virtual-hosted style, fuérzalo a path-style; por ejemplo, con el SDK de AWS para Python (boto3):

import boto3
from botocore.config import Config

s3 = boto3.client(
    "s3",
    endpoint_url="https://s3.otterstorage.io",
    region_name="eu-mad",
    aws_access_key_id="TU_ACCESS_KEY",
    aws_secret_access_key="TU_SECRET_KEY",
    config=Config(s3={"addressing_style": "path"}),
)

Autenticación

OtterStorage utiliza AWS Signature Version 4 (SigV4) para firmar las peticiones. Los SDK y la CLI oficiales generan la firma automáticamente: solo necesitas configurar tu access key, tu secret key y la región. Una petición firmada incluye, entre otras, las siguientes cabeceras:

Authorization: AWS4-HMAC-SHA256 Credential=TU_ACCESS_KEY/20260611/eu-mad/s3/aws4_request, \
  SignedHeaders=host;x-amz-content-sha256;x-amz-date, Signature=...
x-amz-date: 20260611T120000Z
x-amz-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
host: s3.otterstorage.io

El reloj del cliente debe estar sincronizado: una desviación grande respecto a la hora del servidor invalida la firma. Para configurar la CLI paso a paso, consulta la guía de AWS CLI.

Servicio

Operaciones a nivel de cuenta, no asociadas a un bucket concreto.

ListBuckets — lista todos los buckets a los que tienen acceso tus credenciales.

aws --profile otter --endpoint-url https://s3.otterstorage.io s3api list-buckets

Operaciones de bucket

Crean, consultan y configuran buckets y sus políticas.

Ciclo de vida del bucket

CreateBucket — crea un bucket (admite LocationConstraint y Object Lock).
HeadBucket — comprueba la existencia del bucket y tus permisos.
DeleteBucket — elimina un bucket vacío.
GetBucketLocation — devuelve la región del bucket.

# Crear un bucket en eu-mad
aws --profile otter s3api create-bucket \
  --bucket mi-bucket \
  --create-bucket-configuration LocationConstraint=eu-mad

# Comprobar que existe y tienes acceso
aws --profile otter s3api head-bucket --bucket mi-bucket

Versionado del bucket

PutBucketVersioning — activa o suspende el versionado.
GetBucketVersioning — consulta el estado del versionado.

aws --profile otter s3api put-bucket-versioning \
  --bucket mi-bucket \
  --versioning-configuration Status=Enabled

Políticas de bucket

PutBucketPolicy — define una política de acceso en formato JSON.
GetBucketPolicy — recupera la política vigente.
DeleteBucketPolicy — elimina la política del bucket.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "LecturaPublicaDeAssets",
      "Effect": "Allow",
      "Principal": "*",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::mi-bucket/public/*"
    }
  ]
}

Reglas de ciclo de vida

PutBucketLifecycleConfiguration — define reglas de expiración y limpieza.
GetBucketLifecycleConfiguration — consulta las reglas activas.
DeleteBucketLifecycle — elimina toda la configuración de ciclo de vida.

Las reglas de ciclo de vida permiten, por ejemplo, expirar versiones antiguas o abortar subidas multiparte incompletas de forma automática. Consulta la guía de ciclo de vida para ver ejemplos completos.

ACL y etiquetas del bucket

GetBucketAcl / PutBucketAcl — consulta y define la lista de control de acceso del bucket.
PutBucketTagging / GetBucketTagging — asigna y consulta etiquetas (clave/valor) del bucket.

CORS

PutBucketCors — configura las reglas CORS para accesos desde el navegador.
GetBucketCors — consulta la configuración CORS actual.

{
  "CORSRules": [
    {
      "AllowedOrigins": ["https://app.ejemplo.com"],
      "AllowedMethods": ["GET", "PUT"],
      "AllowedHeaders": ["*"],
      "MaxAgeSeconds": 3000
    }
  ]
}

Operaciones de objeto

Suben, descargan, copian, listan y eliminan objetos, además de gestionar sus ACL y etiquetas.

PutObject — sube un objeto (admite metadatos, Content-Type y, con Object Lock, retención).
GetObject — descarga un objeto; admite descargas por rango (Range).
HeadObject — recupera solo los metadatos y cabeceras del objeto.
DeleteObject — elimina un objeto (o crea un marcador de borrado si hay versionado).
DeleteObjects — elimina hasta 1000 objetos en una sola petición.
CopyObject — copia un objeto entre claves o buckets sin descargarlo.
ListObjectsV2 — lista objetos por prefijo (paginación con continuation-token; recomendada).
ListObjects — variante original con marcadores (marker); se mantiene por compatibilidad.
GetObjectAcl / PutObjectAcl — consulta y define la ACL de un objeto.
GetObjectTagging / PutObjectTagging — consulta y asigna etiquetas a un objeto.

# Subir un objeto con su tipo de contenido
aws --profile otter s3api put-object \
  --bucket mi-bucket \
  --key docs/manual.pdf \
  --body ./manual.pdf \
  --content-type application/pdf

# Copiar un objeto a otra clave del mismo bucket
aws --profile otter s3api copy-object \
  --bucket mi-bucket \
  --copy-source mi-bucket/docs/manual.pdf \
  --key docs/manual-copia.pdf

# Listar por prefijo con ListObjectsV2
aws --profile otter s3api list-objects-v2 \
  --bucket mi-bucket \
  --prefix docs/ \
  --max-keys 100

El borrado por lotes con DeleteObjects recibe la lista de claves en el cuerpo de la petición:

aws --profile otter s3api delete-objects \
  --bucket mi-bucket \
  --delete '{"Objects":[{"Key":"docs/a.txt"},{"Key":"docs/b.txt"}]}'

Como no facturamos peticiones ni eliminaciones, puedes listar y limpiar tantos objetos como necesites sin coste por operación.

Versionado

Con el versionado activado, cada objeto conserva sus versiones anteriores y se identifican por versionId. Esto protege frente a sobrescrituras y borrados accidentales.

ListObjectVersions — lista todas las versiones y marcadores de borrado de un bucket o prefijo.
GetObject con ?versionId= — descarga una versión concreta de un objeto.
DeleteObject con ?versionId= — elimina de forma permanente una versión concreta.

# Listar todas las versiones
aws --profile otter s3api list-object-versions --bucket mi-bucket

# Descargar una versión concreta
aws --profile otter s3api get-object \
  --bucket mi-bucket \
  --key docs/manual.pdf \
  --version-id LA_VERSION_ID \
  ./manual-anterior.pdf

# Borrar permanentemente una versión concreta
aws --profile otter s3api delete-object \
  --bucket mi-bucket \
  --key docs/manual.pdf \
  --version-id LA_VERSION_ID

Para más detalle sobre cómo activarlo y restaurar versiones, consulta la guía de versionado.

Subida multiparte

La subida multiparte divide un objeto grande en partes que se transfieren por separado (y en paralelo) y luego se ensamblan en el servidor. Es la vía recomendada para archivos grandes y para reanudar transferencias.

CreateMultipartUpload — inicia una subida y devuelve un UploadId.
UploadPart — sube una parte numerada del objeto.
UploadPartCopy — crea una parte copiando un rango de otro objeto existente.
CompleteMultipartUpload — ensambla las partes y finaliza el objeto.
AbortMultipartUpload — cancela la subida y descarta las partes ya enviadas.
ListMultipartUploads — lista las subidas multiparte en curso de un bucket.
ListParts — lista las partes ya subidas de un UploadId.

# Ver subidas multiparte pendientes
aws --profile otter s3api list-multipart-uploads --bucket mi-bucket

# Abortar una subida concreta (no tiene coste de operación)
aws --profile otter s3api abort-multipart-upload \
  --bucket mi-bucket \
  --key media/video.mov \
  --upload-id EL_UPLOAD_ID

Los comandos de alto nivel (aws s3 cp y aws s3 sync) usan multiparte de forma automática cuando el archivo supera el umbral configurado. Una regla de ciclo de vida puede abortar automáticamente las subidas incompletas pasado cierto tiempo.

Object Lock

Object Lock aplica un modelo WORM (escribir una vez, leer muchas) que impide borrar o sobrescribir un objeto hasta una fecha determinada o mientras tenga una retención legal activa. Requiere un bucket con Object Lock habilitado, lo que activa también el versionado.

PutObjectLockConfiguration / GetObjectLockConfiguration — define y consulta la retención por defecto del bucket.
PutObjectRetention / GetObjectRetention — fija y consulta la retención (modo GOVERNANCE o COMPLIANCE) de una versión.
PutObjectLegalHold / GetObjectLegalHold — activa, desactiva y consulta una retención legal independiente de la fecha.

# Aplicar retención COMPLIANCE a un objeto
aws --profile otter s3api put-object-retention \
  --bucket bucket-worm \
  --key contratos/2026.pdf \
  --retention '{"Mode":"COMPLIANCE","RetainUntilDate":"2027-06-11T00:00:00Z"}'

# Activar una retención legal sobre el objeto
aws --profile otter s3api put-object-legal-hold \
  --bucket bucket-worm \
  --key contratos/2026.pdf \
  --legal-hold Status=ON

Consulta la guía de Object Lock y la de retención legal para el detalle de cada modo.

URLs prefirmadas (presigned)

Una URL prefirmada incrusta una firma SigV4 temporal en la propia URL, de modo que puedes compartir un objeto privado (o permitir una subida) durante un tiempo limitado sin exponer tus claves. La firma es de cliente: OtterStorage la verifica al recibir la petición, no hace falta una llamada previa al servidor para generarla.

# Generar una URL de descarga válida 1 hora (3600 s)
aws --profile otter s3 presign s3://mi-bucket/docs/manual.pdf --expires-in 3600

También puedes generar URLs prefirmadas con cualquier SDK; por ejemplo, una URL de subida con boto3:

url = s3.generate_presigned_url(
    "put_object",
    Params={"Bucket": "mi-bucket", "Key": "uploads/foto.jpg"},
    ExpiresIn=900,
)

Facturación de peticiones

En OtterStorage las peticiones a la API no se facturan: no cobramos por operaciones de lectura, escritura, listado ni borrado. Puedes paginar listados grandes, comprobar metadatos con HeadObject o limpiar versiones y subidas incompletas sin que ello añada coste por operación a tu factura.

Siguientes pasos

Configura tu cliente de terminal con la guía de AWS CLI.
Protege tus datos frente a borrados con el versionado.
Aplica cumplimiento WORM con Object Lock.

¿Necesitas más contexto sobre buckets, claves o regiones? Vuelve a la documentación.

¿Listo para probarlo?

Crea tu cuenta y obtén tus claves en minutos.

Hazte Founding Otter