Meratyn

Manual/Referencia

API de capas alojadas

La API de capas alojadas es una fachada propiedad de Meratyn. Las respuestas usan IDs estables de Meratyn y modelos normalizados; los identificadores de GeoNode y GeoServer nunca forman parte del contrato público.

Recursos

GET, POST        /api/layers
GET, POST        /api/layers/collections
GET, PUT, DELETE /api/layers/collections/:collectionId
POST             /api/layers/collections/:collectionId/layers
DELETE           /api/layers/collections/:collectionId/layers/:layerId
GET              /api/layers/provider
POST             /api/layers/provider/sync
POST             /api/layers/schema
GET, POST        /api/layers/remote-catalogues
DELETE           /api/layers/remote-catalogues/:catalogueId
POST             /api/layers/remote-catalogues/:catalogueId/:check|refresh|harvest
GET              /api/layers/remote-catalogues/:catalogueId/resources
GET, POST        /api/layers/principals
GET              /api/layers/principals/:principalId/members
PUT, DELETE      /api/layers/principals/:principalId/members/:userId
GET              /api/layers/metadata/schema
GET, PUT, DELETE /api/layers/:id
GET              /api/layers/:id/services
GET, POST        /api/layers/:id/gateway/:serviceId
GET              /api/layers/:id/representations
GET              /api/layers/:id/downloads
GET, HEAD        /api/layers/:id/downloads/:downloadId
GET              /api/layers/:id/usage
GET              /api/layers/:id/audit
GET              /api/layers/:id/lineage
POST             /api/layers/:id/access
GET, HEAD        /api/layers/:id/assets/:assetId/:filename
GET, PUT         /api/layers/:id/metadata
GET, PUT         /api/layers/:id/permissions
GET, PUT         /api/layers/:id/attributes
GET, POST        /api/layers/:id/styles
PUT, DELETE      /api/layers/:id/styles/:styleId
GET, PUT         /api/layers/:id/geolimits
GET, POST        /api/layers/:id/comments
DELETE           /api/layers/:id/comments/:commentId
GET, PUT, DELETE /api/layers/:id/rating
GET, PUT, DELETE /api/layers/:id/favorite
GET              /api/layers/:id/versions
POST             /api/layers/:id/replace
POST             /api/layers/:id/versions/:versionId/restore
GET, POST        /api/layers/:id/features
PATCH, DELETE    /api/layers/:id/features/:featureId
GET, POST        /api/layers/:id/related
DELETE           /api/layers/:id/related/:relatedId
GET, POST        /api/layers/:id/reconcile
GET, PUT         /api/layers/:id/workflow
GET, POST        /api/layers/:id/supplementary-assets
DELETE           /api/layers/:id/supplementary-assets/:assetId
GET, HEAD        /api/layers/:id/supplementary-assets/:assetId/download
GET              /api/layers/:id/metadata-links
POST             /api/layers/:id/metadata-file
GET              /api/layers/:id/dataset-schema
POST             /api/layers/:id/upsert
GET              /api/layers/:id/provider-jobs
POST             /api/layers/:id/recalculate-extent

POST /api/layers acepta datos de formulario multipart para archivos locales y sus sidecars. El registro de endpoints o URLs no se presenta a los usuarios.

Todas las mutaciones requieren autenticación. Las lecturas de catálogo e ítems siguen la política de descubrimiento y concesiones de la capa. Las solicitudes de servicio exigen View o Download según corresponda.

GET /api/layers acepta las facetas collection, owner, category, region, subtype, published, approved, featured, favorite y la faceta geográfica extent=minX,minY,maxX,maxY, además de texto, kind, estado y visibilidad. Las lecturas públicas de colecciones exponen solo miembros públicos. GET /api/layers/collections devuelve colecciones descubribles, mientras que scope=mine devuelve las colecciones que el usuario actual puede gestionar. Ambos endpoints de catálogo aceptan parámetros acotados limit y offset y devuelven pagination.nextOffset; los clientes deben seguir esa continuación hasta que sea null. Una colección pública acepta solo capas públicas; las colecciones privadas aceptan capas que el propietario pueda gestionar. La membresía en una colección no altera la visibilidad ni la política de eliminación de una capa.

Los registros de organización y grupo son principals de Meratyn. Los administradores los crean y gestionan su membresía; los gestores de capa conceden a los principals permisos independientes view, download, edit y manage. La visibilidad pública implica view y download para consumidores anónimos. Las capas unlisted son legibles a través de su ID estable o de un proyecto que las referencie, pero se omiten de los resultados del catálogo.

POST /api/layers/:id/access intercambia un token autenticado de Meratyn por un token de acceso de corta duración acotado a la capa. Devuelve { token, expiresAt, refreshAfter, services }. Las URLs directas de servicio que devuelve llevan el token efímero; los proyectos persistidos deben conservar solo el ID estable de capa y el ID de servicio. Los activos directos públicos no necesitan sesión.

La pasarela de activos soporta GET, HEAD, Range, If-Range y revalidación con ETag. Los rangos satisfacibles devuelven 206; los rangos inválidos devuelven 416. Los activos privados, de organización y de grupo devuelven 404 sin propiedad, concesión o acceso válido mediante sesión de capa.

Los servicios canónicos de mapa, features y datos ráster siempre se devuelven como URLs de pasarela Meratyn, incluidas las capas públicas. La pasarela resuelve en el servidor un recurso y servicio almacenados; quien llama no puede suministrar un host del proveedor. Acepta únicamente operaciones WMS/WFS/WCS acotadas, de solo lectura y limitadas al recurso, y devuelve documentos de capabilities limitados al recurso que anuncian solo el ID estable de capa de Meratyn. Rechaza transacciones, solicitudes dirigidas a otra capa, parámetros no soportados, solicitudes demasiado grandes y respuestas demasiado grandes.

WFS GetFeature y GetPropertyValue respetan el parámetro estándar srsName y por defecto usan EPSG:4326 cuando se omite. WMS soporta los parámetros estándar de GetFeatureInfo, incluidos INFO_FORMAT y FEATURE_COUNT, de modo que un cliente puede usar su flujo habitual de identificación. El renderizado de mapas requiere View; las descargas de features, coberturas y archivos del proveedor requieren Download. Los descriptores privados devueltos por POST /access llevan un token de capa de corta duración que la pasarela valida en cada solicitud.

Las opciones de descarga del proveedor se anuncian en /downloads y se obtienen por su ID opaco anunciado en /downloads/:downloadId. Meratyn re-resuelve ese ID contra la lista vigente anunciada por el proveedor, restringe el destino a orígenes confiables configurados y solo reenvía validadores de rango y caché seguros.

Los endpoints sociales son propiedad de Meratyn para que los comentarios, la valoración de un usuario y los favoritos tengan un contrato consistente incluso cuando el backend de publicación no ofrece esas escrituras. Las valoraciones agregadas y la visibilidad de comentarios siguen igualmente la política View de la capa. Las rutas de features aceptan features GeoJSON y traducen operaciones de creación, actualización y eliminación en el límite del proveedor; requieren permiso Edit.

Modelo central

Un resumen de capa contiene:

  • id, slug, title, description
  • kind: vector, raster, tiles, multidimensional, point-cloud o 3d
  • format y tipo de medio detectado
  • visibility: public, unlisted o private
  • status: draft, uploading, processing, published, failed o deleting
  • propietario y organización opcional
  • extensión, CRS, tamaño, marcas de tiempo, palabras clave y miniatura
  • resumen de capacidades del proveedor

PUT /api/layers/:id acepta los campos editables del resumen, incluido crs. Los valores CRS se normalizan a un identificador EPSG:<code> o CRS:84 y se sincronizan con el SRS declarado por el proveedor de publicación. Esto declara el sistema de coordenadas de origen; no transforma coordenadas almacenadas.

Los descriptores de servicio contienen un tipo, una URL controlada por Meratyn, un tipo de medio, pistas opcionales para la fuente MapLibre y un requisito de acceso. Los clientes deben seleccionar en este orden cuando corresponda:

  1. formato cloud nativo (PMTiles, COG, FlatGeobuf, GeoParquet, Zarr, COPC)
  2. teselas vectoriales/ráster
  3. WMS
  4. WFS para acceso editable a features, o WCS para datos ráster

Los descriptores directos añaden:

  • representation: identificador estable de la representación
  • access.mode: public o session
  • direct, preferred y rangeRequests
  • sizeBytes, mediaType y formato
  • opcionalmente sourceLayer y la variable Zarr

Los formatos directos actuales de objeto único son PMTiles, subidas COG con nombre (*.cog.tif, *.cog.tiff o *.cog), FlatGeobuf, GeoParquet, objetos Zarr, COPC/LAZ, payloads de 3D Tiles, glTF, GLB y Gaussian splats. Los almacenes Zarr de múltiples objetos y las jerarquías 3D Tiles/glTF pueden enviar un arreglo JSON relativePaths. La entrega de proyectos privados firma la URL raíz con una capacidad de proyecto y conserva esa capacidad para los archivos relativos validados solicitados por manifiestos. Se rechazan el path traversal, las rutas absolutas, las rutas duplicadas y los archivos hermanos no declarados.

Las subidas crudas de MBTiles devuelven 415; conviértalas a PMTiles antes de la publicación.

Los clientes deben hacer polling solo mientras la capa esté en uploading o processing, y detenerse tras un estado terminal. La interfaz de gestión incluida y el Catálogo usan un intervalo de tres segundos para esta actualización en vivo acotada.

Capacidades del proveedor

El objeto de capacidades describe lo que la fachada Meratyn puede hacer, no la lista de funcionalidades de un backend concreto. Meratyn es dueño de su catálogo estable, concesiones, versiones retenidas de reemplazo, comentarios, valoraciones por usuario, favoritos, registros de capas relacionadas, historial de auditoría y respaldo local de presentación. Usa operaciones del proveedor para publicación, metadatos ricos, entrega de mapas, descargas, estilos, descubrimiento de atributos y transacciones de features cuando están disponibles. La UI nunca debe inferir el soporte a partir del nombre de un proveedor.

Los metadatos, la política de acceso, la presentación de tabla y las ediciones de estilos se retienen en Meratyn antes de la sincronización opcional con el proveedor. Por lo tanto, una caída del proveedor no descarta un cambio ordinario de gestión. La reconciliación registra internamente la sincronización pendiente o divergente y expone solo un resumen saneado de desviación neutral respecto al proveedor.

POST /api/layers/:id/reconcile?repair=true realiza una comparación real y repara metadatos, permisos, propiedad, estado de flujo de trabajo, atributos, estilos, CRS y extensión del proveedor usando las reglas de propiedad documentadas de Meratyn. Un POST simple verifica sin reparar.

El catálogo del proveedor se importa de forma idempotente y se sincroniza cada cinco minutos en el despliegue Node (GEONODE_CATALOGUE_SYNC_INTERVAL_MS controla el intervalo). Los administradores también pueden ejecutar la sincronización explícitamente. Las identidades de usuario/grupo de GeoNode son mapeos sombra con contraseñas inutilizables; Meratyn sigue siendo la autoridad de inicio de sesión y membresía.

La creación schema-first acepta un esquema de campos, restricciones, tipo de geometría, CRS y features GeoJSON iniciales. Valida restricciones de obligatoriedad, unicidad, tipo, rango numérico y patrón seguro antes de la publicación. El upsert masivo reutiliza el esquema almacenado para la preflight GeoJSON, envía el contrato nativo action=upsert de GeoNode y expone la ejecución asíncrona a través de provider-jobs. Los informes de validación de GeoNode permanecen como activos de recursos complementarios.

Los documentos de GeoNode usan su gestor de recursos de documento. Los activos complementarios, la importación de metadatos XML ISO, los enlaces de metadatos generados, la aprobación de publicación y el harvesting WMS/GeoNode/ArcGIS se exponen a través de la misma fachada Meratyn. La configuración y moderación del harvesting remoto requieren un administrador de Meratyn.

Una operación del proveedor no disponible devuelve una respuesta estructurada 501 con una clave de capacidad y una explicación legible. La autenticación/autorización, la validación, el conflicto, la caída del proveedor y el fallo de importación continúan siendo errores distintos.

Seguridad de subida

Los despliegues deben imponer tamaño de solicitud, ratio de expansión de archivos, cantidad de miembros, path traversal, concordancia entre firma y extensión de archivo, y cuota por cuenta. Los orígenes se almacenan provisionalmente bajo claves generadas; los nombres de archivo del usuario son metadatos, nunca rutas de sistema de archivos. Los despliegues de producción deberían añadir análisis de malware antes de que un worker de ingesta abra el archivo.

Las subidas multipart son adecuadas para la vertical local. El almacenamiento de objetos de producción debería añadir sesiones de subida reanudable y transferencia multipart directa para que los ráster grandes no pasen por un único proceso Node ni permanezcan en memoria.

Uso y auditoría

El almacenamiento directo se reserva atómicamente contra la cuota existente por usuario de Meratyn antes de escribir un objeto. Un almacenamiento fallido revierte la reserva, la eliminación la libera, y el recálculo de almacenamiento del administrador incluye los activos de capas alojadas.

GET /api/layers/:id/usage informa bytes de origen, derivados, versión y totales, la cuota de la cuenta, el conteo de descargas y la hora del último acceso. GET /api/layers/:id/audit registra eventos de subida, publicación, metadatos, permisos, atributos, estilos, sesión de acceso, descarga, actualización y eliminación. La eliminación de una capa retiene el registro de auditoría con una clave foránea de capa vaciada.