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.11 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:

@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:

Strumento	Audience	Scopo
OpenMetadata	Data operators interni (WP2)	Governance, lineage, data quality
CKAN	Pubblico 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

• ← Torna alla Home
• WP2 - Data Lake - Fonte dati per API e CKAN
  • Architettura Dual-Catalog (OpenMetadata + CKAN)
• WP3 - Algoritmo SLO - Dati SLO da esporre
• WP5 - Simulatore - Integrazione risultati simulazioni

---

Autore: Guglielmo Celata - Fondazione Gran Sasso Tech