Repassa el que vam escriure al mòdul 4: un limitador de peticions amb Redis, la validació de tokens JWT i de tokens OAuth per JWKS, una llista blanca d'orígens per a CORS, capçaleres de memòria cau amb ETag i 304, compressió, mètriques a /metriques. Sis peces d'infraestructura, amb el seu codi, les seves proves i el seu manteniment.

Ara la incomoditat: gairebé totes existeixen resoltes una capa per damunt. Un API gateway fa les sis, amb configuració en lloc de codi, i les fa per a totes les teves APIs alhora. La pregunta òbvia és si vam perdre el temps. La resposta és que no —entendre un mecanisme és el que permet decidir si delegar-lo i depurar-lo quan falli—, però la pregunta següent sí que és difícil i és la que ocupa mitja lliçó: què es delega al gateway i què s'ha de quedar a l'aplicació.

I hi ha una segona meitat. Tenim una API excel·lent, documentada i desplegada. Però CataBox, l'aplicació de tercers que s'integra per OAuth, no té ni idea de com començar: on registrar-se, com aconseguir credencials, on provar sense trencar res, quins límits té, quan canviarà alguna cosa. Això és un portal de desenvolupador, i determina si la teva API es fa servir o s'abandona la primera hora.

Aquesta lliçó tanca el mòdul 5 amb les dues capes que envolten l'API: la que la protegeix i la que l'explica.

1. Què és un API gateway i quin problema resol
2. Les funcions que assumeix, comparades amb el mòdul 4
3. Què delegar i què no delegar mai
4. L'arquitectura completa: CDN, gateway, serveis
5. El patró backend for frontend
6. El service mesh és una altra cosa
7. Els productes i com es comparen
8. Configuració de Kong per a la Botiga Aroma
9. L'alternativa amb NGINX
10. Quins middlewares podríem retirar i quins no
11. Els riscos del gateway
12. Què és un portal de desenvolupador
13. Què conté un bon portal
14. Registre d'aplicacions i credencials OAuth
15. El temps fins a la primera crida amb èxit
16. Cicle de vida i inventari d'APIs
17. Monetització, com a nota
18. Balanç del mòdul 5

Un API gateway és un servidor que se situa davant d'una o diverses APIs i actua com a porta única: rep tot el trànsit extern, aplica polítiques transversals i reenvia les peticions al servei que correspongui.

El problema que resol es veu millor amb l'escenari que li dona sentit. Imagina't que la Botiga Aroma creix:

Amb una API, el gateway aporta poc: estàs movent de lloc codi que ja funciona. Amb cinc, la diferència és enorme: sense ell, cada equip reimplementa el rate limiting a la seva manera, tres dels cinc ho fan malament, la política de CORS divergeix, i no hi ha un lloc on respondre «quantes peticions rebem en total?».

La formulació precisa: un gateway centralitza les preocupacions transversals del trànsit. I com tot el que està centralitzat, aporta consistència i crea un punt únic de fallada. Totes dues coses alhora.

Les tres últimes files són l'assumpte de l'apartat següent.

El criteri, en una frase: el gateway sap qui crida i on; només l'aplicació sap què hi ha a dins i què significa.

D'aquí se'n dedueix tota la resta:

Es delega bé el que depèn únicament de la petició i de la identitat: rate limiting, terminació TLS, verificació criptogràfica del token, CORS, compressió, encaminament. Són decisions que no requereixen consultar la teva base de dades.

No es delega mai, i convé ser taxatiu:

1. L'autorització a nivell de recurs. El gateway pot comprovar que el token és vàlid i que té l'àmbit comandes.llegir. No pot comprovar que com_5001 pertany a cli_842, perquè això exigeix consultar la base de dades. I aquella comprovació és precisament la que evita la fallada número u de l'OWASP API Top 10 (04-02), el BOLA. Si deixes de fer-la a l'aplicació perquè «ja ho mira el gateway», tens una vulnerabilitat crítica.

2. La lògica de negoci. Que una comanda pagat no pugui tornar a pendent_pagament, que no es vengui més estoc del disponible, que el termini de devolució siguin 14 dies. Ficar regles de negoci a la configuració del gateway crea un segon lloc on viu el domini, sense proves, sense tipus i sense revisió de codi. És l'error més car que es comet amb aquestes eines.

3. La validació semàntica. El gateway pot rebutjar un cos que no compleixi el JSON Schema —tipus, rangs, camps obligatoris— i és una defensa útil. No pot validar que cafeId existeixi, que preuMin sigui menor que preuMax, o que el client pugui comprar aquell cafè.

4. La defensa en profunditat. Encara que el gateway validi el token, l'aplicació ha de continuar validant-lo. Motiu: si algú arriba al teu servei esquivant el gateway —una regla de xarxa mal posada, un desplegament nou, un atacant dins de la xarxa— la teva API quedaria totalment oberta. La regla és zero trust: el servei no confia que el trànsit vingui d'on sembla.

Una taula que resumeix l'assignació:

Què fa cada capa i per què és on és:

Les fletxes puntejades del diagrama són importants: el trànsit nord-sud (de fora cap a dins) passa pel gateway; el trànsit est-oest (entre serveis interns) no. Fer que les crides internes surtin i tornin a entrar pel gateway multiplica la latència i converteix el gateway en el coll d'ampolla de tot el sistema.

L'Aroma Mòbil té un problema que la SPA no té: per pintar la pantalla d'inici necessita el catàleg destacat, les comandes recents del client i les seves preferències. Amb l'API tal qual, són tres peticions, sobre una xarxa mòbil amb 150 ms de latència i una bateria que es gasta.

Un BFF és una API intermèdia dedicada a un consumidor concret, que agrega i adapta:

L'avantatge polític del BFF és tan important com el tècnic: l'equip mòbil pot canviar el seu BFF sense negociar amb ningú ni esperar un cicle de versionat, perquè és l'únic consumidor. El parany és que un BFF acabi amb regles de negoci pròpies que divergeixen de l'API. Regla: el BFF agrega, filtra i adapta formats; no decideix res del domini.

Alguns gateways ofereixen agregació per configuració, sense escriure un BFF. Funciona per a casos trivials i es torna inmanejable tan bon punt hi ha lògica condicional. Si necessites un if, escriu un BFF.

Es confonen constantment, així que convé separar-los:

No són alternatives: són complementaris, i moltes arquitectures madures tenen tots dos. Per a la Botiga Aroma avui, amb una API i dos serveis interns, un service mesh és clarament prematur: el seu cost operatiu només s'amortitza amb desenes de serveis.

Criteris d'elecció, que s'assemblen molt als de 05-03:

• Qui l'operarà? Un Kong autogestionat en alta disponibilitat és un sistema distribuït més per mantenir, apedaçar i monitorar. Si l'equip és petit, l'opció gestionada gairebé sempre guanya.
• On és la resta? Si ja ets a AWS amb ECS, AWS API Gateway estalvia integració. Si ja fas servir Cloudflare, bona part de la feina es pot fer allà.
• Necessites un portal? Si tindràs tercers com CataBox, el portal és la meitat del producte. Kong OSS no el porta; Tyk sí; Apigee i Azure APIM porten els més complets.
• Quant costa per petició? Els gestionats cobren per milió de peticions. Amb volums alts, el compte pot superar el cost d'operar-lo tu.
• Quin model de configuració? La configuració declarativa en YAML versionada a Git (Kong amb decK, Traefik, Gateway API de Kubernetes) és molt superior a configurar per interfície gràfica: es revisa en un pull request i es desplega amb la canalització de 05-05.

Configuració declarativa completa, versionable al repositori com a gateway/kong.yaml:

Quatre punts d'aquella configuració que mereixen comentari:

• fault_tolerant diferent segons la ruta. Al límit global és true: si Redis cau, preferim deixar passar trànsit a tirar l'API sencera. A l'inici de sessió és false: si Redis cau, preferim bloquejar a quedar-nos sense protecció contra la força bruta. És una decisió de disponibilitat davant de seguretat que s'ha de prendre conscientment per a cada cas, i el gateway obliga a explicitar-la.
• limit_by: consumer davant de limit_by: ip. Limitar per IP castiga tots els usuaris darrere d'un NAT corporatiu i no protegeix d'un atacant amb moltes IP. Per consumidor autenticat és el correcte… tret de l'inici de sessió, on encara no hi ha consumidor.
• exposed_headers. L'error de CORS més frustrant de 04-05: el navegador rep ETag però JavaScript no el pot llegir si no és a Access-Control-Expose-Headers. Aquí queda declarat d'una vegada per a tota l'API.
• preflight_continue: false. El gateway respon els OPTIONS i l'aplicació no els veu. Estalvia latència i una part del trànsit, però significa que el teu middleware de CORS deixa d'executar-se per al preflight: si algun dia treus el gateway, recorda que aquella peça hi era.

La configuració s'aplica des de la canalització de 05-05:

Això és infraestructura com a codi aplicada al gateway, i és el que evita el problema clàssic: algú toca la configuració a la interfície gràfica un dimarts, ningú no ho recorda, i a la reconstrucció següent de l'entorn la política desapareix.

Si l'equip ja opera NGINX i no necessita gestió de consumidors ni portal, bona part de l'anterior s'aconsegueix amb configuració directa:

La capçalera X-Forwarded-For connecta directament amb el trust proxy 1 de la posició 1 de src/app.js. Sense X-Forwarded-For, Express veu la IP del gateway a totes les peticions i el rate limiting per IP limita el gateway sencer. I amb trust proxy mal configurat —confiant en més salts dels que hi ha— un atacant pot falsificar la seva IP afegint la capçalera ell mateix. El número ha de coincidir exactament amb la quantitat de proxies de confiança que hi ha al davant.

El que NGINX no dona i Kong sí: gestió de consumidors amb credencials, quotes mensuals, validació de JWT sense recórrer a Lua, portal de desenvolupador i configuració per API en lloc de per fitxer. Per a una API amb socis i tercers, aquelles absències pesen.

La pregunta pràctica: amb el gateway de dalt al davant, què queda a src/app.js?

Balanç honest: es retiren un o dos middlewares de setze. Aquest és el resultat real i convé dir-ho sense adorns, perquè contradiu la promesa comercial d'aquestes eines.

El valor del gateway no és aprimar la teva aplicació. És en tres coses diferents:

1. Consistència entre diversos serveis. Amb cinc APIs, les polítiques s'escriuen una vegada en lloc de cinc.
2. Gestió de consumidors. Quotes per pla, credencials, mTLS amb socis, llistes negres. Això no existia al nostre projecte i construir-ho seria costós.
3. Canviar polítiques sense desplegar. Ajustar un límit o bloquejar un client abusiu és una línia de YAML i trenta segons, en lloc d'un desplegament complet.

I una última observació important: la configuració del gateway s'ha de provar igual que el codi. El recorregut de Newman de 05-01 s'ha d'executar contra el gateway, no contra l'API directament. Si no, un CORS mal configurat o un strip_path equivocat es descobreix en producció. Amb deck gateway diff al pull request, el canvi de política es revisa com qualsevol altre.

1. Punt únic de fallada. Si el gateway cau, totes les teves APIs cauen alhora, encara que estiguin perfectament sanes. Mitigació: diverses instàncies, comprovacions de salut, i —el que gairebé ningú no fa— un pla documentat per exposar temporalment els serveis sense ell.

2. Coll d'ampolla i latència afegida. Cada petició travessa un salt de xarxa i un processament addicional: entre 1 i 10 ms típicament. Amb un pressupost de latència de 200 ms (04-06) és assumible; si el teu p99 objectiu són 20 ms, és un 25 % del pressupost i cal mesurar-ho, no suposar-ho.

3. Configuració duplicada i divergent. El cas més perniciós: CORS configurat al gateway i a l'aplicació amb llistes diferents. Un origen funciona en desenvolupament i falla en producció, o a l'inrevés, i depurar-ho és un infern perquè cada capa diu que està bé. Regla: una política, un amo, documentat en un ADR (04-01).

4. Lògica de negoci al gateway. El risc més car. Comença amb una transformació innocent i acaba amb regles de preus en un script Lua sense proves, sense control de versions efectiu i sense ningú que sàpiga que hi són. La regla de l'apartat 3 no admet excepcions.

5. Dependència del proveïdor. Les polítiques d'Apigee o d'Azure APIM no es migren a Kong. Com més lògica fiquis al gateway, més car és canviar-lo. Un altre argument per mantenir-lo prim.

6. Falsa sensació de seguretat. «El gateway valida els tokens, així que l'app pot confiar.» No. Zero trust: l'aplicació valida sempre.

7. Depuració més difícil. Un 403 pot venir del gateway o de l'aplicació, i de vegades no és evident quin. Mitigació: que el gateway marqui els seus propis errors —una capçalera pròpia, o un camp a detalls— i que l'Aroma-Traca-Id travessi totes dues capes, que és exactament per al que serveix el plugin correlation-id.

Canviem de tema i d'audiència. Un portal de desenvolupador és el lloc web on qui vol integrar-se amb la teva API aprèn a fer-ho, es registra, obté credencials, prova i s'assabenta dels canvis.

La pregunta que respon: CataBox vol integrar-se amb la Botiga Aroma un dimarts al matí. Què passa?

Qui el necessita: qualsevol API amb consumidors que no siguin al teu equip. Amb una API estrictament interna i dos equips, /docs amb Swagger UI i un canal de xat poden bastar. Tan bon punt hi ha tercers, socis o més de quatre o cinc equips interns, el portal deixa de ser un luxe.

Tres apartats solen faltar i són els que més s'agraeixen:

• Guies temàtiques, no només referència. La referència diu que POST /v1/comandes accepta Idempotency-Key. Una guia explica per què, què passa en reintentar, quant de temps es conserva la clau i com generar-la. La referència respon «què»; la guia respon «com i per què», i és el que evita les integracions mal fetes.
• La pàgina d'errors. El catàleg complet de 02-04 amb què significa cada codi, si convé reintentar-ho i què fer. Amb 429 i Retry-After, amb 409 d'idempotència, amb 412 d'If-Match. És la pàgina que més visites rep d'un portal madur, i la seva absència es tradueix directament en tiquets de suport.
• Exemples executables. curl copiable, i la col·lecció de Postman de 05-01 amb un botó d'importar. Que algú pugui enganxar una ordre i veure una resposta real en trenta segons val més que deu pàgines de prosa.

I una guia d'inici que funciona té aquesta forma, sense adorns:

Quatre passos, tres minuts, zero ambigüitat. Aquest és l'estàndard.

El flux pel qual un tercer es converteix en consumidor:

Decisions de disseny d'aquest flux, totes amb conseqüències de seguretat (04-02 i 04-03):

• El client_secret es mostra una sola vegada. Es desa com a hash, igual que una contrasenya. Si es perd, es rota; no es recupera.
• Aplicacions públiques davant de confidencials. Una SPA o una app mòbil no poden desar un secret: són públiques i han de fer servir Authorization Code amb PKCE. El portal ha de preguntar el tipus i no oferir secret a les públiques.
• Àmbits mínims. Que CataBox demani cafes.llegir i ressenyes.escriure, no tots. El portal ha d'explicar què permet cada àmbit amb llenguatge clar, perquè aquell text és el que veurà el client final a la pantalla de consentiment.
• Àmbits sensibles amb revisió manual. ressenyes.moderar o enviaments.escriure no es concedeixen automàticament: es demanen i algú els aprova.
• Aprovació separada per a producció. L'entorn de proves és immediat; l'accés a producció exigeix revisar l'aplicació. És el que evita que un desenvolupador curiós arribi a dades reals.
• Rotació de credencials sense tall: poder tenir dos secrets vàlids alhora durant la rotació. Sense això, rotar implica un tall, i la conseqüència és que ningú no rota mai.

Hi ha una mètrica que resumeix la qualitat de l'experiència d'integració: TTFHW (time to first hello world), el temps des que algú arriba al teu portal fins que rep la seva primera resposta 200.

Per què importa tant: els primers minuts, qui avalua la teva API decideix si continua o busca una altra cosa. Un TTFHW de trenta minuts amb tres correus a suport pel mig és una barrera comercial real, no un detall d'experiència d'usuari.

Com es mesura de debò: asseu-te amb algú que no conegui l'API, dona-li l'enllaç del portal i cronometra sense ajudar-lo. Anota cada punt on dubta, s'equivoca o s'atura. Aquells punts són la llista de tasques, ordenada per impacte. És una prova que costa una hora i produeix millor informació que qualsevol enquesta.

Els frens habituals, que es repeteixen a gairebé totes les APIs:

1. El registre demana dades innecessàries al primer pas (raó social, telèfon, adreça fiscal).
2. Les credencials requereixen aprovació humana fins i tot per a l'entorn de proves.
3. L'exemple de la documentació no funciona copiat i enganxat (falta una capçalera, la URL està desactualitzada).
4. L'entorn de proves no té dades: el primer GET retorna una llista buida i sembla que alguna cosa falla.
5. Els errors no expliquen el problema: un 401 genèric sense dir si el token no és vàlid, ha caducat o li falta l'àmbit.

El punt 4 és especialment traïdor. L'entorn de proves ha d'estar sembrat amb dades fictícies riques: el nostre npm run sembrar amb caf_001, caf_002, cli_842 i com_5001 compleix exactament aquella funció, i per això les primeres crides del portal retornen alguna cosa interessant en lloc de {"dades": [], "total": 0}.

A 04-02, el novè punt de l'OWASP API Top 10 era la gestió inadequada de l'inventari: APIs oblidades, versions antigues encara vives, endpoints de proves exposats. Aquí és on es resol.

El gateway és la font de veritat de l'inventari, perquè tot el que s'exposa hi passa. Si alguna cosa rep trànsit extern i no és a la configuració del gateway, és una API a l'ombra i hi ha un problema.

Cada API o versió té un cicle de vida explícit:

L'última fila és el problema real. Les APIs zombis apareixen perquè ningú no té la llista completa, i sobreviuen perquè ningú no s'atreveix a apagar res per si de cas.

Les pràctiques que ho eviten, totes recolzades en peces que ja tenim:

• Inventari automàtic des de la configuració del gateway, versionada a Git.
• Mètriques d'ús per ruta, versió i consumidor (04-07 i el plugin prometheus amb per_consumer). Abans de retirar /v1 la pregunta «qui la fa servir encara?» té una resposta amb noms i volums, no una suposició.
• Un amo per API, amb nom i equip. Sense amo, no hi ha qui decideixi.
• Data de revisió. Cada API es revisa almenys una vegada l'any: continua fent falta?, està documentada?, té consumidors?
• Els entorns de no producció, tancats. Preproducció sense autenticació, accessible des d'internet, és un clàssic i apareix als informes de bretxes amb una freqüència depriment.
• La retirada, en dues fases. Primer l'apagada de prova: retornar 410 durant unes hores en una data anunciada. Els consumidors que quedaven apareixen immediatament. Després, la retirada definitiva. És molt més eficaç que qualsevol correu d'avís.

Quan l'API és en si mateixa un producte, el gateway i el portal aporten la infraestructura de cobrament. Els models habituals:

Les peces tècniques són totes en aquesta lliçó: quotes al gateway per consumidor, mesura amb les mètriques per consumidor, plans al portal, i la facturació integrada amb la passarel·la.

Un avís sobre la mesura, que és on es cometen els errors cars: cal decidir explícitament si es cobren les crides fallides. Cobrar un 500 propi és indefensable; no cobrar un 429 pot incentivar l'abús. I la mesura ha de ser auditable: un client té dret a veure el seu consum desglossat i a quadrar-lo amb la seva factura.

Per a la Botiga Aroma, l'API no és el producte: és el canal. Un repartiment d'ingressos amb CataBox per comandes referides tindria més sentit que cobrar per crida.

• Posar un gateway tenint una sola API. Hi afegeixes un punt de fallada, latència i una eina més per operar, a canvi de gairebé res. El gateway es justifica amb diversos serveis o amb tercers per gestionar.
• Treure l'autenticació de l'aplicació perquè el gateway la fa. Si algú arriba al servei esquivant el gateway, la teva API està completament oberta. Zero trust, sempre.
• Delegar l'autorització a nivell de recurs. El gateway no pot saber que com_5001 és de cli_842. És la fallada número u de l'OWASP API Top 10 i no té solució fora de l'aplicació.
• Ficar lògica de negoci al gateway. Regles de domini en un script Lua sense proves, sense tipus i sense revisió. És l'error més car de revertir.
• Configurar CORS al gateway i a l'aplicació amb llistes diferents. Un origen funciona en un entorn i falla en un altre, i depurar-ho porta hores perquè cada capa sembla correcta. Una política, un amo.
• Oblidar exposed_headers al gateway. El navegador rep ETag i Link però JavaScript no els pot llegir. És l'error de CORS més frustrant de 04-05.
• trust proxy mal configurat. Amb menys salts dels que hi ha, la IP real es perd; amb més, un atacant la pot falsificar. El número ha de coincidir exactament.
• Configurar el gateway per interfície gràfica. Ningú no recorda què s'ha canviat ni per què, i es perd a la reconstrucció següent. Configuració declarativa versionada i aplicada des de la canalització.
• No provar contra el gateway. El recorregut de Newman de 05-01 ha d'apuntar al gateway. Un strip_path equivocat o un CORS mal posat es descobreixen en producció si no.
• Un portal que només és Swagger UI. La referència sense guia d'inici, sense pàgina d'errors i sense exemples executables deixa qui s'integra buscant on començar.
• Aprovació manual per a l'entorn de proves. Multiplica el TTFHW per cent i fa que la gent provi l'API de la competència mentre espera.
• Un entorn de proves buit. La primera crida retorna {"dades": [], "total": 0} i sembla trencada. Sembra'l amb dades fictícies riques.
• Consell: mesura el TTFHW amb una persona real i un cronòmetre. Una hora d'observació produeix millor informació que qualsevol enquesta.
• Consell: abans de retirar una versió, fes una apagada de prova. Unes hores de 410 en una data anunciada descobreixen tots els consumidors que quedaven, cosa que cap correu d'avís no aconsegueix.
• Consell: documenta en un ADR (04-01) quina política viu al gateway i quina a l'aplicació. És la informació que falta el dia de l'incident.

La Botiga Aroma posarà Kong davant de l'API. Per a cada requisit, decideix si s'implementa al gateway, a l'aplicació o a tots dos, i justifica-ho:

1. Rebutjar peticions sense token vàlid.
2. Comprovar que un client només veu les seves pròpies comandes.
3. Limitar CataBox a 10.000 crides al mes.
4. Rebutjar preuMin més gran que preuMax.
5. Bloquejar un rang d'IP que està atacant l'inici de sessió.
6. Retornar 409 comanda_ja_pagada si la comanda ja s'ha pagat.
7. Permetre peticions des de https://panel.botigaaroma.example i de cap altre origen.
8. Exigir la capçalera Idempotency-Key a POST /v1/comandes.
9. Rebutjar cossos més grans de 100 KB.
10. Retornar 304 quan l'ETag coincideix amb If-None-Match.

La Botiga Aroma publica /v2, que viu en un servei separat (api-v2.intern:3000), mentre /v1 continua al servei actual amb sis mesos de convivència. Escriu la configuració declarativa de Kong necessària: els serveis i rutes, com s'apliquen els mateixos plugins de rate limiting i CORS a totes dues versions sense duplicar configuració, i com s'afegeixen les capçaleres Deprecation, Sunset i Link amb la successora només a les respostes de /v1. Indica també què passa el dia del Sunset.

Un portal de la competència té: pàgina d'inici amb la proposta de valor, referència completa generada d'OpenAPI amb consola «prova-ho ara», formulari de contacte per sol·licitar accés —resposta en 2-3 dies laborables—, PDF amb els plans i preus, i una pàgina d'estat del servei.

Identifica almenys cinc mancances greus, estima el TTFHW resultant justificant l'estimació, i proposa un pla prioritzat de millora amb les tres primeres accions, indicant quina mètrica esperaries moure amb cadascuna.

Patró que emergeix: tot el que depèn del contingut o de l'estat persistit es queda a l'aplicació; tot el que depèn de qui crida i quant crida va al gateway; i el que és barat de comprovar dues vegades es fa a tots dos llocs.

Com s'evita la duplicació: els plugins declarats al nivell superior (sense service ni route) són globals i s'apliquen a totes les rutes. Només es declara per servei o per ruta el que difereix, que aquí és únicament el response-transformer amb les capçaleres de deprecació. Canviar el límit global és una línia que afecta totes dues versions.

Detall que sempre s'oblida: Deprecation i Sunset han de ser a exposed_headers del plugin de CORS. Si no, el navegador les rep però la SPA no les pot llegir, i la instrumentació que volies —que el front avisi a la consola que fa servir una versió obsoleta— no funciona.

Què passa el dia del Sunset (30 de juny de 2027):

Seqüència recomanada:

1. Mesos abans: capçaleres Deprecation i Sunset actives (ja ho són), avisos al changelog del portal, i correus als consumidors identificats per les mètriques del gateway, que diuen exactament qui continua cridant /v1 i amb quin volum.
2. Un mes abans: apagada de prova de dues hores, anunciada. Apareixen els resseguidors.
3. El dia del Sunset: s'activa el request-termination amb 410. 410 Gone i no 404, perquè 410 significa «va existir i es va retirar deliberadament», que és informació útil per a qui depura.
4. Setmanes després: s'elimina la ruta de la configuració i s'apaga el servei api-v1. El 410 deixa pas al 404 genèric.

Es manté el 410 explicatiu durant setmanes en lloc d'esborrar la ruta immediatament perquè un 404 sec deixa el consumidor sense saber què ha passat, mentre que el 410 amb enllaç a la guia de migració és autoexplicatiu.

Cinc mancances greus:

1. Accés amb aprovació manual de 2-3 dies. És la mancança més greu amb diferència. Converteix una avaluació de cinc minuts en un projecte d'una setmana, i qui avalua alternatives provarà la de la competència mentre espera. Molts no tornen mai.
2. No hi ha entorn de proves amb credencials immediates. Conseqüència de l'anterior: no es pot tocar res sense permís, així que la consola «prova-ho ara» és decorativa. Ningú no pot avaluar l'API sense comprometre's abans.
3. Només hi ha referència, no guies. La referència diu quins camps accepta POST /comandes; no explica la idempotència, la paginació, com reintentar davant d'un 429 o com verificar la signatura d'un webhook. Sense això, totes les integracions es fan malament de la mateixa manera i el cost es trasllada a suport.
4. Preus en un PDF. Un PDF no es pot enllaçar a una secció concreta, es desactualitza sense que ningú se n'adoni, no és accessible i transmet que la informació és estàtica. A més, si els plans són en PDF, les quotes tècniques probablement no estiguin documentades enlloc.
5. No hi ha changelog ni política de deprecació. És la mancança que més por fa a qui construirà un negoci a sobre: no hi ha manera de saber si l'API canviarà ni amb quant d'avís. Sense un compromís públic de compatibilitat, integrar-s'hi és assumir un risc indefinit.

Mancances addicionals: no hi ha pàgina d'errors amb el catàleg de codis; no es veu una col·lecció de Postman ni exemples executables; res no indica els límits d'ús tècnics; i no hi ha clients generats ni SDK (05-02).

Estimació del TTFHW: 2-3 dies laborables. El desglossament justifica la xifra: descobriment i lectura, 10 minuts; omplir el formulari, 5 minuts; espera d'aprovació, 2-3 dies; configurar l'autenticació amb documentació incompleta, 30-60 minuts; primera crida amb èxit, 10 minuts. El temps actiu són uns 90 minuts; el temps transcorregut, tres dies. I el que compta comercialment és el transcorregut, perquè és el que determina si la persona continua interessada.

Pla prioritzat — tres primeres accions:

Acció 1 (impacte altíssim, cost mitjà): registre automàtic per a l'entorn de proves. Qualsevol es registra amb un correu, crea una aplicació i obté client_id i client_secret de proves a l'instant. L'aprovació manual es conserva només per a producció, que és on de debò cal. El sandbox ha d'estar sembrat amb dades fictícies riques perquè la primera crida retorni alguna cosa interessant. Mètrica esperada: TTFHW de 2-3 dies a menys de 15 minuts. És un canvi d'ordre de magnitud i, per si sol, justifica el projecte.

Acció 2 (impacte alt, cost baix): guia d'inici de quatre passos i pàgina d'errors. Una pàgina amb registre → token → primera crida → passos següents, amb ordres curl copiables i provades a CI perquè no es desactualitzin mai (05-04 ja ens va ensenyar a provar que els exemples del contracte funcionen). I una pàgina amb el catàleg complet d'errors: què significa cada codi, si convé reintentar-ho i què fer. Mètrica esperada: reducció del temps actiu de 90 a 20 minuts, i caiguda dels tiquets de suport de primer nivell, que solen ser el 60-70 % del total i gairebé sempre són «no entenc aquest error».

Acció 3 (impacte mitjà-alt, cost baix): changelog públic i compromís de compatibilitat. Una pàgina amb l'historial de canvis, un compromís explícit —«no eliminem camps sense sis mesos d'avís; els canvis trencadors van en una versió major de la ruta»— i subscripció per correu o RSS. És la peça que converteix una API que es prova en una API sobre la qual algú s'atreveix a construir un producte. Mètrica esperada: conversió de comptes de prova a integracions en producció. I, a mitjà termini, menys incidències a cada desplegament, perquè els consumidors s'assabenten dels canvis abans de patir-los.

Després: publicar els preus en HTML, oferir la col·lecció de Postman amb un botó d'importar, generar SDK amb OpenAPI Generator (05-02) i documentar els límits tècnics al costat dels plans.

Has vist la capa que envolta l'API per fora. Un API gateway centralitza les preocupacions transversals del trànsit —rate limiting, terminació TLS, validació de JWT i OAuth per JWKS, CORS, compressió, encaminament per versió, quotes per consumidor, mètriques, mTLS amb socis, llistes negres— i les converteix en configuració declarativa versionable en lloc de codi repetit a cada servei. Tens la seva configuració real per a la Botiga Aroma a gateway/kong.yaml, amb els mateixos límits de 04-04 i el seu fault_tolerant decidit ruta a ruta, la llista blanca de 04-05 amb els exposed_headers que gairebé tothom oblida, el correlation-id que propaga l'Aroma-Traca-Id de 04-07 i el plugin de Prometheus segmentat per consumidor; i l'alternativa equivalent a gateway/nginx.conf, amb l'X-Forwarded-For que dona sentit al trust proxy 1 de la posició 1 de src/app.js.

I tens el criteri, que val més que la configuració: el gateway sap qui crida i on; només l'aplicació sap què hi ha a dins i què significa. Per això el rate limiting, el TLS, la validació criptogràfica del token i el CORS es deleguen bé, mentre que l'autorització a nivell de recurs, la lògica de negoci i la validació semàntica no es deleguen mai —i per això, amb el gateway al davant, dels setze middlewares de src/app.js només se'n retiren un o dos—. El valor no és aprimar la teva aplicació, sinó la consistència entre diversos serveis, la gestió de consumidors que abans no existia i poder canviar polítiques sense desplegar. Tot això assumint-ne els riscos amb els ulls oberts: punt únic de fallada, latència afegida, configuració divergent i la temptació sempre present de ficar regles de negoci on no hi ha proves ni revisió.

La segona meitat de la lliçó era l'altra cara: un portal de desenvolupador amb guia d'inici de quatre passos, referència generada de l'openapi.yaml de 05-02, consola interactiva, registre d'aplicacions amb credencials OAuth immediates per a l'entorn de proves, pàgina d'errors amb el catàleg de 02-04, changelog amb els avisos de deprecació de 02-07, límits, estat del servei i suport. Amb una mètrica que ho resumeix tot, el temps fins a la primera crida amb èxit, que es mesura amb una persona real i un cronòmetre i que decideix si la teva API s'adopta o s'abandona la primera hora. I amb la gestió del cicle de vida i de l'inventari, on el gateway es converteix en la font de veritat de què està exposat i les mètriques per consumidor responen amb noms i volums a la pregunta «qui continua fent servir /v1?» abans de retirar-la —amb una apagada de prova d'unes hores, que descobreix resseguidors com no ho aconsegueix cap correu—.

Amb això es tanca el mòdul 5. L'API de la Botiga Aroma ja no està sola: té una col·lecció de Postman executable a CI, un contracte OpenAPI complet que serveix de documentació, de mock, de validador i de generador de clients, la perspectiva per saber què hauria canviat amb un altre framework i què no, proves de contracte que impedeixen que el codi i el contracte se separin juntament amb una porta que detecta canvis trencadors, una canalització que construeix, prova i desplega sense talls amb migracions retrocompatibles i retorn enrere, i una capa de gateway i portal que la protegeix i l'explica. És una API operable i consumible, no només correcta.

El que falta ja no és cap peça solta: és veure tot això junt, aplicat de principi a fi i sostingut en el temps. Al mòdul 6, Casos d'Estudi i Projectes, deixem les eines i tornem al disseny amb tot el que hem après al damunt: un cas d'estudi complet de l'API d'una botiga en línia, recorrent les decisions des dels recursos fins al desplegament (06-01); un segon cas, el d'una xarxa social, on els problemes són diferents —grafs de relacions, línies de temps, paginació per cursor a gran escala, contingut generat per usuaris i moderació— i obliguen a replantejar diverses de les decisions que aquí vam donar per bones (06-02); l'evolució i el manteniment d'una API en producció, és a dir, què passa els tres anys següents al llançament: deute de contracte, migracions de versió, incidents reals i retirada de funcionalitats (06-03); i el projecte final, en què dissenyaràs i desenvoluparàs la teva pròpia API RESTful aplicant els sis mòduls complets (06-04).