Vuoi creare una API REST, ma trovare solo la teoria astratta sul "trasferimento di stato" e sui "protocolli"? Cambiamo la situazione. Questo articolo è un tutorial pratico. Progettiamo, su carta, una vera [REST API] per un Task Manager (To-Do List).
Al termine di questa guida, capirai esattamente come strutturare gli URL, utilizzare i verbi HTTP corretti e progettare risposte JSON professionali.
Lo scenario
Creiamo un'API per gestire le Attività.
Un'attività ha: id, titulo, descricao e concluida (vero/falso).
Passaggio 1: definizione delle risorse (sostantivi)
In REST pensiamo alle "Risorse". La risorsa principale qui è Attività. Gli URL (endpoint) devono rappresentare queste risorse utilizzando sostantivi plurali.
- ✅ Destra:
/tarefas - ❌ Sbagliato:
/pegarTarefas,/criarNovaTarefa
L'URL identifica COSA stai manipolando. Il verbo HTTP identifica L'AZIONE.
Passaggio 2: elenca e crea (la raccolta)
Come interagiamo con l'elenco completo delle attività?
Elenca tutte le attività
- Richiesta:
GET /tarefas - Significato: "Ehi server, dammi la lista completa."
- Risposta (200 OK):
[ { "id": 1, "titulo": "Comprar leite", "concluida": false }, { "id": 2, "titulo": "Lavar o carro", "concluida": true } ]
Crea una nuova attività
- Requisito:
POST /tarefas - Corpo inviato:
{ "titulo": "Estudar REST", "descricao": "Ler o tutorial completo" }
- Significato: "Ehi server, aggiungi questo alla raccolta."
- Risposta (201 Creato): Il server deve restituire l'oggetto creato, ora con l'ID generato.
{ "id": 3, "titulo": "Estudar REST", "descricao": "Ler o tutorial completo", "concluida": false }
Passaggio 3: gestire un articolo specifico
Ora vogliamo modificare l'attività ID 3.
Leggi un'attività specifica
- Requisito:
GET /tarefas/3 - Risposta (200 OK): restituisce solo l'oggetto dell'attività 3.
- E se non esiste?: Risposta 404 Non trovato. (Molto importante utilizzare il codice di errore corretto!).
Aggiorna un'attività (edizione completa)
- Requisito:
PUT /tarefas/3 - Corpo:
{ "titulo": "Estudar API REST", "descricao": "Atualizado", "concluida": true }
- Nota: PUT solitamente sostituisce l'intero oggetto. Se invii solo il titolo, il resto potrebbe essere cancellato (dipende dall'implementazione, ma questa è la regola PUT).
Aggiornamento parziale (PATCH)
Per solo cambiare lo stato in completato, senza inviare nuovamente il titolo.
- Requisito:
PATCH /tarefas/3 - Corpo:
{ "concluida": true } - Significato: "Cambia solo questo campo".
Elimina un'attività
- Requisito:
DELETE /tarefas/3 - Risposta (204 Nessun contenuto): Successo, ma non c'è nulla da mostrare in cambio.
Passaggio 4: filtraggio e impaginazione
E se avessimo 10.000 attività? GET /tarefas causerebbe l'arresto anomalo dell'app.
Usiamo Parametri di query (la cosa dopo ?) per filtrare. Ciò non modifica l'URL della risorsa, ne filtra semplicemente la visualizzazione.
- Impaginazione:
GET /tarefas?pagina=2&limite=10 - Filtro:
GET /tarefas?concluida=true(Dammi solo quelli completati). - Cerca:
GET /tarefas?busca=leite
Codici di stato HTTP (feedback)
Un'API RESTful deve utilizzare codici HTTP per dirti cosa è successo. Non restituire sempre 200 con {"erro": "deu ruim"} in JSON. Ciò interrompe gli strumenti di monitoraggio.
- 200 OK: Ha funzionato.
- 201 Created: ho creato con successo la risorsa (utilizzata in POST).
- 204 No Content: ha funzionato, ma non ho nulla da mostrarti (usato in DELETE).
- 400 Bad Request: Hai inviato dati errati (es. mancava il titolo).
- 401 Non autorizzato: Chi sei? (Token mancante).
- 403 Proibito: So chi sei, ma non ti è permesso interferire.
- 404 Not Found: non l'ho trovato.
- Errore interno del server 500: il server è esploso (colpa dello sviluppatore del backend).
Conclusione
Progettare una REST API riguarda l'organizzazione e la standardizzazione. Seguendo questo schema (nomi nell'URL, verbi HTTP nell'azione, codici di stato corretti), crei un'API che qualsiasi sviluppatore nel mondo comprende in modo intuitivo, senza dover leggere un manuale di 500 pagine.
Ora tocca a te: prendi questo modello e applicalo al tuo prossimo progetto!