API Reference & Swagger

Questa sezione spiega come accedere alla reference completa delle API Homsai tramite Swagger UI e come utilizzarla in combinazione con la documentazione “wiki”.

---

Overview

La reference tecnica dettagliata degli endpoint (metodi, parametri, schemi request/response) è esposta tramite Swagger UI:

• URL ambiente v2:
  https://v2.api.homsai.app/swagger-ui/index.html#/

Swagger UI ti permette di:

• esplorare tutti gli endpoint raggruppati per “tag” (Auth, Plants, Devices, Sensors, ecc.);
• vedere in dettaglio path, query params, request body e response schema;
• provare le chiamate direttamente dal browser usando un token JWT valido.

---

Come usare Swagger UI

1. Apri nel browser:
   https://v2.api.homsai.app/swagger-ui/index.html#/
2. Autenticati (se richiesto) inserendo il tuo accessToken JWT nell’apposito campo “Authorize”.
3. Naviga i gruppi di endpoint (tag) nella sidebar:
   • Auth
   • Plants
   • Devices
   • Sensors
   • Sensor Types / Device Types
   • Load Signatures
   • Data Types Collects
   • Vendors
   • Energy Metrics & Forecasts
4. Per ogni endpoint puoi:
   • espandere il dettaglio;
   • leggere parametri e schema dei DTO;
   • usare “Try it out” per eseguire una chiamata di test.

Swagger è la fonte autorevole per il dettaglio dei contract (schema JSON), mentre le pagine wiki spiegano come e quando usare gli endpoint nei diversi casi d’uso.