Convenzioni URL, metodi e errori: API prevedibile e standardizzata

Ultima modifica:

Diana Romanova

—

Giugno 25, 2025

Convenzioni URL, metodi, errori («GET», «POST», «PUT», «DELETE»)

API affidabile e comprensibile inizia con regole chiare per la creazione di interfacce. Seguiamo le migliori pratiche di REST. in modo che ogni sviluppatore sappia cosa aspettarsi: la struttura URL è logica, i metodi corrispondono all'azione e gli errori sono facilmente interpretabili.

Questo riduce la soglia di accesso, semplifica le integrazioni e consente di scalare il sistema senza caos.

Convenzioni URL e metodi HTTP

Metodo	Destinazione	Esempio di query
`GET`	Recupero risorsa	`GET /users/42`
`POST`	Creazione di una nuova risorsa	`POST /users`
`PUT`	Aggiornamento completo della risorsa	`PUT /users/42`
`PATCH`	Aggiornamento parziale della risorsa (opz.) `PATCH /users/42`
`DELETE`	Eliminare una risorsa	`DELETE /users/42`

Utilizzare sostantivi multipli («/users », «/devices», «/games »)

Le entità annidate sono descritte come gerarchie ('/users/42/sessions ')
Tutte le richieste vengono effettuate tramite HTTPS

Standard di gestione degli errori

Codice	Valore	Esempio di messaggio
`400`	Richiesta non valida	`Missing required field: email`
`401`	Non autorizzato	`Invalid token or expired session`
`403`	Accesso non consentito	`Access denied to resource`
`404`	Impossibile trovare	`User with ID 42 not found`
`409`	Conflitto (ad esempio duplicazione)	`Email already in use`
`422`	Errore di convalida	`Field 'age' must be a number`
`500`	Errore interno del server	`Unexpected exception, contact support`

Struttura di risposta all'errore:

json
{
"error": {
"code": 400,   "message": "Missing required field: email",   "details": {...}
}
}

Vantaggi per gli sviluppatori

Comprensione rapida della logica API senza troppa documentazione

Approccio unificato a tutti i moduli e entità
Debug e loging facili grazie a codici e formati standard
Compatibilità con SDK/Swagger, Postman
Supporto, test e CD semplificati

Dove è particolarmente importante

Piattaforme API aperte o partner

Progetti con più team di sviluppo
Architettura di microservizi o approccio API-first
Sistemi con più entità e interazioni

Le convenzioni unificate rendono l'API affidabile, comprensibile e conveniente. Seguiamo le migliori pratiche REST. in modo che ogni integrazione avvenga rapidamente, senza equivoci e con la massima prevedibilità.