Introducción a la API

Novodat expone tu base de datos a través de una API REST y una API GraphQL. Las dos se generan a partir del esquema: no hay nada que declarar, y una tabla o un campo nuevos están disponibles en cuanto existen.

Dirección base

Todas las rutas cuelgan de PUBLIC_URL, por ejemplo https://datos.ejemplo.com/items/articles. Peticiones y respuestas son JSON (application/json), salvo la subida de archivos (multipart/form-data) y los assets.

Colecciones, ítems y campos

Término	En la base de datos
Colección	Una tabla o una vista. En PostgreSQL con varios schemas, las tablas fuera del schema por defecto se llaman schema.tabla.
Ítem	Una fila.
Campo	Una columna, o una relación sin columna propia (el lado "muchos" de una relación).

Tus tablas se leen y escriben en /items/<colección>. Las tablas propias de Novodat (novodat_*) tienen sus propias rutas: /users, /files, /collections… y nunca se alcanzan desde /items.

Respuestas

Una respuesta correcta envuelve su resultado en data, con meta cuando se piden recuentos:

{
  "data": [{ "id": 1, "title": "Hola" }],
  "meta": { "filter_count": 1 }
}

Los borrados, y las escrituras cuyo resultado no puedes leer, responden 204 sin cuerpo.

Errores

Los errores siempre llegan como una lista, cada uno con un code estable:

{
  "errors": [
    {
      "message": "Value for field \"slug\" of collection \"articles\" has to be unique.",
      "extensions": { "code": "RECORD_NOT_UNIQUE", "collection": "articles", "field": "slug" }
    }
  ]
}

Los mensajes están en inglés y pueden cambiar; los programas deben basarse en extensions.code, y traducir a partir de él cuando muestran el error a las personas.

Código	Estado	Significado	Datos extra
FORBIDDEN	403	Sin permiso, o el recurso no existe. Novodat nunca revela si existe algo que no puedes ver.
INVALID_CREDENTIALS	401	Correo o contraseña incorrectos.
INVALID_OTP	401	Falta el código de dos pasos o es incorrecto.
INVALID_TOKEN	401	El token no es válido, su sesión se cerró o su usuario ya no está activo.
TOKEN_EXPIRED	401	El token de acceso caducó: renuévalo.
TFA_REQUIRED	403	Una política exige la autenticación en dos pasos y el usuario no la ha configurado.
INVALID_PAYLOAD	400	El cuerpo no es válido.	path
INVALID_QUERY	400	Un parámetro de consulta no es válido.	parameter
RECORD_NOT_UNIQUE	400	Ya existe un valor único igual.	collection, field
VALUE_TOO_LONG	400	Un valor es más largo de lo que permite su campo.	collection, field, maxLength
CONTAINS_NULL_VALUES	400	Un campo no puede pasar a obligatorio: algunas filas no tienen valor.	collection, field
VECTOR_DIMENSION_MISMATCH	400	Un vector tiene un número de dimensiones incorrecto.	field, expected, received
UNSUPPORTED_FEATURE	400	El motor de base de datos no ofrece esta funcionalidad.	feature, engine
ROUTE_NOT_FOUND	404	No existe esa ruta.	path
CONTENT_TOO_LARGE	413	La subida es demasiado grande.	limit
RANGE_NOT_SATISFIABLE	416	El rango de bytes pedido está fuera del archivo.	size
REQUESTS_EXCEEDED	429	Demasiadas peticiones o intentos fallidos. La cabecera Retry-After dice cuándo volver a intentarlo.	limit, retryAfter
EXTENSION_MISSING	500	Hace falta una extensión de PostgreSQL y no se pudo instalar. El mensaje incluye el comando para un administrador.	extension, command
SERVICE_UNAVAILABLE	503	Un servicio que Novodat necesita (la base de datos, un proveedor de IA, un directorio…) no respondió.	service
INTERNAL	500	Error inesperado. Los detalles quedan en el log del servidor.

Identificador de la petición

Cada respuesta lleva una cabecera X-Request-Id. Novodat conserva la que envía el cliente o un proxy cuando es segura (hasta 128 letras, dígitos, ., _, : o -), o genera una nueva. Los logs usan el mismo identificador, así que es lo mejor que puedes citar al informar de un problema.

Capacidades del motor

Algunas funcionalidades dependen del motor de base de datos (consulta las funcionalidades exclusivas de PostgreSQL). GET /database/capabilities indica lo que ofrece la base de datos actual:

{
  "data": {
    "engine": "postgres",
    "capabilities": {
      "vector": true, "customTypes": true, "arrays": true, "jsonb": true,
      "multiSchema": true, "fullTextSearch": "tsvector", "geometry": "postgis", "…": "…"
    }
  }
}

Las funcionalidades que el motor no tiene no aparecen en GraphQL ni en OpenAPI, y usarlas de todos modos responde UNSUPPORTED_FEATURE.

OpenAPI

GET /server/specs/oas devuelve un documento OpenAPI 3.1 de lo que puede hacer quien llama: solo las colecciones, campos, operaciones y operadores de filtro disponibles para ese usuario en este motor. Cárgalo en Postman, Insomnia, Swagger UI o un generador de clientes, con el token del usuario con el que actuará el cliente.

curl -s https://datos.ejemplo.com/server/specs/oas -H "Authorization: Bearer $TOKEN" > novodat.openapi.json

Rutas del servidor

No necesitan autenticación, salvo donde se indica.

Ruta	Respuesta
GET /server/health	{ data: { status: "ok", checks: { database: { status, responseTimeMs } } } }, o 503 cuando la base de datos no responde. No cuenta para los límites de peticiones.
GET /server/info	{ data: { name: "Novodat", version } }
GET /server/specs/oas	El documento OpenAPI de quien llama.
GET /server/specs/graphql, GET /server/specs/graphql/system	El esquema GraphQL de quien llama, en SDL.
GET /server/map	El mapa base en uso y cómo se dibujan los campos de mapa. Solo usuarios con sesión.
GET /database/capabilities	El motor y sus capacidades.
GET /database/extensions	Extensiones de PostgreSQL disponibles e instaladas. Solo administradores.

Siguientes pasos

• Autenticación: obtener y usar tokens.
• Ítems y parámetros de consulta: leer y escribir tus datos.