Progetto MAPS

Appearance

WP6: API e Pubblicazione Open Data ​

Work Package 6: API REST e catalogo open data secondo standard DCAT-AP_IT

Panoramica ​

Sviluppo di API REST v2 per accesso programmatico ai dati SLO e pubblicazione di dataset open data secondo lo standard europeo DCAT-AP_IT.

Obiettivi:

  • Democratizzare l'accesso ai dati MAPS
  • Supportare sviluppo applicazioni terze
  • Conformità standard open data europei
  • Integrazione con portali open data nazionali

Timeline ​

  • Mesi: M20-M24
  • Deadline finale: 31/03/2027

Deliverable Previsti ​

D6.1 - Specifiche API e Documentazione OpenAPI ​

Documento di progettazione API:

  • Specifiche OpenAPI 3.1
  • Autenticazione e autorizzazione
  • Rate limiting e quote
  • Esempi di integrazione

D6.2 - Implementazione API v2 ​

Implementazione API REST con:

  • Backend FastAPI/Flask
  • Autenticazione JWT
  • Documentazione interattiva (Swagger/Redoc)
  • Client libraries (Python, JavaScript)

D6.3 - Catalogo Open Data e Metadata DCAT-AP_IT ​

Pubblicazione dataset open data tramite CKAN:

  • Catalogo CKAN 2.10+ conforme DCAT-AP_IT
  • Metadata completi (lineage, qualità, licenze Creative Commons)
  • Harvesting automatico verso dati.gov.it
  • Portal open data dedicato user-friendly
  • API pubblica per download programmatico
  • Preview multi-formato (CSV, GeoJSON, Parquet)

Endpoint API Previsti ​

API REST v2 (FastAPI) ​

GET  /api/v2/slo                    # Lista Sistemi Locali Omogenei
GET  /api/v2/slo/{id}               # Dettaglio SLO
GET  /api/v2/comuni                 # Lista comuni con attributi
GET  /api/v2/comuni/{codice}        # Dettaglio comune
GET  /api/v2/isocrone/{codice}      # Isocrone accessibilità
GET  /api/v2/polarita               # Polarità territoriali
GET  /api/v2/datasets               # Catalogo dataset disponibili

CKAN API (Open Data) ​

CKAN espone automaticamente API standard per ogni dataset pubblicato:

# CKAN Action API (JSON)
GET  /api/3/action/package_list                    # Lista dataset
GET  /api/3/action/package_show?id={dataset_id}    # Metadata dataset
GET  /api/3/action/resource_show?id={resource_id}  # Metadata risorsa
GET  /api/3/action/datastore_search?resource_id={id}  # Query dati

# DCAT-AP_IT Endpoint (RDF/XML)
GET  /catalog.xml                                   # Catalogo DCAT-AP_IT completo
GET  /dataset/{dataset_id}.xml                     # Metadata DCAT singolo dataset

# CSW Harvesting (per dati.gov.it)
GET  /csw?request=GetCapabilities
GET  /csw?request=GetRecords&outputSchema=http://www.isotc211.org/2005/gmd

Pipeline di Pubblicazione ​

Workflow automatizzato Prefect:

python
@flow(name="publish-to-ckan")
def publish_open_data():
    """
    Pubblica dataset approvati da Gold layer a CKAN

    Steps:
    1. Query gold.open_data_approved (flag published=false)
    2. Export dataset (CSV, GeoJSON, Parquet)
    3. Generate DCAT-AP_IT metadata
    4. Upload to CKAN via API
    5. Update published=true flag
    6. Notify dati.gov.it harvester
    """

    approved_datasets = get_approved_datasets()

    for dataset in approved_datasets:
        # Export da PostgreSQL
        export_dataset(dataset)

        # Genera metadata DCAT-AP_IT
        metadata = generate_dcat_metadata(
            dataset,
            license="CC-BY-4.0",
            publisher="Fondazione Gran Sasso Tech",
            temporal_coverage="2010-2025",
            spatial_coverage="Italia"
        )

        # Upload to CKAN
        ckan_client.package_create(
            name=dataset.slug,
            title=dataset.title,
            notes=dataset.description,
            extras=metadata
        )

        # Mark as published
        mark_as_published(dataset.id)

Trigger:

  • Manuale: Approvazione dataset in OpenMetadata
  • Automatico: Schedule settimanale per dataset aggiornati

Architettura Dual-Catalog ​

Il progetto MAPS adotta un'architettura dual-catalog per separare governance interna e accesso pubblico:

StrumentoAudienceScopo
OpenMetadataData operators interni (WP2)Governance, lineage, data quality
CKANPubblico esterno (WP6)Catalogo open data, DCAT-AP_IT, dati.gov.it

Questa separazione garantisce:

  • Conformità contrattuale: CKAN soddisfa requisiti WP6 D6.3 out-of-the-box
  • Separation of concerns: Governance interna isolata da accesso pubblico
  • Standard compliance: DCAT-AP_IT nativo, integrazione dati.gov.it built-in
  • User experience: Portal ottimizzato per cittadini/ricercatori vs tool tecnico per data engineers

Workflow: Gold Layer → OpenMetadata (approvazione qualità) → CKAN (pubblicazione) → dati.gov.it (harvesting)

Stato ​

🚧 In preparazione - La documentazione sarà disponibile durante la fase di implementazione (M20-M24)

Collegamenti ​

Autore: Guglielmo Celata - Fondazione Gran Sasso Tech