Referencia de la API

Subidas

Subir archivos o fragmentos por HTTP, consultar los fragmentos recibidos, fusionarlos en archivos o adjuntos y seguir o limpiar las tareas.

Definiciones de tipos

graphql
type Subscription {
  uploadMergeResult: UploadMergeResult!
}

type Mutation {
  deleteChunks(fileId: String!): Boolean!
  mergeChunks(fileId: String!, totalChunks: Int!, path: String!, replace: Boolean!, totalSize: Long!): MergeTask!
}

type Query {
  mergeStatus(fileId: String!): MergeTask!
  uploadedChunks(fileId: String!): [UploadedChunk!]!
}

scalar Long

type MergeTask {
	status: MergeTaskStatus!
	value: String
	mergedSize: Long
	error: String
}

enum MergeTaskStatus {
	NONE
	STARTED
	MERGING
	DONE
	FAILED
}

type UploadMergeResult {
	fileId: ID!
	ok: Boolean!
	value: String
	mergedSize: Long
	error: String
}

type UploadedChunk {
	index: Int!
	sizeBytes: Long!
}

Operaciones

http

POST /upload

info contiene los bytes sin transformar del sobre cifrado de POST /upload, no texto ni Base64. Envía info antes de file. Si el servidor devuelve HTTP 201, el cuerpo de texto contiene el nombre real del archivo guardado. Los metadatos deben incluir el tamaño declarado en bytes; si se reutilizan, se rechazan.

bash
curl 'https://<device-host>:<https-port>/upload' \
  -H 'c-id: <client-id>' \
  -F 'info=<./encrypted-info.bin' -F 'file=@./example.txt'
# Send info before file. Metadata JSON: { dir, replace, isAppFile, size }
# info contains raw encrypted request-envelope bytes for POST /upload.
# A Bearer header alone does not authenticate multipart uploads.
http

POST /upload_chunk

Envía los bytes sin transformar del sobre cifrado de POST /upload_chunk en info antes de file. HTTP 201 devuelve texto en formato index:size. Consulta uploadedChunks, ejecuta mergeChunks o mergeAppFileChunks y comprueba mergeStatus. La unión es asíncrona.

bash
curl 'https://<device-host>:<https-port>/upload_chunk' \
  -H 'c-id: <client-id>' \
  -F 'info=<./encrypted-info.bin' -F 'file=@./chunk.bin'
# Metadata JSON: { fileId, index, size }; bind encryption to POST /upload_chunk.
# Inspect uploadedChunks; call mergeChunks with totalSize for normal files,
# or mergeAppFileChunks for app attachments. Poll mergeStatus for completion.
subscription

uploadMergeResult

Recibir información de finalización o fallo de una unión asíncrona de fragmentos cargados.

graphql
subscription uploadMergeResult {
  uploadMergeResult { fileId ok value mergedSize error }
}
mutation

deleteChunks

Eliminar todos los fragmentos almacenados de un fileId de carga fragmentada. Usar tras cancelar o fallar una carga para liberar espacio en disco.

graphql
mutation deleteChunks($fileId: String!) {
  deleteChunks(fileId: $fileId)
}
mutation

mergeChunks

Iniciar la unión de fragmentos cargados en un archivo de destino; consultar mergeStatus para comprobar su finalización.

graphql
# Starts the merge and returns immediately; completion arrives over the
# websocket, and `mergeStatus` is the polling fallback for a lost event.
mutation mergeChunks($fileId: String!, $totalChunks: Int!, $path: String!, $replace: Boolean!, $totalSize: Long!) {
  mergeChunks(fileId: $fileId, totalChunks: $totalChunks, path: $path, replace: $replace, totalSize: $totalSize) { status value mergedSize error }
}
query

mergeStatus

Consultar el progreso o fallo de la unión de una carga; el estado NONE indica que no se ha iniciado ninguna unión para este ID de archivo.

graphql
# `NONE` when no merge was ever started for this id, which is what a
# client sees before it calls `mergeChunks`.
query mergeStatus($fileId: String!) {
  mergeStatus(fileId: $fileId) { status value mergedSize error }
}
query

uploadedChunks

Listar los índices de fragmentos ya recibidos de una carga fragmentada reanudable. Se usa para reanudar cargas interrumpidas.

graphql
query uploadedChunks($fileId: String!) {
  uploadedChunks(fileId: $fileId) { index sizeBytes }
}