Leggere la documentazione API
Trasforma qualsiasi voce di documentazione API in un comando curl funzionante
⏱ Stima ~7 min
01 · Leggi
La competenza non è memorizzare le API. È saper leggere qualsiasi documentazione API e trasformarla in una richiesta funzionante in 2 minuti.
Ogni API ha la sua documentazione. Il formato varia, ma la struttura è sempre la stessa: - Method + path — che richiesta mandare - Path parameter — valori incorporati nel percorso URL - Query parameter — filtri e opzioni opzionali - Request body — cosa mandare in JSON per POST/PUT - Response — cosa riceverai
Punti chiave
- I path parameter come {owner} vanno sostituiti direttamente nel percorso URL
- I query parameter vanno dopo ? — quelli senza "required" sono opzionali
- I campi del corpo della richiesta per POST/PUT si mandano con -d '{...}'
- Guarda sempre prima la sezione "Authentication" (autenticazione) della documentazione
02 · Esempio di codice
Leggiamo insieme una voce reale della documentazione API di GitHub.
Voce della documentazione API
GET /repos/{owner}/{repo}/issues
Path parameters:
owner (string, required) — account owner of the repository
repo (string, required) — name of the repository
Query parameters:
state (string) — "open", "closed", or "all" — default: "open"
labels (string) — comma-separated label names
per_page (integer) — results per page, max 100, default 30
page (integer) — page number of results
Response: Array of issue objects
Tradotta in comando curl
# Get all CLOSED issues for facebook/react, 10 per page
curl "https://api.github.com/repos/facebook/react/issues?state=closed&per_page=10"
Il processo di traduzione: 1. Method = GET → nessun flag -X necessario 2. Base URL = https://api.github.com 3. Path = /repos/{owner}/{repo}/issues → {owner} diventa facebook, {repo} diventa react 4. Query param = ?state=closed&per_page=10 5. I repo pubblici non richiedono autenticazione
03 · Pratica reale
Prova tu. Esegui questo comando per recuperare le issue chiuse di facebook/react.
curl "https://api.github.com/repos/facebook/react/issues?state=closed&per_page=5"
04 · Completa
La documentazione API dice GET /repos/{owner}/{repo}/commits. Per recuperare i commit del repo torvalds/linux, il path URL sarà: /repos/___/linux/commits
05 · Pratica reale
Ora metti tutto insieme. Traduci questa voce di documentazione in un comando curl completo: GET /repos/{owner}/{repo}/commits Query: author (username GitHub), per_page (massimo 100) Compito: recupera i 5 commit più recenti di torvalds/linux, senza filtrare per autore.
curl "https://api.github.com/repos/torvalds/linux/commits?per_page=5"
06 · Quiz
La documentazione API dice: GET /users/{userId}/orders?status=pending&limit=50. Vuoi recuperare gli ordini dell'utente con ID 42, con stato pending e limite di 10. Qual è il path corretto?
- /users?userId=42/orders?status=pending&limit=10
- /users/{42}/orders?status=pending&limit=10
- /users/42/orders?status=pending&limit=10
- /users/42/orders&status=pending&limit=10
07 · Completa
Quando la documentazione API dice GET /repos/{owner}/{repo}/commits, le parti tra parentesi graffe come {owner} si chiamano _____ parameter.
Altre lezioni di questo capitolo
⚠ L'esperienza interattiva completa richiede JavaScript. Attivalo e ricarica la pagina.
※ Questo è un progetto educativo indipendente — non è un prodotto ufficiale di Anthropic. Claude™ è un marchio di Anthropic, PBC.