API e agenti AI — Studio Dentistico Di Mauro

I dati pubblici dello studio (recapiti, orari, trattamenti, pagine) sono disponibili in formato leggibile dalle macchine. L'API è in sola lettura e non permette di prenotare: per le prenotazioni si usa la pagina Contatti o il telefono.

Autenticazione

Nessuna. Tutti gli endpoint sono pubblici e rispondono in JSON (UTF-8).

Endpoint

  • GET /api/v1/info — Recapiti, orari, team e zone servite
  • GET /api/v1/treatments — Trattamenti offerti
  • GET /api/v1/pages — Pagine pubbliche del sito
  • GET /api/md?url=/percorso — una pagina del sito in markdown

Specifica completa: /openapi.json (OpenAPI 3.1) · catalogo: /.well-known/api-catalog

curl https://odontoiatriadimauro.it/api/v1/info curl https://odontoiatriadimauro.it/api/v1/treatments

Markdown

Ogni pagina del sito risponde in markdown se la richiesta invia l'header Accept: text/markdown (in alternativa si aggiunge ?format=md).

curl -H "Accept: text/markdown" https://odontoiatriadimauro.it/invisalign-nola

Rate limit

60 richieste ogni 60 secondi per indirizzo IP. Ogni risposta di /api/v1 include gli header IETF RateLimit-Policy (es. "default";q=60;w=60) e RateLimit (es. "default";r=59;t=60). Oltre il limite la risposta è 429 con Retry-After in secondi.

Versioning e deprecazione

La versione è nel path: /api/v1 è stabile e riceve solo modifiche compatibili (nuovi campi o nuovi endpoint). Una modifica incompatibile uscirà solo su /api/v2. Quando un endpoint viene deprecato, le sue risposte includono l'header Deprecation (RFC 9745) e l'header Sunset(RFC 8594) con la data di rimozione, che arriva almeno 6 mesi dopo l'annuncio. Oggi nessun endpoint è deprecato.

Errori

Gli errori sotto /api usano application/problem+json (RFC 9457) con i campi type, title, status, detail, code e resolution. Valori di code: not_found, rate_limited, invalid_path, upstream_error, method_not_allowed, internal_error.

{ "type": "https://odontoiatriadimauro.it/docs#errori", "title": "Not Found", "status": 404, "detail": "Nessun endpoint API corrisponde a /api/xyz.", "code": "not_found", "resolution": "Consulta https://odontoiatriadimauro.it/openapi.json per gli endpoint disponibili." }

Server MCP

Server Model Context Protocol (Streamable HTTP, sola lettura) su /mcp. Tool: get_studio_info, list_treatments, list_pages; risorse JSON leggibili con resources/read. Server card: /.well-known/mcp/server-card.json.

curl -X POST https://odontoiatriadimauro.it/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_studio_info","arguments":{}}}'

Per un client MCP da riga di comando: npx -y mcp-remote https://odontoiatriadimauro.it/mcp

Altre risorse