Crear API y desplegar una base de datos

Después de crear un archivo de esquema (.sfn), convierta el diseño en un servicio operativo. API Build prepara para cada tabla API de creación, consulta, modificación y eliminación, y muestra quién puede usar cada dirección.

También puede conectar al mismo servicio API de consultas personalizadas, API de archivos estáticos y eventos en tiempo real.

Antes de comenzar

• Permiso necesario: ser un usuario con permiso para utilizar bases de datos.
• Requisito previo: crear primero un archivo de esquema (.sfn).

Abrir API Build

Seleccione la pestaña API Build en la parte superior de la pantalla del esquema para consultar las API generadas automáticamente para cada tabla.

API generadas automáticamente

De forma predeterminada se generan cinco API por tabla. También puede añadir API personalizadas cuando lo necesite.

Use Add new API (Custom Endpoint) para definir una API con la consulta y el formato de respuesta necesarios. Use Add static file API para servir archivos JSON, XML, HTML, imágenes y archivos binarios del espacio de trabajo con el tipo correspondiente.

Servir un archivo o una carpeta mediante una API

1. Seleccione Add static file API.
2. En Storage space, elija Team space o Personal space.
3. En Source type, elija Single file o Folder list · file content; después, seleccione el origen mediante Choose file o Choose folder.
4. Para una carpeta, configure Allowed extensions e Include subfolders. Si deja vacías las extensiones, se incluirán todos los tipos.
5. En Response mode, elija si desea mostrar el contenido en el navegador (Display in browser) o devolverlo como archivo (Download).
6. Compruebe los permisos del endpoint y despliegue el esquema.

Un endpoint de archivo devuelve su contenido. Un endpoint de carpeta crea una lista JSON y una dirección que lee el contenido mediante el id de cada elemento. Al cambiar el nombre o mover un archivo también cambia su id, que se basa en la ruta. Los clientes deben usar el id o viewUrl más reciente de la respuesta de la lista.

Los endpoints de funciones controlan los permisos de capacidades generales del servicio, como sockets en tiempo real, carga de archivos e imágenes y respuestas de AI.

Importar eventos en tiempo real y ajustes REST

En Event definitions del socket en tiempo real puede definir solo eventos o importar un paquete JSON o YAML que también incluya las tablas y los ajustes REST necesarios.

1. Seleccione Paste AI answer y pegue el paquete. También puede pegar uno preparado por usted con el mismo formato.
2. Elija Merge by name para conservar los eventos existentes o Replace all para sustituirlos por completo.
3. En Preview, compruebe los eventos que se añadirán, cambiarán o eliminarán, además del número de tablas, columnas y endpoints REST que se añadirán.
4. Revise los conflictos REST y los elementos normalizados u omitidos. Seleccione Overwrite conflicting REST settings únicamente si debe cambiar los ajustes REST existentes.
5. Revise la comprobación del servidor, corrija los errores y seleccione Apply.

La importación modifica el esquema que está editando. Los cambios solo se aplican al servicio después de completar Deploy. Durante el despliegue, el servidor vuelve a comprobar las reglas de eventos y REST y rechaza el despliegue si no son válidas.

Crear API más allá de CRUD mediante un endpoint personalizado

Cuando las cinco API generadas (list/view/create/update/delete) no sean suficientes, seleccione Add new API (Custom Endpoint) para definir el comportamiento con mayor precisión.

Tipo de operación

Además de las cinco operaciones CRUD, el menú Operation kind ofrece estas opciones:

En Scope, elija Collection para toda la tabla o varios registros, normalmente sin :id en la ruta; Item para un registro concreto; o Command para un endpoint de comandos que no encaja en CRUD.

Los permisos usan los mismos tres niveles que la API REST

Los permisos de los endpoints personalizados funcionan igual que los de las API generadas automáticamente. La propia pantalla explica cada opción.

Con Member + Additional Conditions puede combinar condiciones de nivel, equipo, administrador y propietario. Puede aplicar restricciones como «nivel 2 o superior» o «solo el equipo de ventas» del mismo modo que en un endpoint REST generado automáticamente.

Escribir SQL directamente

En la pestaña Processing flow, Base query contiene un editor en el que puede escribir el SQL que ejecutará el endpoint. En una API generada automáticamente, cambie Base query a Hand-written SQL para abrir el mismo editor.

La columna Processing de la lista de API REST muestra una insignia SQL cuando el endpoint usa una consulta escrita directamente. Las condiciones que no pueden expresarse con API generadas, como «rechazar si este miembro ya ha creado tres filas hoy», solo pueden crearse con este editor.

Comprobar el SQL y los parámetros

Al escribir SQL, el navegador comprueba la sintaxis y las tablas y columnas del esquema actual. Si un error o aviso incluye la línea y la columna, selecciónelo para ir a esa posición en el editor. También puede abrir el SQL con errores desde el área de despliegue.

Esta comprobación no ejecuta la consulta en la base de datos. Después del despliegue, llame a la API para comprobar las funciones específicas del motor, los permisos de acceso y los resultados con datos reales.

La lista de parámetros muestra los valores :name usados en el SQL. El servidor rellena los valores reservados :id, :user_id, :nick y :now. Los demás valores proceden de la cadena de consulta en las solicitudes de lectura o del cuerpo de la solicitud tras el procesamiento de entrada en las de escritura. Los valores ausentes se tratan como NULL.

Cambiar el procesamiento de solicitudes mediante el flujo

Sin escribir SQL, puede añadir en orden funciones predefinidas en la pestaña Processing flow. Las funciones se dividen en tres etapas: entrada, base de datos y salida.

Configurar permisos

Configure el acceso de cada API por separado. Los miembros son las cuentas existentes del espacio de trabajo. No necesita crear otro sistema de autenticación: los miembros, niveles y equipos del espacio se conectan directamente a los permisos de la API.

Desplegar

Introduzca la información de despliegue de la siguiente manera.

1. Database identifier: introduzca en inglés el nombre lógico de la base de datos que se usará en el servidor.
2. Storage engine mode: seleccione SQLite3, PostgreSQL, MySQL o MariaDB. Para una base externa, introduzca también el host, el puerto, el nombre de la base, el usuario y la contraseña. MySQL y MariaDB utilizan una configuración basada en InnoDB.
3. Revise los siguientes elementos en General y Advanced.

Seleccione Deploy en la sección situada debajo de la lista de API para abrir la configuración. Esta sección permanece fija al final del editor mientras desplaza la lista. La primera selección no inicia el despliegue. Revise los ajustes y vuelva a seleccionar Deploy para preparar la base de datos y las API. Si indicó una ruta de despliegue del cliente, Webspace también creará una interfaz de ejemplo para probarlas. Consulte Revisar el ejemplo de frontend para modificar la interfaz.

Ejemplos de solicitudes de API

Los siguientes ejemplos utilizan la tabla user_profile.

GET  /api/web/{dbName}/user_profile/list
GET  /api/web/{dbName}/user_profile/view/{id}
POST /api/web/{dbName}/user_profile/create
PUT  /api/web/{dbName}/user_profile/update/{id}
DELETE /api/web/{dbName}/user_profile/delete/{id}

Ejemplo de solicitud de creación (POST):

POST /api/web/{dbName}/user_profile/create
Content-Type: application/json

{
  "email": "user@example.com",
  "is_active": true
}

Leer respuestas de error

Si una solicitud falla, compruebe su estado HTTP y code o errorCode. Los códigos no cambian con el idioma: úselos para decidir si debe solicitar el inicio de sesión o reintentar, y use message para mostrar el mensaje.

Los mensajes de error predeterminados de Webspace admiten coreano, inglés, japonés, chino simplificado y alemán. Se utiliza primero el idioma del miembro que ha iniciado sesión. Si no está definido o no se admite, el servidor consulta Accept-Language en la solicitud. Si ninguno coincide, utiliza inglés. No compare el texto mostrado en una integración de API.

Por ejemplo, una solicitud que requiere iniciar sesión devuelve estos datos.

{
  "code": "WEBSPACE_LOGIN_REQUIRED",
  "errorCode": "WEBSPACE_LOGIN_REQUIRED",
  "message": "로그인이 필요합니다."
}

Estos son los campos principales que debe comprobar, no un ejemplo de la respuesta completa. Las API REST, de archivos estáticos y de administración pueden usar envoltorios distintos.

• La validación de entradas conserva el formato existente, con ok: false y una lista errors. Compruebe ok incluso cuando el estado HTTP sea 200 y use field, code y message de cada elemento para explicar el problema.
• Los errores de WebSocket aparecen dentro de data en un mensaje type: "error". Se conserva la clave de clasificación key; code y errorCode identifican la causa.
• Las rutas físicas del servidor, el SQL y los errores internos sin procesar no se devuelven a los usuarios. Si se requiere que un operador consulte los registros, proporcione la hora, la ruta de la solicitud, el estado HTTP y el código del error.

Despliegue y sobrescritura

La sobrescritura de un esquema cuya base de datos ya contiene datos sigue la política de despliegue del servidor. La organización puede prohibirla o limitarla a administradores y responsables designados. Antes de cambiar la estructura, revise las columnas y API afectadas y confirme los procedimientos de copia de seguridad y recuperación.

Información útil

• Las API utilizan sesiones de inicio de SetFN para autenticarse. Las solicitudes sin autenticar se rechazan, salvo que el permiso de la API sea Anyone.
• Al cambiar la estructura del esquema también se actualizan los endpoints. Compruebe la compatibilidad con las integraciones existentes.
• Los datos de SQLite3 se guardan en el almacenamiento de Webspace del servidor. Los de motores externos se guardan en la base configurada por el administrador.
• Use filtros, ordenación y tamaños de página solo dentro de los intervalos permitidos por el servidor.
• Para llamadas desde un sitio externo, compruebe también los orígenes permitidos y la configuración CSP del administrador.

Documentos relacionados

• Crear un archivo de esquema (.sfn)
• Crear un juego de Gomoku en tiempo real
• Consultar el ejemplo de frontend
• Rendimiento y escalado
• Empezar a administrar Webspace