AI Agents · Lezione

Fondamenti delle REST API per sviluppatori di agenti

Metodi HTTP, codici di stato, header e formato JSON delle richieste e risposte

Lezione 1 di 413 passaggi

Fondamenti delle REST API per sviluppatori di agenti è una lezione AI Agents gratuita su CoddyKit. Questa è la lezione 1 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento AI Agents, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso AI Agents include 4 lezioni in totale.

Che cos'è una richiesta HTTP?

Ogni agente che si connette a un servizio esterno utilizza HTTP, il linguaggio del web. Una richiesta HTTP ha tre componenti fondamentali: un metodo, un URL e, facoltativamente, intestazioni e un corpo.

Consideri il metodo come un verbo che indica al server l'operazione da eseguire e l'URL come l'indirizzo della risorsa.

import requests

# A simple GET request to a public API
response = requests.get('https://api.example.com/users')
print(response.status_code)  # 200
print(response.text)          # raw JSON string

GET — Recupero dei dati

GET recupera dati da un server. Non dovrebbe mai modificare nulla. Gli agenti utilizzano GET per leggere i profili degli utenti, recuperare gli elenchi di attività o ottenere i dati di configurazione.

Può passare i parametri nell'URL come stringa di query utilizzando l'argomento params.

import requests

# Fetch users filtered by role
params = {'role': 'admin', 'page': 1, 'limit': 10}
response = requests.get(
    'https://api.example.com/users',
    params=params
)
# URL becomes: /users?role=admin&page=1&limit=10
data = response.json()
print(data['users'])

POST — Creazione di risorse

POST invia dati al server per creare una nuova risorsa. Gli agenti utilizzano POST per inviare attività, messaggi o attivare azioni. I dati vengono inseriti nel corpo della richiesta in formato JSON.

Imposti sempre l'intestazione Content-Type: application/json: la maggior parte delle API la richiede.

import requests
import json

payload = {
    'title': 'Research competitors',
    'assignee': 'agent-001',
    'priority': 'high'
}

response = requests.post(
    'https://api.example.com/tasks',
    json=payload  # sets Content-Type automatically
)
print(response.status_code)  # 201 Created
new_task = response.json()
print('Created task ID:', new_task['id'])

PUT e PATCH — Aggiornamento dei dati

PUT sostituisce un'intera risorsa con nuovi dati. PATCH aggiorna solo campi specifici. Gli agenti utilizzano PUT quando dispongono dell'oggetto completo aggiornato e PATCH per modifiche parziali, ad esempio l'aggiornamento dello stato di un'attività.

import requests

task_id = '42'

# PATCH: only update the status field
response = requests.patch(
    f'https://api.example.com/tasks/{task_id}',
    json={'status': 'completed'}
)
print(response.status_code)  # 200

# PUT: replace the whole task object
full_task = {
    'title': 'Research competitors',
    'assignee': 'agent-001',
    'priority': 'low',
    'status': 'completed'
}
response = requests.put(
    f'https://api.example.com/tasks/{task_id}',
    json=full_task
)
print(response.status_code)  # 200

DELETE — Rimozione di risorse

DELETE rimuove una risorsa dal server. Gli agenti utilizzano DELETE per eliminare dati temporanei, rimuovere attività elaborate o annullare processi pianificati. La maggior parte delle richieste DELETE non ha un corpo.

Una richiesta di eliminazione completata correttamente restituisce in genere 204 No Content: la risposta non contiene alcun corpo.

import requests

task_id = '42'

response = requests.delete(
    f'https://api.example.com/tasks/{task_id}'
)

if response.status_code == 204:
    print('Task deleted successfully')
elif response.status_code == 404:
    print('Task not found — already deleted?')
else:
    print('Unexpected status:', response.status_code)

Codici di stato: 2xx — Operazione riuscita

I codici di stato indicano all'agente se una richiesta è riuscita o meno. L'intervallo 2xx indica un'operazione riuscita:

200 OK — GET/PUT/PATCH ha restituito dati
201 Created — POST ha creato una nuova risorsa
204 No Content — DELETE è riuscito, senza corpo restituito

Verifichi sempre il codice di stato prima di elaborare il corpo della risposta.

import requests

response = requests.post(
    'https://api.example.com/tasks',
    json={'title': 'New task'}
)

if response.status_code == 201:
    task = response.json()
    print('Created:', task['id'])
elif response.status_code == 200:
    print('Updated existing resource')
else:
    print('Unexpected code:', response.status_code)

Codici di stato: 4xx — Errori del client

Gli errori 4xx indicano che l'agente ha inviato una richiesta non valida. I più comuni sono:

400 Bad Request — JSON non valido o campo obbligatorio mancante
401 Unauthorized — chiave API mancante o non valida
404 Not Found — la risorsa non esiste
429 Too Many Requests — limite di frequenza superato

In questi casi l'agente deve correggere la richiesta, non riprovare alla cieca.

import requests

response = requests.get(
    'https://api.example.com/tasks/9999',
    headers={'Authorization': 'Bearer YOUR_KEY'}
)

if response.status_code == 401:
    print('AUTH ERROR: Check your API key')
elif response.status_code == 404:
    print('Task not found')
elif response.status_code == 429:
    retry_after = response.headers.get('Retry-After', 60)
    print(f'Rate limited. Wait {retry_after}s')
elif response.status_code == 400:
    print('Bad request:', response.json().get('error'))

Codici di stato: 5xx — Errori del server

Gli errori 5xx indicano che si è verificato un problema sul server: l'agente non ha commesso errori. I più comuni sono:

500 Internal Server Error — bug o arresto anomalo del server
502 Bad Gateway — errore del servizio upstream
503 Service Unavailable — server sovraccarico o non disponibile

È possibile riprovare senza rischi dopo una breve attesa.

import requests
import time

def get_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        if response.status_code < 500:
            return response  # success or client error
        wait = 2 ** attempt
        print(f'Server error {response.status_code}, retrying in {wait}s...')
        time.sleep(wait)
    return response  # return last response after retries

Intestazioni della richiesta

Le intestazioni trasportano metadati con ogni richiesta. Le più importanti per gli agenti sono:

Content-Type: application/json — indica al server che il corpo è in formato JSON
Authorization: Bearer TOKEN — autentica la richiesta
Accept: application/json — indica al server che si prevede di ricevere JSON
User-Agent — identifica il client (alcune API lo richiedono)

import requests

headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer sk-proj-abc123xyz',
    'Accept': 'application/json',
    'User-Agent': 'MyAgent/1.0'
}

response = requests.post(
    'https://api.example.com/analyze',
    headers=headers,
    json={'text': 'Analyze this document'}
)

print(response.json())

Corpo JSON della richiesta e della risposta

La maggior parte delle API moderne scambia dati in formato JSON. Per l'invio, utilizzi json=payload nelle richieste: il contenuto viene serializzato e le intestazioni vengono impostate automaticamente. Alla ricezione, chiami response.json() per analizzare il corpo e convertirlo in un dict Python.

Verifichi sempre che le chiavi previste esistano prima di accedervi.

import requests

# Send JSON body
response = requests.post(
    'https://api.example.com/summarize',
    json={
        'content': 'Long article text here...',
        'max_length': 150,
        'format': 'bullet_points'
    }
)

# Parse JSON response
result = response.json()

# Always check keys exist
summary = result.get('summary', 'No summary returned')
tokens_used = result.get('usage', {}).get('total_tokens', 0)

print('Summary:', summary)
print('Tokens used:', tokens_used)

Mettere tutto insieme

Un agente ben scritto racchiude le chiamate API in una funzione di supporto chiara, che gestisce la selezione del metodo, le intestazioni corrette, il controllo del codice di stato e l'analisi del JSON. In questo modo ogni interazione con l'API è coerente e facile da sottoporre a debug.

Utilizzi un oggetto Session per riutilizzare le connessioni e condividere le intestazioni tra più richieste.

import requests

class APIClient:
    def __init__(self, base_url, api_key):
        self.base_url = base_url
        self.session = requests.Session()
        self.session.headers.update({
            'Authorization': f'Bearer {api_key}',
            'Content-Type': 'application/json',
            'Accept': 'application/json'
        })

    def get(self, path, params=None):
        r = self.session.get(f'{self.base_url}{path}', params=params)
        r.raise_for_status()
        return r.json()

    def post(self, path, payload):
        r = self.session.post(f'{self.base_url}{path}', json=payload)
        r.raise_for_status()
        return r.json()

# Usage
client = APIClient('https://api.example.com', 'sk-proj-abc123')
tasks = client.get('/tasks', params={'status': 'open'})
new_task = client.post('/tasks', {'title': 'Write report'})

Verifica rapida: metodi HTTP

Verifichi la Sua comprensione dei metodi HTTP e dei codici di stato.

Rispondi nella lezione interattiva

Riepilogo dei fondamenti di HTTP

Ora conosce le basi di HTTP su cui si basa ogni agente:

GET recupera, POST crea, PUT/PATCH aggiorna, DELETE rimuove
2xx = operazione riuscita, 4xx = errore dell'agente, 5xx = errore del server
Le intestazioni trasportano l'autenticazione (Authorization: Bearer) e il formato (Content-Type: application/json)
Utilizzi response.json() per analizzare il corpo e .get() per accedere ai campi in modo sicuro
Un oggetto Session condivide intestazioni e connessioni tra le richieste

Con queste basi consolidate, può connettere con sicurezza il Suo agente a qualsiasi API REST.

Gratis per iniziare

Impara AI Agents con un tutor IA — gratis

Scrivi ed esegui vero codice nel tuo browser, ricevi aiuto istantaneo da un tutor IA disponibile 24/7, e riprendi da dove hai lasciato sul web o nell'app.

Corsi: 60
Lezioni: 239

Inizia a imparare gratis Visualizza il corso completo

Domande Frequenti

La lezione «Fondamenti delle REST API per sviluppatori di agenti» è gratuita?

Sì — il testo completo di «Fondamenti delle REST API per sviluppatori di agenti» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso AI Agents, passa a CoddyKit PRO. Il corso AI Agents include 4 lezioni in totale.

Cosa imparerò in «Fondamenti delle REST API per sviluppatori di agenti»?

Metodi HTTP, codici di stato, header e formato JSON delle richieste e risposte Eserciti AI Agents con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.

Ho bisogno di esperienza per iniziare AI Agents?

Non è richiesta alcuna esperienza precedente. AI Agents su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 1 di 4.

Quanto tempo richiede la lezione «Fondamenti delle REST API per sviluppatori di agenti»?

La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.

Posso scrivere ed eseguire codice in questa lezione AI Agents?

Sì. Ogni lezione AI Agents include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.

Tutte le lezioni di questo corso

Fondamenti delle REST API per sviluppatori di agenti
Autenticazione: API key e OAuth
Gestione delle risposte e degli errori delle API
Rate limiting e logica di retry

← Torna a AI Agents