--- term: 'Endpoint API' seoTitle: 'Endpoint API: anatomia, esempi e buone pratiche' headline: 'Che cos''è un endpoint API?' slug: endpoint-api category: api-realtime shortDefinition: 'Un endpoint API è un URL specifico in cui un''API riceve le richieste per una risorsa – abbinato a un metodo HTTP, definisce un''operazione.' relatedTerms: - api - rest-api - api-gateway-architecture - auto-generated-database-apis contrastsWith: - api-gateway-architecture aboutTerms: - 'Base URL' - 'Path Parameters' - 'Query Parameters' faq: - question: 'Che cos''è un endpoint API in parole semplici?' answer: 'L''URL specifico in cui un''API riceve le richieste relative a una risorsa: ogni endpoint è una porta d''ingresso nell''API. Una richiesta a /users/42 con il metodo GET chiede i dati dell''utente 42; lo stesso path con DELETE ne chiede la rimozione. L''API è l''intero edificio; gli endpoint sono le sue porte indirizzabili.' - question: 'Qual è un esempio di endpoint API?' answer: 'https://api.example.com/v1/users/42 – un URL di base (schema, host e versione), poi un path che nomina la risorsa. Equivalenti reali: l''endpoint /repos/OWNER/REPO di una piattaforma di hosting del codice, oppure l''endpoint /classes/Todo che un''app Back4app genera automaticamente per una classe di dati Todo.' - question: 'Qual è la differenza tra un''API e un endpoint?' answer: 'L''API è il contratto intero: l''insieme completo di regole, risorse e operazioni che un servizio espone. Un endpoint è un singolo punto di accesso al suo interno. Un''API espone molti endpoint, e la documentazione di un''API ne è in larga parte il catalogo.' - question: 'Un endpoint è la stessa cosa di un URL?' answer: 'Non esattamente. L''endpoint si esprime sotto forma di URL, ma l''URL è solo l''indirizzo; l''endpoint è il punto di interazione che quell''indirizzo identifica. La documentazione scrive di norma gli endpoint come path, con l''URL di base sottinteso – e, a essere rigorosi, il metodo HTTP fa parte di ciò che definisce l''operazione a quell''indirizzo.' - question: 'Uno stesso URL può corrispondere a più endpoint?' answer: 'Sì. GET /users/42 e DELETE /users/42 condividono un URL ma sono operazioni diverse: è per questo che lo standard OpenAPI modella un''API come un insieme di path, ciascuno con più operazioni indicizzate per metodo. Quando si contano gli "endpoint", in realtà si contano operazioni.' - question: 'Qual è la differenza tra un endpoint e una route?' answer: 'Una questione di prospettiva. La route è la definizione lato server: un pattern di path, un metodo e una funzione handler nel framework. L''endpoint è l''URL esposto al client in cui quella route è raggiungibile. La stessa cosa vista dalle due estremità della richiesta.' - question: 'Come si trovano gli endpoint di un''API?' answer: 'Tre vie, in ordine di affidabilità: leggere la documentazione o la specifica OpenAPI leggibile da una macchina, che enumera ogni path e ogni operazione; osservare il traffico reale nella scheda di rete degli strumenti per sviluppatori del browser, filtrata su fetch/XHR; oppure provare le chiamate con curl e un client API per confermarne il comportamento.' - question: 'Come si mette in sicurezza un endpoint API?' answer: 'Ogni endpoint va trattato come superficie d''attacco: solo HTTPS, autenticazione su ogni route, autorizzazione al minimo privilegio, validazione degli input, rate limiting, paginazione limitata e messaggi di errore che non lascino filtrare nulla dei meccanismi interni. Poi va tenuto un inventario: gli endpoint "zombie" dimenticati figurano tra le principali falle di sicurezza delle API.' codeLanguages: [javascript, dart, swift, kotlin] externalAuthorities: - name: 'RFC 3986 — URI: Generic Syntax' url: 'https://datatracker.ietf.org/doc/html/rfc3986' - name: 'RFC 9110 — HTTP Semantics' url: 'https://www.rfc-editor.org/rfc/rfc9110' - name: 'OpenAPI Specification — Paths and Operations' url: 'https://spec.openapis.org/oas/latest.html#paths-object' - name: 'OWASP API Security Top 10' url: 'https://owasp.org/API-Security/' cta: title: 'Endpoint che non hai mai dovuto progettare' text: 'Crea una classe su Back4app e i suoi endpoint REST esistono subito – URL delle risorse, metodi, autenticazione e permessi gestiti dalla piattaforma, coerenti su tutto il tuo modello di dati.' linkText: 'Inizia gratis' linkUrl: 'https://www.back4app.com/signup' author: 'Back4app Engineering' publishedDate: '2026-10-06' translationKey: api-endpoint --- **Un endpoint API è un URL specifico in cui un'API riceve le richieste per una risorsa – abbinato a un metodo HTTP, definisce un'operazione.** È questa seconda parte che la maggior parte delle definizioni salta, ed è proprio quella a sciogliere la confusione classica: `GET /users/42` e `DELETE /users/42` condividono un indirizzo ma sono due endpoint diversi, come una porta si comporta in modo diverso a seconda che si batta o si giri la chiave. ## Punti chiave | Domanda | Risposta | | --- | --- | | La formula | URL di base + path (+ metodo) = un'operazione su una risorsa | | vs. l'API | API = il contratto intero · endpoint = un punto di accesso al suo interno | | Path vs. query | Il path identifica *quale* risorsa · la query dice *come* restituirla | | La denominazione | Nomi al plurale, minuscole, annidamento basso – il verbo lo porta il metodo | | La sicurezza | Ogni endpoint è superficie d'attacco – compresi quelli dimenticati | ## Anatomia dell'URL di un endpoint API Ogni pezzo di un vero URL di richiesta, etichettato – secondo la grammatica della [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986): ```text GET https://api.example.com/v1/users/42/posts?status=published&limit=20 GET metodo – l'azione; parte dell'identità dell'operazione https schema – TLS, non negoziabile api.example.com host ┐ l'URL di base, condiviso da /v1 versione ┘ ogni endpoint dell'API /users/42/posts path – la risorsa: i post dell'utente 42 42 parametro di path – identifica QUALE risorsa ?status=published parametri di query – COME restituirla: &limit=20 filtrare, ordinare, paginare (fuori dall'identità) ``` Chiamare un endpoint dal codice applicativo – l'SDK compone URL, metodo e autenticazione al posto di chi scrive: **JavaScript:** ```javascript // JavaScript / Node.js — Back4app JS SDK // Every class gets endpoints automatically — this call hits one const query = new Parse.Query('Todo'); query.equalTo('done', false); query.limit(10); const todos = await query.find(); // Endpoint used: GET /classes/Todo?where={"done":false}&limit=10 ``` **Flutter:** ```dart // Flutter / Dart — Back4app Flutter SDK // Every class gets endpoints automatically — this call hits one final query = QueryBuilder(ParseObject('Todo')) ..whereEqualTo('done', false) ..setLimit(10); final response = await query.query(); // Endpoint used: GET /classes/Todo?where={"done":false}&limit=10 ``` **Swift:** ```swift // iOS / Swift — Back4app Swift SDK // Every class gets endpoints automatically — this call hits one let query = Todo.query("done" == false) .limit(10) let todos = try await query.find() // Endpoint used: GET /classes/Todo?where={"done":false}&limit=10 ``` **Kotlin:** ```kotlin // Android / Kotlin — Back4app Android SDK // Every class gets endpoints automatically — this call hits one val query = ParseQuery.getQuery("Todo") query.whereEqualTo("done", false) query.limit = 10 val todos = query.find() // Endpoint used: GET /classes/Todo?where={"done":false}&limit=10 ``` ## Endpoint vs. API vs. URL vs. route La disambiguazione a quattro termini che nessuna pagina di classifica propone: | Termine | Che cos'è | Vocabolario di chi | | --- | --- | --- | | API | Il contratto intero: tutte le risorse, le operazioni e le regole | Di tutti | | Endpoint | Un punto di accesso – un URL (+ metodo) che riceve le richieste per una risorsa | La vista di chi consuma | | URL | La stringa di indirizzo che localizza l'endpoint ([RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986)) | La vista della rete | | Route | La definizione lato server: pattern di path + metodo + codice dell'handler | La vista di chi implementa | Endpoint e route sono la stessa cosa vista dalle due estremità: un framework dichiara una route, un client chiama un endpoint. E l'[OpenAPI Specification](https://spec.openapis.org/oas/latest.html#paths-object) formalizza il quadro completo – un'API è un insieme di *path*, ogni path contiene *operazioni* indicizzate per metodo, e "quanti endpoint ha questa API?" è in realtà un conteggio di operazioni. ```mermaid flowchart LR accTitle: Come una richiesta raggiunge una risorsa attraverso un endpoint accDescr: Una richiesta del client che porta un metodo e un URL arriva all'URL di base dell'API, viene abbinata alla route di un endpoint per path e metodo, supera autenticazione e validazione, e poi l'handler opera sulla risorsa sottostante prima di restituire una risposta. C["Client
GET /v1/users/42/posts"] --> B["URL di base dell'API
abbinamento di route: path + metodo"] B --> A["Auth · validazione
rate limiting"] A --> H["Handler
(il codice della route)"] H --> R[("Risorsa:
i post dell'utente 42")] R --> H --> C ``` ## Parametri di path vs. parametri di query La regola che risolve gran parte dei dibattiti di progettazione – **l'identità nel path, la modifica nella query**: | Domanda a cui risponde il parametro | Il suo posto | Esempio | | --- | --- | --- | | *Quale* risorsa? | Path | `/users/42`, `/orders/2026-1187` | | Quale collezione *collegata*? | Path | `/users/42/posts` | | Filtrare i risultati? | Query | `?status=published` | | Ordinare o paginare? | Query | `?sort=-createdAt&limit=20` | | Ritocchi opzionali di comportamento? | Query | `?include=author&fields=title` | La distinzione ha delle conseguenze: i parametri di path fanno parte dell'identità della risorsa (e della chiave di cache); i parametri di query ne modellano la rappresentazione. Una risorsa raggiungibile solo tramite parametri di query (`/getData?type=user&id=42`) è il classico odore di livello 0 da cui parte la scala di maturità [REST](/glossary/it/api-rest/). ## Dare un buon nome agli endpoint Chi consuma un'API la giudica dalla sua lista di endpoint prima di leggere una parola di documentazione: | Convenzione | Bene | Male | | --- | --- | --- | | Nomi, non verbi – il verbo è il metodo | `POST /orders` | `POST /createOrder` | | Collezioni al plurale | `/users`, `/users/42` | `/user/42` | | Minuscole, con trattini | `/purchase-orders` | `/PurchaseOrders`, `/purchase_orders` | | Annidamento basso (un livello) | `/users/42/posts` | `/users/42/posts/8/comments/3/likes` | | Prefisso di versione con una politica | `/v1/…` + finestre di deprecazione | Rompere `/v1` in silenzio | | Pattern prevedibili | La stessa forma per ogni risorsa | Ogni risorsa con il suo dialetto | ## Mettere in sicurezza gli endpoint: la checklist Ogni endpoint è una porta, e chi attacca le prova tutte – comprese quelle che si sono dimenticate. La checklist compatta: **solo HTTPS**; **autenticazione su ogni endpoint** (nessuna eccezione "interna" raggiungibile da internet); **autorizzazione per risorsa**, non solo per API – l'utente 42 che legge `/users/43/orders` è il classico buco di broken object level authorization; **validazione degli input** su path, query e body; **[rate limiting](/glossary/it/rate-limiting-api/)** dimensionato al costo dell'endpoint; **paginazione limitata** perché nessun endpoint restituisca collezioni senza tetto; **igiene degli errori** (nessuno stack trace, nessuna fuga di esistenza). E il punto che i team mancano: **l'inventario**. Gli endpoint "zombie" – non documentati, deprecati ma vivi – hanno una voce tutta loro nell'[OWASP API Security Top 10](https://owasp.org/API-Security/): un endpoint che non si ricorda è un endpoint che non si difende. ## Casi d'uso tipici Dove ragionare per endpoint si guadagna il posto: - **Consumare un'API di terze parti** – il catalogo di endpoint della documentazione *è* il prodotto; padroneggiarne l'anatomia è il modo di leggerlo. - **Progettare un'API pubblica** – decisioni di denominazione, collocazione dei parametri e versionamento con cui chi consuma convive per anni. - **Fare il debug delle integrazioni** – riprodurre una chiamata dell'SDK come richiesta grezza all'endpoint con curl separa le colpe del client da quelle del server. - **Configurare gateway e monitoring** – [rate limiting](/glossary/it/api-gateway/), avvisi e regole di accesso si dichiarano per endpoint. - **Audit di sicurezza** – l'inventario degli endpoint è la mappa della superficie d'attacco; l'audit parte dalla sua enumerazione. ## Serve un nuovo endpoint? Matrice decisionale | Situazione | Risposta | | --- | --- | | Nuovo tipo di risorsa | Nuovo endpoint (`/invoices`) | | Stessa risorsa, risultati più ristretti | Endpoint esistente + parametri di query | | Stesso URL, azione diversa | Stesso path, metodo diverso | | Una schermata ha bisogno di cinque endpoint | Valutare un endpoint composito – ma vedere la proliferazione, più sotto | | Rappresentazione variante (campi, formato) | Parametro di query o negoziazione del contenuto, non un nuovo path | | Modifica che rompe forma o semantica | Nuovo prefisso di versione, con una finestra di deprecazione | ## Limiti e trade-off - **La proliferazione di endpoint è debito vero.** Gli endpoint per schermata e per team si accumulano; ciascuno è documentazione, test, monitoring e superficie d'attacco per sempre. Pochi endpoint ben progettati battono molti endpoint su misura. - **Le forme rigide si adattano male ad alcuni consumatori.** Un endpoint restituisce ciò che restituisce – è il trade-off di [overfetching/underfetching](/glossary/overfetching-underfetching/) a cui le API a query modellabili esistono per rispondere. - **Gli URL sono contratti.** Rinominare un endpoint rompe ogni consumatore; conviene scegliere nomi con cui si possa convivere, perché migrare significa versionamento, redirect e calendari di deprecazione. - **Il metodo è invisibile nel linguaggio corrente.** "L'endpoint /users" nasconde se si parli di lettura o di scrittura – la precisione conta nella documentazione, nei log e nelle regole di sicurezza. - **Contare gli endpoint non misura nulla.** Un'API con 12 endpoint coerenti batte regolarmente un'API con 400 endpoint improvvisati; il segnale di qualità è la governance, non il volume. ## Endpoint API su Back4app Back4app è una piattaforma open-source di Backend as a Service (BaaS) che combina database gestito, API REST e GraphQL generate automaticamente, autenticazione, archiviazione di file e funzioni serverless con Cloud Code. Qui gli endpoint sono *derivati, non progettati*: creare una classe `Todo` espone all'istante `/classes/Todo` e `/classes/Todo/:objectId` con il set completo di metodi – il pattern delle [API generate automaticamente](/glossary/it/api-generate-automaticamente/) – più endpoint permanenti per utenti, sessioni, file e funzioni, tutti con un solo URL di base, autenticazione a chiavi e permessi per classe. I tab di codice ne mostrano la conseguenza pratica: l'SDK compone endpoint, metodo e credenziali, e la checklist qui sopra – coerenza dei nomi, autenticazione in ogni punto, query limitate, zero zombie – arriva come comportamento della piattaforma invece che come disciplina in sede di revisione. Le operazioni su misura ottengono endpoint nello stesso modo: basta fare il deployment di una funzione Cloud Code e `/functions/nomeFunzione` esiste.