0Pricing
AI SaaS Builder · Lezione

Progettare API RESTful

Crei API ben strutturate ed efficienti per una comunicazione fluida tra frontend e backend.

Progettare API RESTful è una lezione AI SaaS Builder 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 SaaS Builder, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso AI SaaS Builder include 4 lezioni in totale.

API: il collegamento di comunicazione della Sua app

Nel software moderno, spesso le diverse parti di un’applicazione devono comunicare tra loro. Questo vale soprattutto per il software AI SaaS, in cui il frontend (ciò che vedono gli utenti) deve interagire con il potente backend di intelligenza artificiale.

Un’API (Application Programming Interface) è simile al menu di un ristorante. Elenca i piatti (le funzioni) che è possibile ordinare e descrive quali ingredienti (i parametri) è necessario fornire e che cosa si riceverà in cambio (i risultati).

Per le applicazioni web, le API RESTful sono il modo più comune per far comunicare frontend e backend tramite Internet.

Che cos’è REST?

REST è l’acronimo di Representational State Transfer. Si tratta di uno stile architetturale, non di un protocollo, che definisce una serie di vincoli per la progettazione dei servizi web.

Lo si può considerare come un progetto di riferimento per stabilire in che modo il backend deve offrire i propri servizi ad altre applicazioni. Il rispetto dei principi REST rende le API:

  • Scalabili: possono gestire un numero maggiore di richieste.
  • Flessibili: sono facili da evolvere e adattare.
  • Manutenibili: sono più semplici da comprendere e correggere.

L’idea fondamentale è trattare ogni elemento come una «risorsa».

Principi fondamentali di REST

REST si basa su diversi principi chiave per ottenere questi vantaggi:

  • Client-server: separazione delle responsabilità. Il client gestisce l’interfaccia utente, mentre il server gestisce l’archiviazione e l’elaborazione dei dati.
  • Stateless: ogni richiesta dal client al server deve contenere tutte le informazioni necessarie per comprenderla. Il server non conserva il contesto del client tra una richiesta e l’altra.
  • Memorizzabile nella cache: le risposte possono essere contrassegnate come memorizzabili nella cache per migliorare le prestazioni.
  • Interfaccia uniforme: è il principio più importante per la progettazione. Semplifica il sistema offrendo un modo coerente di interagire con le risorse.

Le risorse: i sostantivi della Sua API

Il principio dell’«interfaccia uniforme» stabilisce che l’API deve concentrarsi sulle risorse. Una risorsa è qualsiasi informazione a cui è possibile assegnare un nome, come un utente, un prodotto o un ordine.

Durante la progettazione, consideri le risorse come sostantivi, non come verbi. Gli endpoint dell’API (URL) devono riflettere questi sostantivi, in genere nella forma plurale.

  • Invece di /getUser, utilizzi /users
  • Invece di /createProduct, utilizzi /products
  • Invece di /deleteOrder/123, utilizzi /orders/123

In questo modo, l’API risulta intuitiva e coerente.

Metodi HTTP: le azioni

Una volta definite le risorse, ad esempio /products, si utilizzano i comuni metodi HTTP per eseguire azioni su di esse. Questi metodi sono come verbi associati ai sostantivi.

  • GET: recuperare dati. (ad esempio, GET /products per ottenere tutti i prodotti)
  • POST: creare nuovi dati. (ad esempio, POST /products per aggiungere un nuovo prodotto)
  • PUT: aggiornare o sostituire dati esistenti. (ad esempio, PUT /products/123 per aggiornare il prodotto 123)
  • DELETE: rimuovere dati. (ad esempio, DELETE /products/123 per rimuovere il prodotto 123)

Esiste anche PATCH per gli aggiornamenti parziali, ma questi quattro sono i metodi fondamentali.

Esempio: recupero di dati (GET)

Vediamo come un client interagisce con un’API RESTful per recuperare dati utilizzando il metodo GET.

In questo caso, recuperiamo un post specifico da un’API di test pubblica. L’URL /posts/1 identifica chiaramente la risorsa.

import requests

# Define the API endpoint for a specific post
url = "https://jsonplaceholder.typicode.com/posts/1"

# Send a GET request
response = requests.get(url)

# Check if the request was successful (status code 200)
if response.status_code == 200:
  print("Successfully retrieved data:")
  print(response.json())
else:
  print(f"Error: {response.status_code} - {response.text}")

Esempio: creazione di dati (POST)

Per creare una nuova risorsa, utilizziamo il metodo POST. I nuovi dati vengono inviati nel corpo della richiesta, generalmente in formato JSON.

Noti che eseguiamo la richiesta sull’endpoint della risorsa al plurale (/posts) senza un ID, poiché sarà il server ad assegnarne uno.

import requests
import json

# Define the API endpoint for creating posts
url = "https://jsonplaceholder.typicode.com/posts"

# Define the data for the new post
new_post_data = {
  "title": "CoddyKit Lesson",
  "body": "This is a new post from CoddyKit!",
  "userId": 1
}

# Send a POST request with the JSON data
response = requests.post(url, json=new_post_data)

# Check if the request was successful (status code 201 Created)
if response.status_code == 201:
  print("Successfully created post:")
  print(response.json())
else:
  print(f"Error: {response.status_code} - {response.text}")

Codici di stato HTTP: il feedback dell’API

Dopo una richiesta, l’API restituisce un codice di stato HTTP. Questo numero di tre cifre comunica al client se la richiesta è andata a buon fine, se si è verificato un errore e di quale tipo.

  • 2xx Successo: 200 OK (successo generale), 201 Created (risorsa creata), 204 No Content (successo, ma nessun dato da restituire).
  • 4xx Errore del client: 400 Bad Request (richiesta non valida), 401 Unauthorized (autenticazione mancante), 403 Forbidden (utente autenticato ma privo di accesso), 404 Not Found (la risorsa non esiste).
  • 5xx Errore del server: 500 Internal Server Error (si è verificato un problema sul server).

L’utilizzo di codici di stato appropriati è fondamentale per progettare un’API ben strutturata.

Formato dei dati: JSON per semplicità

Quando si inviano dati a un’API RESTful e la si ricevono dati, un formato comune è JSON (JavaScript Object Notation).

JSON è leggero, leggibile dagli esseri umani e facilmente analizzabile dalla maggior parte dei linguaggi di programmazione. Rappresenta i dati tramite coppie chiave-valore e array, rendendolo ideale per le informazioni strutturate.

Sebbene in passato XML fosse molto diffuso, JSON è diventato lo standard de facto per le API web grazie alla sua semplicità ed efficienza.

Versionamento dell’API

Con l’evoluzione del software AI SaaS, anche la Sua API cambierà. Potrebbe aggiungere nuove funzionalità, modificare le strutture dei dati o persino rimuovere vecchi endpoint. È qui che entra in gioco il versionamento delle API.

Il versionamento consente di apportare modifiche senza interrompere le applicazioni esistenti che dipendono dalla Sua API. Un approccio comune consiste nell’includere il numero di versione nell’URL:

  • /v1/users (per la versione 1)
  • /v2/users (per la versione 2)

In questo modo si garantiscono la compatibilità con le versioni precedenti e una transizione più agevole per gli utenti.

Verifichi le Sue competenze nella progettazione delle API

Quali dei seguenti sono principi fondamentali della progettazione di API RESTful?

Riepilogo: progettare API robuste

Congratulazioni! Ha appreso i fondamenti della progettazione di API RESTful.

  • Le API consentono la comunicazione tra frontend e backend.
  • REST è uno stile architetturale che pone l’accento sulle risorse e sui metodi HTTP standard.
  • Le risorse devono essere identificate da sostantivi plurali negli URL.
  • I metodi HTTP (GET, POST, PUT, DELETE) definiscono le azioni su queste risorse.
  • I codici di stato HTTP forniscono informazioni fondamentali sull’esito delle richieste.
  • JSON è il formato di dati preferito per la comunicazione tramite API.
  • Il versionamento dell’API ne garantisce un’evoluzione graduale e la compatibilità con le versioni precedenti.

Padroneggiare questi concetti è fondamentale per creare backend AI SaaS scalabili e facilmente manutenibili.

Domande Frequenti

La lezione «Progettare API RESTful» è gratuita?

Sì — il testo completo di «Progettare API RESTful» è 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 SaaS Builder, passa a CoddyKit PRO. Il corso AI SaaS Builder include 4 lezioni in totale.

Cosa imparerò in «Progettare API RESTful»?

Crei API ben strutturate ed efficienti per una comunicazione fluida tra frontend e backend. Eserciti AI SaaS Builder 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 SaaS Builder?

Non è richiesta alcuna esperienza precedente. AI SaaS Builder 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 «Progettare API RESTful»?

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 SaaS Builder?

Sì. Ogni lezione AI SaaS Builder 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

  1. Progettare API RESTful
  2. Gestione dei database per SaaS
  3. Autenticazione e autorizzazione degli utenti
  4. Rate limiting e accodamento delle richieste AI
← Torna a AI SaaS Builder