🌐 API & Protocol Documentation: OpenAPI & AsyncAPI

Principio: “An API is only as good as its documentation.”

::: info La documentazione delle interfacce di comunicazione definisce come i diversi moduli del sistema “parlano” tra loro. Utilizziamo standard aperti per generare documentazione interattiva che permetta di testare le chiamate senza scrivere codice client. :::

1. REST APIs: Lo standard OpenAPI (Swagger)

OpenAPI è il linguaggio standard per descrivere le REST API. Permette di definire endpoint, parametri di input, schemi di risposta e metodi di autenticazione.

Integrazione Automatica con FastAPI

Uno dei maggiori vantaggi di FastAPI (Python) è la generazione automatica dello schema OpenAPI partendo dai modelli Pydantic.

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Device(BaseModel):
    id: int
    name: str
    status: str = "offline"

@app.post("/devices/", status_code=201)
async def create_device(device: Device):
    """
    Registra un nuovo dispositivo IoT nel sistema.
    
    - **id**: Identificativo univoco hardware
    - **name**: Nome mnemonico del dispositivo
    - **status**: Stato iniziale (default: offline)
    """
    return device

• Accesso: Una volta avviato il server, la documentazione interattiva è disponibile a /docs (Swagger UI) o /redoc.

2. Event-Driven Systems: AsyncAPI

Mentre OpenAPI gestisce il paradigma “Richiesta/Risposta”, AsyncAPI è lo standard per i sistemi basati su messaggi (Publish/Subscribe), come quelli che utilizzano MQTT (fondamentale per Home Assistant e Zigbee2MQTT).

Elementi di AsyncAPI:

• Channels: I “topic” su cui viaggiano i messaggi (es. tele/sonoff/SENSOR).
• Messages: La struttura del payload (solitamente JSON).
• Bindings: Il protocollo utilizzato (MQTT, AMQP, WebSockets).

# Esempio concettuale di AsyncAPI per MQTT
channels:
  home/livingroom/temperature:
    publish:
      message:
        payload:
          type: object
          properties:
            temp:
              type: number
            humidity:
              type: number

📉 Architettura della Comunicazione (Mermaid)

graph LR
    CLIENT[Client / UI] -->|REST HTTP| API[FastAPI Server]
    API -->|CRUD| DB[(Database)]
    
    IOT[IoT Sensor] -->|MQTT Publish| BROKER[Mosquitto Broker]
    BROKER -->|MQTT Subscribe| API
    
    subgraph Documentation
        SWAG[Swagger UI - OpenAPI]
        ASYNC[AsyncAPI Doc]
    end
    
    API -.-> SWAG
    BROKER -.-> ASYNC

🛠️ Best Practices per API Professionali

1. Versioning: Includi sempre la versione nell’URL (es. /api/v1/devices). Questo evita di “rompere” i client esistenti quando effettui modifiche strutturali.
2. Status Codes Semantici: Usa correttamente i codici HTTP:
   • 200 OK: Successo.
   • 201 Created: Risorsa creata con successo.
   • 400 Bad Request: Errore di validazione input.
   • 401 Unauthorized: Autenticazione mancante.
   • 404 Not Found: Risorsa inesistente.
3. Schema Validation: Definisci sempre modelli di input/output rigorosi (Pydantic in Python, Struct/Classes in C++). Non accettare mai “JSON generico”.
4. Security Schemes: Documenta chiaramente se l’API richiede API-Key, OAuth2 o JWT Token.

Ultimo aggiornamento: {{UPDATE_DATE}} | Tags: #OpenAPI #Swagger #FastAPI #AsyncAPI #MQTT #REST