ALLEGATO G - API di esempio

G.1 Principi

Le API dovranno essere:

• versionate;
• documentate;
• accessibili tramite HTTPS;
• coerenti nei nomi e nelle strutture;
• dotate di paginazione;
• accompagnate da filtri;
• conformi a politiche di sicurezza e limitazione delle richieste;
• predisposte per formati aperti;
• compatibili, ove pertinente, con modelli semantici e geografici.

G.2 Base URL di esempio

https://api.salernoopenheritage.example/v1/

Il dominio utilizzato è puramente dimostrativo.

G.3 Endpoint principali

GET /beni
GET /beni/{id}

GET /luoghi
GET /luoghi/{id}

GET /persone
GET /persone/{id}

GET /organizzazioni
GET /organizzazioni/{id}

GET /documenti
GET /documenti/{id}

GET /media
GET /media/{id}

GET /eventi
GET /eventi/{id}

GET /percorsi
GET /percorsi/{id}

GET /collezioni
GET /collezioni/{id}

GET /dataset
GET /dataset/{id}

POST /contributi
GET /contributi/{id}

G.4 Esempio di richiesta

GET /v1/beni?tipologia=edificio-storico&comune=salerno&page=1&limit=20

G.5 Esempio di risposta

{
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 125
  },
  "data": [
    {
      "id": "bene-123",
      "denominazione": "Esempio di edificio storico",
      "tipologia": {
        "id": "edificio-storico",
        "label": "Edificio storico"
      },
      "luogo": {
        "id": "luogo-45",
        "denominazione": "Salerno"
      },
      "coordinate": {
        "type": "Point",
        "coordinates": [14.0000, 40.0000]
      },
      "licenza": "CC BY 4.0",
      "ultima_modifica": "2026-08-05T08:00:00+02:00"
    }
  ],
  "links": {
    "self": "/v1/beni?page=1&limit=20",
    "next": "/v1/beni?page=2&limit=20"
  }
}

G.6 Dettaglio di un bene

GET /v1/beni/bene-123

{
  "id": "bene-123",
  "denominazione": "Esempio di bene culturale",
  "descrizione": "Descrizione completa della risorsa.",
  "tipologia": "Edificio storico",
  "luoghi": [
    {
      "id": "luogo-45",
      "denominazione": "Salerno"
    }
  ],
  "documenti": [
    {
      "id": "documento-78",
      "titolo": "Documento storico di esempio"
    }
  ],
  "media": [
    {
      "id": "media-90",
      "tipo": "immagine",
      "titolo": "Veduta storica"
    }
  ],
  "eventi": [],
  "percorsi": [
    {
      "id": "percorso-12",
      "titolo": "Percorso storico di esempio"
    }
  ],
  "fonti": [
    {
      "tipo": "bibliografia",
      "riferimento": "Riferimento bibliografico di esempio"
    }
  ],
  "licenza": "CC BY 4.0",
  "versione": 3
}

G.7 Ricerca geografica

GET /v1/beni?bbox=13.95,40.60,14.10,40.75

oppure:

GET /v1/beni?lat=40.68&lon=14.76&radius=1000

G.8 Ricerca temporale

GET /v1/eventi?dal=2026-09-01&al=2026-09-30

G.9 Percorsi

GET /v1/percorsi/percorso-12

{
  "id": "percorso-12",
  "titolo": "Percorso storico di esempio",
  "descrizione": "Itinerario dimostrativo.",
  "tipologia": "storico",
  "tappe": [
    {
      "ordine": 1,
      "tipo": "bene",
      "id": "bene-123"
    },
    {
      "ordine": 2,
      "tipo": "luogo",
      "id": "luogo-46"
    }
  ],
  "geometria": {
    "type": "LineString",
    "coordinates": [
      [14.0000, 40.0000],
      [14.0100, 40.0100]
    ]
  }
}

G.10 Inserimento di un contributo

POST /v1/contributi
Content-Type: application/json
Authorization: Bearer <token>

{
  "tipo": "correzione",
  "risorsa": {
    "tipo": "bene",
    "id": "bene-123"
  },
  "descrizione": "Proposta di aggiornamento della datazione.",
  "fonti": [
    {
      "tipo": "bibliografia",
      "riferimento": "Fonte documentaria di esempio"
    }
  ]
}

G.11 Risposta al contributo

{
  "id": "contributo-501",
  "stato": "proposto",
  "data_creazione": "2026-08-05T10:00:00+02:00",
  "links": {
    "self": "/v1/contributi/contributo-501"
  }
}

G.12 Codici di stato indicativi

G.13 Versionamento

L'API dovrà indicare la versione nel percorso o attraverso una strategia equivalente:

/v1/beni
/v2/beni

Le modifiche incompatibili dovranno determinare una nuova versione principale, accompagnata da documentazione e periodo di transizione.

G.14 Documentazione

La documentazione tecnica dovrebbe essere pubblicata mediante una specifica aperta, preferibilmente OpenAPI, comprendente:

• endpoint;
• parametri;
• schemi;
• autenticazione;
• esempi;
• codici di errore;
• limiti;
• versioni;
• cronologia delle modifiche.