API di MySea (v1)
REST e JSON, prefisso /api/v1/. Documentazione interattiva: /api/v1/documentazione/ (Swagger UI
servita dal portale); schema OpenAPI 3: /api/v1/schema/.
Autenticazione
- Chiave personale: profilo → «Chiave per le API». Intestazione
Authorization: Token <chiave>. La chiave agisce come la persona; si vede una volta sola e si può rigenerare o revocare. - Sessione del browser, per chi è già entrato nel portale.
- Scrivere (POST, PATCH, DELETE) richiede l'email confermata.
- Limiti: 60 richieste all'ora senza chiave, 2000 con la chiave.
- Solo HTTPS in produzione. Risposte paginate (
count,next,previous,results), 50 per pagina. - Date in ISO 8601.
Endpoint
| metodo | percorso | cosa |
|---|---|---|
| GET | /api/v1/stato/ |
nome del servizio e versione (pubblico) |
| GET | /api/v1/io/ |
chi sono: persona della chiave, con il profilo |
| GET, POST | /api/v1/logbook/ |
i miei logbook; POST ne crea uno (titolo, attivita, visibilita, descrizione) |
| GET, PATCH, DELETE | /api/v1/logbook/{id}/ |
un logbook (leggere se visibile, modificare se mio) |
| GET, POST | /api/v1/logbook/{id}/uscite/ |
le uscite; POST aggiunge un'uscita (campi della scheda) |
| GET, PATCH, DELETE | /api/v1/uscite/{id}/ |
un'uscita, con sito, tuffi e specie avvistate |
| GET | /api/v1/manualistica/{lingua}/ |
catalogo dei manuali |
| GET | /api/v1/manualistica/{lingua}/{area}/{nome}/ |
pagine e ancore stabili di un manuale |
Visibilità: si leggono i propri logbook e quelli che altri hanno reso visibili «a chi è iscritto». Il Manuale Istruttore risponde 403 a chi non è istruttore.
Esempio
curl -H "Authorization: Token $CHIAVE" https://myblusea.com/api/v1/logbook/
curl -H "Authorization: Token $CHIAVE" -H "Content-Type: application/json" \
-d '{"data":"2026-09-21","attivita":"apnea","profondita_max_m":"15.0"}' \
https://myblusea.com/api/v1/logbook/<id>/uscite/
Collegamenti
- HYDRA (esaweb.net e le altre): collegamento degli account con OAuth, in
api-hydra.md. - Computer da immersione (Garmin, Suunto): più avanti. Prima l'import di file UDDF, Subsurface XML e
FIT, senza accordi con i produttori; poi le integrazioni OAuth dei produttori, che richiedono un accordo
aziendale. Vedi
logbook.md.
Versioni
Cambiamenti incompatibili solo con un nuovo prefisso (/api/v2/). Novità in CHANGELOG.md.