pygeoapi con PostGIS: filtros, paginación y CRS

Una API sobre PostGIS debe conservar identificadores, significado de filtros y coordenadas entre páginas. Conectar es apenas el inicio. Esta guía usa el conjunto assets del laboratorio de referencia: tabla lab.assets, clave asset_id y geometría geom en EPSG:4326.

La ruta CSV y la ruta PostgreSQL son superficies de verificación diferentes. Consulte en el laboratorio qué se ejecutó realmente antes de llamar probada a la configuración de base. Las instrucciones corresponden al proveedor documentado en pygeoapi 0.24.0, no a todas las versiones históricas.

Prepare la tabla de publicación

Compruebe identificadores únicos y no nulos, CRS y campos permitidos al usuario del servicio. En una copia desechable revise:

SELECT count(*) AS rows, count(DISTINCT asset_id) AS unique_ids,
       count(*) FILTER (WHERE geom IS NULL) AS missing_geometry,
       min(ST_SRID(geom)) AS min_srid,
       max(ST_SRID(geom)) AS max_srid
FROM lab.assets;

El laboratorio genera 10.000 registros con identificadores de texto estables. Para datos reales sustituya ese conteo por el manifiesto de importación. Mantenga el rol de base en lectura para una API pública de consulta. Que una versión del proveedor soporte transacciones no justifica habilitar escritura sin proceso y permisos propios.

Configure el proveedor

La referencia 0.24.0 describe dependencias y parámetros. En providers de la colección use datos reales de conexión y secretos inyectados por el despliegue. Este fragmento explica estructura; el laboratorio contiene configuración completa.

providers:
  - type: feature
    name: PostgreSQL
    data:
      host: postgis
      port: 5432
      dbname: geosat_lab
      user: api_reader
      password: ${PG_API_PASSWORD}
      search_path: [lab, public]
    id_field: asset_id
    table: assets
    geom_field: geom
    properties: [asset_id, asset_type, condition, district, inspected_on]

Defina la variable mediante el entorno del proceso; no pegue una contraseña real. properties expresa el esquema público. Una vista restringida de base añade otra frontera y reduce dependencia de la presentación de API. Regenerar OpenAPI y reiniciar forma parte del cambio.

Pruebe objetos, filtros y páginas

Empiece por /collections/assets?f=json y /collections/assets/queryables?f=json cuando esté expuesto. Los nombres y tipos consultables indican qué filtros existen. Solicite asset-00001 y un identificador inexistente. Verifique que los ceros del ID no se pierdan ni se sustituyan por posición de fila.

curl --fail --get 'http://localhost:5000/collections/assets/items' \
  --data-urlencode 'f=json' \
  --data-urlencode 'limit=10' \
  --data-urlencode 'district=D01'

Todos los objetos deben pertenecer a D01. Pruebe un valor ausente y espere una colección vacía, no todos los datos. Envíe un parámetro no soportado y documente si se rechaza o ignora. Aceptarlo silenciosamente puede hacer creer al consumidor que un filtro sí se aplicó.

Siga enlaces de paginación y compare el conjunto de IDs con SQL equivalente. No suponga orden estable de base. Si cambia la fuente durante extracción, paginar por desplazamientos puede omitir o duplicar; para una exportación reproducible use instantánea o mecanismo específico.

Verifique el CRS con coordenadas conocidas

Un consumidor GeoJSON normalmente espera longitud/latitud. No cambie la etiqueta de coordenadas proyectadas. Consulte una bbox pequeña con puntos conocidos y compare SQL. Si ofrece otros CRS, pruebe declaración de colección, representación y ejes según la documentación CRS.

Controle el costo de consultas

Tamaño de página y costo SQL son distintos. Contar todos los resultados puede ser costoso aunque solo devuelva diez. Revise configuración de conteo, índices y plan de consultas representativas. El total de conexiones depende también de cuántos procesos de API crean pools.

No exponga SQL arbitrario en parámetros. Limite propiedades filtrables y valide fechas, categorías y geometría. Mida combinaciones reales, como distrito más intervalo temporal: un índice útil para un filtro no acelera todos los demás.

Acepte el proveedor cuando esquema, IDs, errores, filtros, paginación y CRS funcionen desde el consumidor requerido, incluidos casos negativos. Registre versión, revisión de datos y conjuntos esperados. Continúe con controles de producción: TLS, límites, permisos, monitoreo y recuperación siguen siendo necesarios.