Crear un tablón de recursos con archivos de una carpeta

Este ejemplo guarda documentos Markdown e imágenes en la carpeta books/guide y usa Webspace para proporcionar la lista de archivos y el contenido del archivo seleccionado. La carpeta sigue siendo la fuente de los recursos, así que no es necesario copiar cada documento en una base de datos.

Antes de empezar

• Necesita permiso para desplegar esquemas y API.
• Prepare en books/guide los archivos que ofrecerá en el tablón.
• Configure primero el permiso de lectura del endpoint para el público previsto.

Este ejemplo solo proporciona archivos .md y .png y no consulta subcarpetas.

books/
└── guide/
    ├── getting-started.md
    ├── permissions.md
    └── permissions.png

Configurar un endpoint de directorio

Este ejemplo usa guide como Database identifier, assets como nombre de tabla y content como ruta personalizada.

1. Abra el archivo de esquema y seleccione API Build.
2. En la tabla assets, seleccione Add static file API.
3. Introduzca content como ruta personalizada.
4. En Source type, seleccione Folder list · file content.
5. En Choose folder, seleccione books/guide.
6. Añada .md y .png en Allowed extensions.
7. Active Include subfolders solo si quiere proporcionar también las subcarpetas. Déjelo desactivado para este ejemplo.
8. Configure el permiso del endpoint para el público previsto del tablón.

El contrato de archivos estáticos resultante es el siguiente:

{
  "mode": "directory",
  "extensions": [".md", ".png"],
  "recursive": false
}

mode puede ser file para un único archivo o directory para una carpeta. extensions es la lista permitida de extensiones que puede devolver el endpoint. Cuando recursive es false, la lista solo incluye los archivos situados directamente en books/guide. Configure recursive como true para proporcionar también los archivos de las subcarpetas.

Desplegar la API

1. En la barra fija de despliegue situada en la parte inferior de la pantalla, seleccione Deploy para expandir el panel hacia arriba. Esta primera selección aún no despliega la API.
2. Introduzca guide en Database identifier y revise Storage engine mode y Client deployment path.
3. Seleccione de nuevo Deploy dentro del panel expandido.
4. Tras el despliegue, compruebe la respuesta de la lista en /api/web/guide/assets/content.

Cargar la lista de archivos

Una solicitud al endpoint de directorio sin especificar un archivo devuelve una lista JSON.

{
  "items": [
    {
      "name": "getting-started.md",
      "path": "getting-started.md",
      "size": 1842,
      "mimeType": "text/markdown; charset=utf-8",
      "modifiedAt": "2026-10-02T09:30:00Z",
      "url": "/api/web/guide/assets/content?file=getting-started.md"
    }
  ],
  "total": 3,
  "offset": 0,
  "limit": 20
}

Use name como etiqueta de la lista y url cuando el lector seleccione un archivo. total contiene el número total de resultados, mientras que offset y limit describen la página devuelta.

Puede limitar la lista con las siguientes consultas:

GET /api/web/guide/assets/content?q=permission&order=modifiedAt:desc&offset=0&limit=20

Si se omite limit, el endpoint devuelve 50 elementos. El máximo es de 200 por solicitud. Para una carpeta más grande, consulte total y aumente offset para solicitar la siguiente página. El valor predeterminado de order es name:asc y q admite hasta 256 caracteres.

Mostrar el documento seleccionado

Pase en la consulta file una ruta relativa obtenida de la lista para recuperar el archivo correspondiente. Solo se admite la ruta relativa de un archivo de una subcarpeta cuando recursive es true.

GET /api/web/guide/assets/content?file=getting-started.md

Muestre las respuestas .md con un procesador de Markdown y use la URL de respuesta de los archivos .png como origen de la imagen. Es preferible usar la url de la lista en lugar de construir las rutas en el cliente, para que resulte más sencillo adaptarse a los cambios en la ruta del endpoint.

Información útil

• Añada a extensions solo los formatos que quiera publicar. Este ejemplo permite .md y .png.
• Puede configurar hasta 32 extensiones.
• Los archivos y las carpetas ocultos cuyo nombre empieza por un punto (.), así como los enlaces simbólicos, no se proporcionan en las solicitudes de listas ni de archivos.
• Las rutas relativas no pueden salir de la carpeta de origen configurada.
• La misma ACL del endpoint se aplica tanto a la lista como al contenido de los archivos. Indique login: false de forma explícita para un endpoint público; en un endpoint para miembros, compruebe también las condiciones de rol, nivel y equipo necesarias.
• Para calcular un valor total y un orden exactos, el servidor explora hasta 2000 archivos y carpetas. Los elementos que después se excluyen por estar ocultos o por el filtro de extensiones también cuentan para este límite. Si se supera, el servidor devuelve un error 413 y no proporciona una lista parcial.
• Después de añadir o modificar un archivo, compruebe que se actualicen modifiedAt y el contenido mostrado.
• Al convertir Markdown en HTML, configure el procesador para que no admita scripts ni marcado peligroso.

Documentos relacionados

• Crear una API y desplegar una base de datos
• Consultar el ejemplo de frontend
• Desplegar un sitio web