Ir a REZICS

Desarrolladores

Marcar un libro como leído también es una operación de API.

Al marcar una obra como «Leída» en tu biblioteca, el sitio envía la petición que aparece aquí. Tu programa puede enviar la misma petición, obtener el mismo resultado y pasar las mismas comprobaciones.

Escritura

Una petición de escritura, línea por línea

PUT /v1/works/{id}/reader-status
Authorization: Bearer …
Idempotency-Key: 7f3c2a9e-read
Content-Type: application/json

{
  "actingSubject":
    "https://rezics.com/id/…",
  "expectedVersion": 3,
  "status": "read",
  "finishedOn": "2026-10-19"
}
La versión, la fecha y la clave de idempotencia son ejemplos.

  • La ruta identifica una obra

    {id}

    Cada elemento de REZICS tiene un identificador estable que empieza por https://rezics.com/id/. Se mantiene igual en todos los idiomas y sitios.

  • Indica la identidad

    actingSubject

    Una cuenta puede representar a una persona o a una organización. Cada escritura debe indicar con qué identidad actúa, y el servidor comprueba sus permisos antes de ejecutarla.

  • Repite peticiones de forma segura

    Idempotency-Key

    Cada escritura incluye una clave de idempotencia. Si se agota el tiempo o se corta la conexión, puedes repetir la petición con la misma clave sin duplicar la escritura.

  • Evita sobrescribir datos

    expectedVersion

    Si leíste la versión 3, indica la versión 3. Si alguien la cambió entretanto, tu escritura no la sobrescribe.

  • Los errores incluyen detalles

    application/problem+json

    Si falla, code contiene un código fijo que el programa puede usar para responder, sin comparar el texto del mensaje.

Repetir

Repite la petición y obtén el mismo resultado.

Si repites la misma petición con la misma clave, el servidor devuelve el resultado original, mantiene la versión 4 y cambia replayed a true. Si cambias el contenido y reutilizas la clave, devuelve 409 reader_status_conflict. Si la versión ya no es 3, devuelve 409 stale_reader_status. Vuelve a leer los datos antes de escribir.

  • Primera petición

    200
{
  "status": "read",
  "version": 4,
  "replayed": false
}

  • Repetir

    200
{
  "status": "read",
  "version": 4,
  "replayed": true
}

  • Versión desactualizada

    409
{
  "status": 409,
  "code":
    "stale_reader_status"
}

Tipos

La API y sus tipos proceden de una misma definición

El sitio de REZICS usa TypeScript para llamar a la API, y los tipos de peticiones y respuestas proceden de las rutas declaradas en el servidor. Si cambia un campo o se añade un código de error, el programa que llama a la API lo detecta al compilar. El SDK de TypeScript se genera a partir de la misma definición, así que usa los mismos tipos que el sitio.

La documentación OpenAPI 3.1 también se genera desde las mismas rutas y describe la autenticación, el formato de petición y las respuestas de cada código de estado.

main().v1
  .works({ id: uuid(work) })
  ['reader-status'].put({
    actingSubject,
    expectedVersion,
    status: 'read',
    ...dates,
  }, headers())
Fragmento de la función Biblioteca del sitio de REZICS.

generated/openapi/main/public.json

Lectura

La lectura también tiene reglas

  • nextCursor · snapshot

    Las listas largas incluyen un cursor para la página siguiente y se pueden recorrer hasta el final. Las exportaciones de la biblioteca también incluyen una instantánea. Si los datos cambian durante la exportación, se indica y no recibes un archivo incompleto.

  • count.precision

    Los resultados de búsqueda indican si la cantidad es exacta o un mínimo.

  • title.language · basis

    Los títulos incluyen la etiqueta de idioma y la dirección de escritura. También se indica si el idioma es el solicitado, una variante de escritura, otro idioma o una alternativa.

  • 404 resource_unavailable

    Las respuestas a recursos que no puedes consultar son iguales que las de recursos inexistentes, así que no revelan que existen.

Desarrolladores

Otras páginas

Crea tus propias herramientas con la misma API.

Permite que tus programas lean y modifiquen obras, tu biblioteca y los datos de la comunidad. Cada operación aplica las reglas de identidad y autorización de REZICS.

Ir a REZICS

Productos

Módulos

Idioma