andrea/api
Reference Spec · v.2026.05 · API REST & GraphQL
per cto, lead dev, founder tecnici

Sviluppo API REST & GraphQL custom production-ready. OpenAPI 3.1

Backend di MVP mobile, integrazioni B2B, microservizi, headless commerce e AI agent endpoint. Schema OpenAPI 3.1 scritto prima di una riga di codice. OAuth2/JWT seri, rate limiting, CORS, docs interattive.

15 anni di backend. Una sola firma dall'audit al deploy: niente PM, niente "il dev frontend ha cambiato lo schema senza dirmelo". Il contratto API è scritto, versionato, testato. Repository Git intestato a te dal primo commit.

step 1 · è il caso che lavoriamo insieme?

Tu sei il cliente giusto
per un'API seria?

Ti aiuto se sei tu

  • Sei un CTO, lead dev o founder tecnico che sa valutare codice e capisce di cosa stiamo parlando.
  • Hai bisogno di un backend serio per MVP mobile/web, integrazione B2B, microservizio o AI agent.
  • Capisci che OAuth2, OpenAPI 3.1 e rate limiting non sono opzionali in produzione.
  • Vuoi schema scritto prima del codice (contract-first) — niente shipping di endpoint indocumentati.
  • Hai budget reale: €5k-€30k per un'API custom, non "ho 800€ e ti pago in visibilità".
  • Vuoi codice tuo, repo Git intestato a te, parlare sempre col dev (non con un account manager).

Lascia perdere se cerchi questo

  • Cerchi "un'API gratis come Postman": Postman è un client, non un'API. Non parliamo la stessa lingua.
  • Vuoi "un'API che fa tutto": API specifiche e ben tipizzate > mega-endpoint generici.
  • Hai un cliente che ha detto "basta un'API REST" ma non sa cosa significa: parliamo prima dell'audit.
  • Vuoi sostituire un programmatore senior con un freelance pagato €15/h: non è quel servizio.
  • Pensi che "l'AI scrive l'API da sola": non scrive la parte che ti rompe in produzione alle 3 di notte.
  • Vuoi cambiare schema ogni settimana in base alle idee del weekend: il versioning serve apposta.
step 2 · 5 errori che vedo ogni mese

Cinque modi concreti
per rompere un'API in produzione.

Risultato? L'API funziona oggi
e si rompe spettacolarmente quando ti serve di più.

step 3 · scegliere il protocollo giusto

REST · GraphQL · RPC · WebSocket
quando usare cosa, davvero.

Non è una questione di moda Twitter. Ogni protocollo è giusto per use case specifici. Scegliere male all'inizio ti costa una migrazione 12 mesi dopo. Te lo dico in chiaro nell'audit.

REST · default

API REST

Il default per il 80% dei casi. Cache-friendly via HTTP, debug con curl, tooling maturo (OpenAPI, Postman, Swagger). Stateless, scala bene, integrabile da qualsiasi linguaggio.

› usalo per

Backend MVP mobile/web, integrazioni B2B, webhook publisher, headless commerce, endpoint AI agent. Tutti i CRUD seri partono REST.

Node.js Fastify Python FastAPI OpenAPI 3.1
GraphQL · query layer

API GraphQL

Schema tipizzato, single endpoint, query composite client-driven. Risolve over-fetching e under-fetching su frontend complessi. Subscription realtime per dashboard.

› usalo per

Dashboard admin con widget multipli, app mobile con poca banda e schermate dense, API consumate da team frontend autonomi che vogliono fetchare ciò che gli serve.

Apollo Server DataLoader Subscription WS
gRPC / tRPC · server-to-server

API RPC

Binario, type-safe end-to-end, latenza minima. gRPC per microservizi server-to-server, tRPC per monorepo TypeScript full-stack senza schema duplicato.

› usalo per

Comunicazione interna tra microservizi (gRPC), streaming bidirezionale, app TypeScript dove client e server sono nello stesso repo (tRPC).

gRPC + Protobuf tRPC + Zod Bidirectional
WebSocket · realtime

API WebSocket

Connessione persistente client-server. Push del server senza polling. Ottimo per chat, notifiche realtime, dashboard live, gaming, trading bot. Pesante se non serve davvero.

› usalo per

Chat in-app, notifiche push interne, dashboard finanziarie/IoT, multiplayer realtime. Spesso basta SSE (Server-Sent Events) come alternativa più semplice.

Socket.IO uWebSockets SSE fallback
step 4 · 3 backend reali in produzione

Tre API. Tre stack diversi.
Tre problemi reali.

GET /v1/mvp-app · node.js fastify · jwt
Backend API REST per MVP app mobile iOS — sviluppo Node.js Fastify JWT Andrea Piani

Backend API REST per MVP mobile startup

140ms

"Node.js Fastify + PostgreSQL + JWT con refresh rotation, deploy serverless. P95 latency 140ms con 50k utenti attivi. Zero downtime al primo round seed."
→ Vedi caso MVP startup completo
POST /v2/erp-sync · python fastapi · oauth2
API REST per integrazione gestionale ERP B2B — sviluppo Python FastAPI OAuth2 Andrea Piani

API integrazione ERP per gestionale aziendale

+4x

"FastAPI + OAuth2 + webhook publisher verso Odoo. 4 milioni di sync mensili, zero data-loss. Migrazione dal vecchio backend PHP completata in 5 settimane."
→ Caso gestionale custom con API ERP
WS /v1/agent-stream · python · realtime ai
AI agent endpoint API per real estate — streaming risposte LLM con WebSocket Andrea Piani

AI agent endpoint per real estate (LLM streaming)

62%

"Endpoint streaming WebSocket + LLM proxy con rate limiting per-token. Costi infra LLM ridotti del 62% con caching semantico e tier-based throttling."
→ Caso AI agent immobiliare endpoint
step 5 · cosa ricevi davvero

Cosa include un'API custom
fatta come si deve.

Tutto incluso, scritto nel preventivo personalizzato dopo l'audit. Scope-based: il prezzo dipende dal numero di endpoint, complessità auth, volume traffico e SLA. Costi cloud terzi (VPS, DB managed, monitoring) separati e sotto tuo account.

  • API Design Call + OpenAPI 3.1 spec scritta — discovery tecnica, schema OpenAPI completo, contratto API approvato prima di una riga di codice.
  • Sviluppo backend Node.js o Python — Fastify/Express/NestJS o FastAPI/Django REST, type-safe, test coverage, repository pattern.
  • Autenticazione OAuth2 / JWT enterprise-grade — refresh token rotation, scope-based authorization, revocation list, no segreti hardcoded.
  • Rate limiting per-token e per-IP — Redis/Upstash backed, configurabile per tier, header standard Retry-After.
  • CORS configurato endpoint-by-endpoint — allow-list esplicita, niente wildcard in produzione, preflight cacheato.
  • Database schema + migrazioni — PostgreSQL o MySQL, schema progettato per le query reali, migrazioni reversibili versionate Git.
  • Deploy su VPS o serverless — Hetzner/Aruba/Vercel/Cloudflare Workers, CI/CD con GitHub Actions, blue/green deploy quando ha senso.
  • Documentazione interattiva Swagger UI / Redoc — generata da OpenAPI 3.1, hostata su /docs, esempi curl per ogni endpoint.
  • Monitoring + observability — Sentry per errori, Better Stack/Uptime Robot per uptime, structured logging JSON, dashboard interno.
  • Repository Git intestato a te dal giorno 1 — codice tuo, history pulita, branch protection. › INCALCOLABILE
  • 3 mesi supporto prioritario post-launch — risposta entro 24h, fix critici immediati, hotfix gratuiti.
  • BONUS 1 Postman collection esportata da OpenAPI per onboarding dev team interno o partner B2B.
  • BONUS 2 Integration test suite (Vitest/Pytest) con coverage minima 80% sugli endpoint critici.
  • BONUS 3 Developer onboarding doc (Markdown nel repo) per il prossimo dev che metterà mano al codice.
pacchetto "API live + handover pulito"
audit · spec · code · deploy · docs · tests · support
preventivo scope-based scritto in 48h dopo l'API Design Audit
voglio l'api design audit
Maggio 2026 — 1 slot libero su 2 · prossimo mese aperto: Giugno 2026
step 6 · il rischio è mio

Tripla garanzia
developer-friendly.

Codice tuo · repo intestato a te

Dal momento dell'acconto: repository Git su organizzazione GitHub/GitLab tua, branch protection attiva, history pulita. Se domani sparisco da internet, hai sorgente, spec, test, doc, deploy script. Qualsiasi backend dev può continuare. Indispensabile per un audit tecnico o un round.

12 mesi bug-fix incluso

Per 12 mesi dal go-live, qualunque bug nel codice che ho scritto lo sistemo gratis. Crash in produzione, regression dopo update dipendenze, edge case che spunta con i primi 1.000 utenti reali. Email/Slack a me, lo aggiusto. Senza fatture extra.

Handover pulito a team interno

Quando l'API funziona e cresci, ti aiuto a passare il codice a un team interno o a una nuova agenzia: handover gratuito, manuale tecnico aggiornato, OpenAPI spec live, 2h di tour video col team nuovo. Niente lock-in, mai.

step 7 · domande tecniche oneste

10 domande tecniche,
10 risposte oneste.

1. REST o GraphQL: quale scegliere?
REST è il default per il 80% dei casi: cache-friendly via HTTP, debug con curl, tooling maturo (OpenAPI, Postman, Swagger UI). GraphQL è giusto se hai un'app frontend con esigenze di fetch composito (dashboard, mobile con poca banda) e vuoi evitare over-fetching. Per backend MVP mobile parto sempre REST: 80% dei casi non ha bisogno di GraphQL e ti porti dietro complessità di schema/resolver per niente.
2. Mi serve davvero versioning (/v1, /v2)?
Sì, dal giorno uno. Una volta che un client mobile in produzione consuma la tua API, una breaking change senza versioning rompe app installate (e gli utenti non aggiornano subito). URL-based versioning (/v1/users) è il più semplice e debugabile. Deprecation policy scritta con window 6-12 mesi e header Sunset/Deprecation è lo standard B2B. Te lo metto in OpenAPI dal primo commit.
3. Rate limiting è necessario su API piccole?
Sì, sempre. Anche un'API che serve solo la tua app mobile può essere abusata: utente compromesso, bug del client in retry loop, scraper che gira di notte. Rate limit per-token (es. 1000 req/min authenticated) + per-IP (es. 30 req/min unauth) è il minimo. Implementazione con Redis o servizio cloud (Upstash, Cloudflare). Response 429 Too Many Requests con header Retry-After.
4. JWT, OAuth2 o API Key: quale uso?
API Key per integrazioni server-to-server semplici (webhook, partner B2B fidati). JWT con refresh token rotation per app mobile/web first-party. OAuth2 Authorization Code + PKCE per app pubbliche di terzi che accedono ai dati dei tuoi utenti (tipo OAuth Google). mTLS per server-to-server critici (pagamenti, banking). Si possono coesistere su tier diversi della stessa API. Niente JWT homemade con segreto hardcoded nel repo.
5. Deploy su serverless o VPS?
VPS (Hetzner, Aruba, DigitalOcean) per API steady-state con traffico prevedibile: costo fisso €10-50/mese, controllo pieno, latenza bassa e stabile. Serverless (Vercel, Cloudflare Workers, AWS Lambda) per API con traffico spiky o bursty: paghi a invocazione, scala da 0 a 1M req senza pensieri, ma watch out cold start. Per MVP parto quasi sempre serverless o VPS managed. Decisione finale durante l'audit.
6. Quanto costa il backend mensile dopo il deploy?
Per un MVP: €15-50/mese (VPS + DB managed + Sentry + uptime monitor). Per API B2B con 100k-1M req/giorno: €100-400/mese (VPS più grosso o serverless tier business, DB ad alta disponibilità, CDN). Costi reali, sotto tuo account cloud, mai sul mio. Te li stimo nel preventivo audit con numeri specifici. Vedi anche guida ai costi sviluppo app per il quadro complessivo.
7. Posso testare l'API prima di firmare?
Sì. Dopo l'API Design Audit gratuito, ti mando uno schema OpenAPI 3.1 preliminare che puoi caricare in Swagger UI o Postman e vedere com'è strutturato. Poi, durante lo sviluppo, hai accesso settimanale a staging environment con docs Swagger live. Niente sorprese al go-live: l'API che vedi in staging = l'API che ti consegno.
8. Quanto tempo serve per un'API custom?
Dipende dallo scope: API REST con 8-15 endpoint, auth, rate limiting, docs e deploy: 4-6 settimane. API GraphQL con resolver complessi e subscription realtime: 6-9 settimane. Microservizio singolo con CI/CD completo: 3-4 settimane. Tempo dal kick-off (dopo audit + preventivo firmato), non dalla firma del preventivo.
9. Posso parlare con un cliente reale prima di firmare?
Sì. Su richiesta ti metto in contatto con un CTO o founder che ho aiutato a costruire l'API backend del loro MVP o gestionale custom. Chiamata reale, niente referenze costruite. I miei clienti che continuano a chiamarmi sono l'unica social proof seria che ho — e lo so. Scrivimi su WhatsApp →
10. Cosa succede se aumenta il traffico dopo il go-live?
L'architettura è pensata per scalare: handler stateless, DB con read replicas pronte da abilitare, response CDN-cacheable dove possibile, rate limiting che assorbe burst. Quando arrivi davvero a 1M+ req/giorno, parliamo: spesso basta upgrade VPS o passaggio a serverless tier business, senza re-write. Se serve, integro con Node.js backend dedicato o Python ad alta performance per workload specifici.
step 8 · api design audit · 5 step · risposta in 48h

Descrivimi il caso in 5 step.
Ti mando io l'API design.

Nessun preventivo standard, nessun PDF auto-generato. Mi descrivi il caso d'uso in 5 step, leggo io a mano i tuoi vincoli (stack, volume, security tier), e ti mando una proposta tecnica e roadmap realistica in 48h.

Cosa ricevi nell'Audit Report:

  • Schema OpenAPI 3.1 suggerito (endpoint, auth, status codes).
  • Stack consigliato con motivazione tecnica (Node.js vs Python vs Go).
  • Tier auth giusto per il tuo caso (JWT, OAuth2, mTLS, API Key).
  • Stima infra cost mensile realistica sul volume previsto.
  • Roadmap 4-8 settimane con milestone settimanali.
  • Preventivo indicativo (range, non numero magico) se vuoi procedere.
  • L'onesta verità se la mia raccomandazione è "non farlo così" o "ti serve un altro stack".
step 1 / 5
Cosa devi esporre via API?
step 2 / 5
Stack backend preferito?
step 3 / 5
Volume di traffico stimato
step 4 / 5
Livello security richiesto
step 5 / 5 — ultimo
A chi mando l'Audit Report?
step 9 · due strade

Hai due modi onesti
per partire ora.

A · consigliato

API Design Audit gratuito 48h.

Apri il form qui sopra. 5 step, 4 minuti. Entro 48h ricevi uno schema OpenAPI 3.1 preliminare, stack consigliato, tier auth, stima infra cost mensile e roadmap 4-8 settimane. Senza impegno, senza marketing.

vai all'audit
B · se preferisci parlare

Tech call gratuita 30 minuti.

Scrivimi su WhatsApp, fissiamo 30 minuti. Mi racconti il caso d'uso da CTO/dev a dev, io ti dico se ha senso un'API custom adesso o se hai prima un problema di architettura/dominio da chiudere. Niente pitch, niente vendita aggressiva.

scrivimi su whatsapp