# Documentazione API di Skillsail

Documentazione API di Skillsail: descrizione OpenAPI, errori API strutturati, gestione delle versioni e politica di deprecazione per agenti e client HTTP.

Questa documentazione sull’API di Skillsail descrive la versione **1**. La descrizione OpenAPI è disponibile [all’indirizzo https://skillsail.com/openapi.json](https://skillsail.com/openapi.json). La creazione dei corsi non è una raccolta di risorse REST: gli agenti creano e modificano i moduli tramite il [server MCP di Skillsail](/it/documentazione/mcp/panoramica) all’indirizzo `https://skillsail.com/mcp`.

## Specifiche OpenAPI

`GET https://skillsail.com/openapi.json` Restituisce JSON OpenAPI 3.1. Comprende:

- `GET /api/health` — accessibilità del servizio
- `GET /openapi.json` — questo documento OpenAPI
- `GET /.well-known/oauth-protected-resource/mcp` — Metadati delle risorse protette da OAuth
- `POST /mcp` — trasporto MCP autenticato di Skillsail

Documenti correlati redatti da persone: [risorse per sviluppatori Skillsail](/it/documentazione/sviluppatori) e [istruzioni di autenticazione Skillsail](https://skillsail.com/auth.md).

## Gestione delle versioni

Invia l’intestazione opzionale `Skillsail-Api-Version: 1`. Se l’intestazione viene omessa, Skillsail fornisce la versione v1. L’attuale `info.version` nel documento OpenAPI è `1.0.0`.

L'endpoint MCP rimane `/mcp`. I client MCP devono leggere la versione del protocollo dalla [scheda del server MCP di Skillsail](https://skillsail.com/.well-known/mcp.json) anziché dal prefisso del percorso REST.

Non dare per scontato che l’URL `/v2` sia definitivo finché Skillsail non ne pubblicherà uno in questo documento e su OpenAPI.

## Errori API strutturati

Gli errori di discovery REST seguono lo standard RFC 9457 `application/problem+json`. `GET /openapi.json` utilizza questo modello quando la discovery non è disponibile. Ogni oggetto che indica un problema include:

- `type` — URI che identifica la classe del problema
- `title` — riassunto breve e chiaro
- `status` — Codice di stato HTTP
- `detail` — messaggio leggibile da una persona
- `code` — codice di errore Skillsail leggibile da macchina

Esempio:

```json
{
  "type": "https://skillsail.com/docs/api#not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "This URL is not a Skillsail API resource.",
  "code": "not_found"
}
```

I metadati delle risorse protette da OAuth (`/.well-known/oauth-protected-resource/mcp`) utilizzano il formato JSON di OAuth, non problem+json. Un’interruzione della configurazione restituisce `503` `application/json` :

```json
{
  "error": "temporarily_unavailable",
  "error_description": "OAuth metadata is temporarily unavailable"
}
```

I suffissi sconosciuti sul percorso `/.well-known/oauth-protected-resource/mcp` restituiscono `404` con un corpo `text/plain` contenente `Not found`.

Il trasporto HTTP MCP su `POST /mcp`:

- Intestazione `Authorization` assente: `401` con il corpo vuoto e `WWW-Authenticate` (`resource_metadata`, non `error=`). Analizza il JSON solo quando `Content-Type` è `application/json`.
- Token di portatore non valido o mal formato: `401` JSON `{ "error": "invalid_token", "error_description": "..." }`
- Token valido senza autorizzazione: `403` JSON `{ "error": "insufficient_scope", "error_description": "..." }`
- Interruzione del servizio di autenticazione: `503` JSON `{ "error": "temporarily_unavailable", "error_description": "..." }` con `Retry-After`

## Deprecazione

Quando un’operazione o una rappresentazione è deprecata, le risposte includono:

- `Deprecation: @1688169599` — Campo strutturato "Date" (timestamp Unix) secondo RFC 9745. Non si tratta del valore booleano " `true`".
- `Sunset` con una data HTTP (RFC 8594)

Le modifiche che comportano incompatibilità vengono annunciate almeno 90 giorni prima della data di fine supporto. Le modifiche aggiuntive e retrocompatibili potrebbero essere incluse nella v1 senza una nuova versione. Dopo la fine del supporto, Skillsail potrebbe rimuovere la funzionalità.

Le risposte REST riuscite potrebbero riportare `Skillsail-Api-Version: 1`.

## Correlati

- [Risorse per gli sviluppatori di Skillsail](/it/documentazione/sviluppatori)
- [Server MCP di Skillsail](/it/documentazione/mcp/panoramica)
- [Documento OpenAPI](https://skillsail.com/openapi.json)