Spearfishing Naples API

API pubblica, read-only e gratuita con i dati di spearfishingnaples.com: informazioni sul sito, pagine principali, attrezzatura per la pesca in apnea consigliata da Simone Ruggiero e guide del blog. Specifica completa: OpenAPI 3.1 (/openapi.json). Catalogo: /.well-known/api-catalog.

Autenticazione

Nessuna. Tutti gli endpoint sono pubblici e rispondono in JSON con CORS aperto.

Endpoint

  • GET /api/v1/info — chi siamo, zona, servizi, contatti
  • GET /api/v1/pages — pagine principali
  • GET /api/v1/equipment?lang=it|en — attrezzatura consigliata
  • GET /api/v1/equipment/{slug}?lang=it|en — un articolo di attrezzatura
  • GET /api/v1/articles?lang=it|en — guide del blog

Esempi

curl https://spearfishingnaples.com/api/v1/info
curl "https://spearfishingnaples.com/api/v1/equipment?lang=en"
curl https://spearfishingnaples.com/api/v1/equipment/omer-cayman-hf-90
curl -H "Accept: text/markdown" https://spearfishingnaples.com/

Rate limit

60 richieste al minuto per IP. Ogni risposta sotto /api/v1, errori compresi, include gli header IETF RateLimit-Policy e RateLimit. Oltre il limite: HTTP 429 con Retry-After.

RateLimit-Policy: "default";q=60;w=60
RateLimit: "default";r=59;t=60

Versioni e deprecazione

  • La versione principale è nel path: /api/v1. Ogni risposta riporta l'header API-Version.
  • La v1 è stabile: riceve solo modifiche compatibili (nuovi campi, nuovi endpoint).
  • Le modifiche incompatibili escono su /api/v2; la v1 resta attiva in parallelo.
  • Un endpoint da ritirare risponde con l'header Deprecation (RFC 9745) e con Sunset (RFC 8594) che indica la data di rimozione, con almeno 6 mesi di preavviso annunciati in questa pagina.

Errori

Gli errori sotto /api/* usano application/problem+json (RFC 9457) con i campi type, title, status, detail, code e resolution.

{
  "type": "https://spearfishingnaples.com/docs#errors",
  "title": "Not Found",
  "status": 404,
  "detail": "No equipment item with this slug.",
  "code": "equipment_not_found",
  "resolution": "List valid slugs with GET /api/v1/equipment."
}

Server MCP

Server MCP (Streamable HTTP, JSON-RPC 2.0) su https://spearfishingnaples.com/mcp, senza autenticazione. Tool read-only: get_info, list_pages, list_equipment, get_equipment, list_articles. Risorse: llms.txt, info e attrezzatura. Server card: /.well-known/mcp/server-card.json.

curl -X POST https://spearfishingnaples.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

claude mcp add --transport http spearfishingnaples https://spearfishingnaples.com/mcp

Markdown per agenti

Ogni pagina è disponibile in Markdown inviando Accept: text/markdown. Guida per LLM: /llms.txt. Mappa del sito: /sitemap.xml.