Vai al contenuto principale

Preventivo in 24 ore

N. Verde
Analisi Legionella Italia
Preventivo
REST API · v1

API DOCUMENTATION

Public REST endpoints for Legionella incidence data and developer integrations (webhook subscriptions, delivery logs). All endpoints respond application/json, are CORS-enabled, and rate-limited per IP.

Authentication

  • Public endpoints (/api/v1/*, /api/sviluppatori/*) — no auth required. Rate-limited per IP.
  • Admin endpoints — Authorization: Bearer $ADMIN_API_SECRET. 404 if missing/invalid (security through obscurity).
  • Webhook subscriber verification — verify each delivery via HMAC SHA-256: signature == HMAC(secret, raw_body). Header X-123Legionella-Signature: sha256=….

Endpoints

GET/api/v1/legionella/regionipublic

List of all 20 Italian regions with cases, incidence per 100k, YoY change.

Example request

curl https://123legionella.com/api/v1/legionella/regioni

Response (sample)

{
  "meta": { "license": "CC BY 4.0", "version": "v1" },
  "count": 20,
  "data": [
    {
      "regione": "Lombardia",
      "slug": "lombardia",
      "popolazione": 9985000,
      "casiAnnoCorrente": 612,
      "incidenzaPer100k": 6.13,
      "variazioneYoY": 0.12
    }
  ]
}
POST/api/sviluppatori/webhook-subscribepublic

Register a new webhook subscription. Returns a one-time HMAC secret used to verify payload signatures.

Example request

curl -X POST https://123legionella.com/api/sviluppatori/webhook-subscribe \
  -H "Content-Type: application/json" \
  -d '{
    "endpointUrl": "https://your-app.com/webhook",
    "contactEmail": "dev@your-app.com",
    "events": ["lead.created","order.paid"]
  }'

Response (sample)

{
  "ok": true,
  "id": 42,
  "endpointUrl": "https://your-app.com/webhook",
  "events": ["lead.created","order.paid"],
  "secret": "a1b2c3...",
  "note": "Store this secret securely — won't be shown again."
}
POST/api/sviluppatori/webhook-testpublic

Trigger a test webhook delivery to ALL subscriptions listening for the given event.

Example request

curl -X POST https://123legionella.com/api/sviluppatori/webhook-test \
  -H "Content-Type: application/json" \
  -d '{"event":"lead.created"}'

Response (sample)

{
  "ok": true,
  "event": "lead.created",
  "sent": 1,
  "failed": 0,
  "skipped": 0
}
GET/api/admin/webhook-deliveriesbearer admin

Admin-only: list recent webhook delivery attempts with status, response code, retry count.

Example request

curl https://123legionella.com/api/admin/webhook-deliveries \
  -H "Authorization: Bearer $ADMIN_API_SECRET"

Response (sample)

{
  "ok": true,
  "count": 50,
  "deliveries": [
    { "id": 1, "event_type": "lead.created", "status": "delivered",
      "response_status": 200, "retry_count": 0 }
  ]
}

Versioning policy

  • • URL-versioned: /api/v1/…. Breaking changes ship under v2 only.
  • • Additive changes (new fields, new optional params) are non-breaking and ship under the current version.
  • • Deprecation: at least 6 months notice via blog + Sunset response header.
  • • Webhook payload schema versioned via X-123Legionella-Schema-Version (currently 1).