Come costruire una REST API: progettazione, sicurezza e deploy

Per costruire una REST API, elenca le risorse che gestisce la tua app (utenti, ordini, prenotazioni), assegna a ciascuna un URL come /orders e /orders/{id}, e usa i metodi HTTP per le azioni: GET per leggere, POST per creare, PATCH per aggiornare, DELETE per eliminare. Restituisci JSON con codici di stato significativi, valida ogni input, richiedi autenticazione e controlli di permesso per singolo record lato server, e pagina le liste. Poi documenta gli endpoint e pubblica l'API dietro HTTPS.

Questa guida copre le decisioni di progettazione, un insieme di route svolte, i prompt per un AI app builder e gli errori che causano falle di sicurezza. Se le API ti sono nuove, inizia da cos'è un'API.

Quando ti serve una REST API

• Il tuo frontend web deve salvare e caricare dati da un server
• Un'app mobile, un partner o uno strumento di automazione ha bisogno di accedere ai tuoi dati
• Altri servizi ti inviano eventi (webhook)
• Stai dividendo il lavoro tra un team frontend e un team backend

REST è lo stile più diffuso, ma non l'unico. REST vs GraphQL spiega quando un singolo endpoint di query flessibile è la scelta migliore.

Progetta prima: risorse e route

Scrivi i sostantivi della tua app e ciò che le persone fanno con essi. Per una semplice app di prenotazioni:

Queste corrispondono a create, read, update e delete; vedi cos'è il CRUD. Convenzioni utili da seguire:

• Sostantivi al plurale, niente verbi negli URL: /bookings, non /getBookings.
• Annida un solo livello quando chiarisce la proprietà: /bookings/{id}/notes.
• Le azioni che non sono CRUD possono essere sotto-risorse: POST /bookings/{id}/cancel è più chiaro di una PATCH "magica".
• Nomi coerenti per i campi, come created_at ovunque.

Codici di stato ed errori

Usa i codici HTTP standard così i client capiscono cosa è successo senza analizzare il testo:

Restituisci gli errori in un'unica forma JSON coerente, per esempio {"error": {"code": "slot_taken", "message": "Quell'orario non è più disponibile."}}, e non includere mai stack trace o errori del database nelle risposte.

Opzioni e compromessi

Passo dopo passo

1. Elenca risorse e route come sopra, incluso chi può chiamare ciascuna.
2. Modella i dati nel tuo database con i campi e le relazioni che ti servono.
3. Costruisci prima le route di lettura, poi create, update e delete.
4. Valida l'input in ogni scrittura con una libreria di schema: campi obbligatori, tipi, lunghezze, valori ammessi. Rifiuta i campi sconosciuti.
5. Aggiungi l'autenticazione, poi l'autorizzazione per singolo record: caricare /bookings/42 deve verificare che la prenotazione 42 appartenga al chiamante, non solo che qualcuno abbia effettuato l'accesso.
6. Pagina ogni lista e limita la dimensione della pagina.
7. Limita le richieste per il login e le route costose. Vedi rate limiting.
8. Configura CORS solo se browser di altri domini devono chiamare l'API, ed elenca esplicitamente quelle origini. Come risolvere gli errori CORS spiega gli errori che vedrai.
9. Scrivi documentazione e test per ogni route, inclusi i casi di errore.
10. Pubblica con i segreti nelle variabili d'ambiente, HTTPS, log e un controllo di integrità.

Prompt per il tuo AI builder

Impalcatura:

Crea una REST API per le prenotazioni con queste route: GET /api/health, GET /api/bookings (paginato, massimo 50 per pagina), POST /api/bookings, GET /api/bookings/:id, PATCH /api/bookings/:id, DELETE /api/bookings/:id. Salva i dati nel nostro database. Valida i corpi delle richieste con una libreria di schema e rifiuta i campi sconosciuti. Restituisci gli errori JSON come {"error": {"code", "message"}} con i codici di stato corretti (400, 401, 403, 404, 409). Conserva i segreti nelle variabili d'ambiente.

Sicurezza:

Richiedi l'accesso su ogni route delle prenotazioni. Per ogni lettura, aggiornamento ed eliminazione, verifica lato server che la prenotazione appartenga all'utente corrente; restituisci 404 se non appartiene. Non accettare mai ID utente o ruoli dal corpo della richiesta. Limita POST /api/bookings a 20 al minuto per utente. Registra gli errori sul server senza restituire stack trace.

Documentazione:

Scrivi una descrizione OpenAPI di queste route e un breve README con esempi di richieste e risposte per ciascuna.

Testare la tua API

Testa dall'esterno del frontend, perché lo faranno gli attaccanti:

• Ogni route funziona con input validi e restituisce la forma e il codice documentati
• Campi mancanti o non validi restituiscono 400 con un messaggio chiaro
• Nessun token restituisce 401 su ogni route protetta
• L'utente A che richiede il record dell'utente B tramite ID ottiene 404 o 403
• Le liste sono paginate; un limit enorme viene limitato
• Le creazioni duplicate o in conflitto restituiscono 409, non 500
• I rate limit restituiscono 429
• Le risposte di errore non contengono stack trace, SQL o segreti
• CORS consente solo le origini che intendi

Errori comuni

• Controllare il login ma non la proprietà. È la falla più comune nelle API: qualsiasi utente connesso può leggere qualsiasi record cambiando l'ID.
• Fidarsi del client. Prezzi, ruoli e ID utente nel corpo della richiesta possono essere modificati.
• Restituire intere righe del database. Gli hash delle password e i campi interni finiscono all'esterno. Scegli cosa include ogni risposta.
• Liste senza limiti. Una richiesta per ogni record può rallentare l'intera app.
• 200 OK con un messaggio di errore dentro. Client e monitoraggio non possono capire che è fallito.
• CORS impostato per consentire tutto su un'API che usa i cookie.
• Nessun controllo di integrità né log, quindi scopri i guasti dagli utenti.

Per una verifica più ampia prima del lancio, vedi la checklist di sicurezza per app costruite con l'AI.

Costruire una REST API in Mythex

Puoi chiedere a Mythex un'API come parte della tua app o come servizio a sé. La ricetta della documentazione REST API backend include un prompt di partenza: indica framework e route, chiedi errori JSON chiari, conserva i segreti nelle variabili d'ambiente e includi un Dockerfile. I backend container in Node, Python, C#, Java e altri si pubblicano tramite un Dockerfile, e Mythex gestisce il deploy da Publish (backend API). Un progetto può far girare un sito e un server API affiancati, e puoi passare dall'uno all'altro nell'anteprima. Salva le chiavi come segreti del progetto e, se l'API richiede un database, chiedilo in chat. Per il lavoro programmato attorno alla tua API, vedi come eseguire job in background.

Domande