Evitar el caos d'interfícies: governança d'API que funciona també sense estructures de grans empreses

En moltes empreses el caos d’interfícies no sorgeix per «mala tècnica», sinó per la manca de baranes de seguretat. Un nou programari empresarial necessita dades de l’ERP, un portal ha de mostrar l’estat de les comandes, un proveïdor integra un sistema de tercers – i de sobte hi ha dotzenes d’extrems, importacions de fitxers, accessos directes a bases de dades i cronjobs «temporals» que fa anys que funcionen en producció. Precisament aquí entra en joc la Governança d’API: no com a burocràcia de gran empresa, sinó com un marc pràctic que defineix responsabilitats, estàndards i regles d’explotació amb la claredat necessària perquè les interfícies continuïn sent fiables, segures i mantenibles.

El nucli del problema: la majoria d’organitzacions TI de mida mitjana no disposen ni d’un architecture board central amb rols a temps complet ni de la capacitat per revisar cada projecte durant mesos. Malgrat això, la integració, la seguretat i l’operació han de funcionar —i en el dia a dia, amb releases que es duen a terme en paral·lel, les àrees de negoci pressionant i sistemes antics en funcionament. Aquest article mostra com es pot construir una governança d’API «lleugera»: amb poques però coherents regles, artefactes clars i un procés que accelera els projectes en lloc d’aturar-los.

Per què el caos d’interfícies surt tan car — i gairebé sempre es detecta massa tard

Les interfícies sovint es consideren una tasca purament d’implementació: «Només necessitem un endpoint» o «un export en CSV és suficient». Els costos derivats apareixen més endavant — típicament quan l’empresa creix, es modernitzen sistemes o apareixen nous requisits de compliment normatiu. Símptomes freqüents en l’explotació:

• Responsabilitats poc clares: Ningú sap qui opera una API, qui valida canvis o qui intervé en cas d’avaries.
• Dependències fràgils: Un release al sistema A trenca silenciosament processos al sistema B perquè s’han modificat noms de camp o la semàntica.
• Bretxes de seguretat: APIs «internes» passen a ser utilitzades externament, l’autenticació és inconsistent o els permisos són massa genèrics.
• Depuració difícil: Falten logs, no es pot correlacionar esdeveniments i els informes dels departaments de negoci són vagues («El portal va lent»).
• Embussos d’integració: Nous projectes no topen amb la funcionalitat, sinó amb dependències i la manca de transparència sobre els fluxos de dades.

El més desagradable: mentre tot «d’alguna manera funciona», la governança sembla un overhead. Només en cas d’avaries, projectes de migració o auditories es fa evident que les interfícies no són només punts finals tècnics, sinó contractes entre sistemes i equips — amb obligacions sobre estabilitat, seguretat i comunicació.

Governança d’API sense gran corporació: què vol dir realment

La governança d’API és un conjunt de rols, regles i evidències que garanteix que les APIs (i altres vies d’integració) es desenvolupen i s’exploten de manera controlada al llarg del seu cicle de vida. «Governança» sona a comitès i cadenes d’aprovació — en la pràctica hauria de funcionar més com un sistema de trànsit: poques regles clares que evitin col·lisions sense haver d’autoritzar cada trajecte individualment.

Per a empreses sense estructura de grup, es recomana un enfocament basat en tres preguntes clau:

• Qui és l’owner? (a nivell funcional i tècnic) — i què vol dir això en l’explotació?
• Quin és el contracte? (dades, semàntica, versionat, SLAs/SLOs) — i on es pot trobar?
• Com es canvia? (procés de canvi, proves, deprecació) — sense sorpreses per als consumidors?

És important fer la delimitació: API-Governance no és el mateix que API-Management. API-Management sol referir-se a funcions de plataforma com gateway, gestió de claus, quotes, analytics. API-Governance defineix les regles segons les quals s’utilitzen aquestes funcions — i funciona també quan (encara) no s’ha introduït una gran eina.

Punt d’inici per a la governance: inventari en comptes d’ideologia

Abans d’escriure regles, val la pena un cop d’ull pragmàtic a la realitat. En paisatges creixents sovint coexisteixen diversos patrons d’integració: REST-API, SOAP, transferència de fitxers, accessos directes a BD, EDI, messaging, ETL. L’API-Governance no pot ignorar aquesta diversitat, si no apareixen integracions en ombra.

Un primer pas sensat és un inventari d’interfícies amb un abast mínim obligatori. No cal que sigui un projecte mastodòntic — però ha de ser prou complet per identificar riscos. A la pràctica, al començament basten 10–15 camps per interfície, per exemple:

• Sistema A (provider) i sistema B (consumer) incl. punts de contacte
• Tipus d’integració (REST, fitxer, missatge, enllaç BD …)
• Categories de dades (p. ex. registre de clients, comandes, preus) i necessitat de protecció
• Freqüència/latència (batch diari, quasi en temps real, síncron)
• Via d’operació (on s’executa, com es monitoritza, qui respon)
• Risc de canvi (procés crític, molts consumidors, històricament inestable)

Aquest inventari és la palanca per a les decisions: quines interfícies necessiten estàndards en primer lloc? On amenacen punts únics de fallida? Quins sistemes bloquegen la modernització perquè tenen „massa“ acoblaments durs? I: on té sentit un API-Gateway — i on no?

Rols i responsabilitats: sense un responsable no hi ha estabilitat

La regla de governance més important és d’organització: cada interfície productiva necessita un responsable. „Responsable“ no vol dir que una sola persona ho faci tot. Vol dir: hi ha una responsabilitat inequívoca, que en cas de dubte decideix i prioritza.

Model mínim de rols per a equips de mida mitjana

• API Owner (funcional): És responsable de l’objectiu, la semàntica funcional (què significa un camp?), i de l’aprovació de canvis incompatibles des de la perspectiva del negoci.
• API Owner (tècnic): És responsable de l’explotació, els estàndards de seguretat, el rendiment, el monitoratge i la capacitat de desplegament.
• Responsables de consumidors: Designen punts de contacte, assumeixen adaptacions en cas de deprecació i compleixen els estàndards de consum.

En la pràctica, s’ha demostrat que convé vincular la responsabilitat a un equip de sistema o a un equip de producte — no a un projecte. Un cop un projecte acaba, les API es mantenen. Per això ha d’estar clar qui després de la posada en producció s’encarrega d’aplicar pegats, registre, certificats, temps d’execució, deprecació i suport.

Contractes d’interfície: què necessiten realment els consumidors

Un contracte d’interfície és més que una descripció tècnica. És la base vinculant perquè dues parts puguin treballar de manera independent. Per a REST-APIs, OpenAPI (una especificació llegible per màquina per a endpoints, paràmetres, payloads) és un estàndard consolidat. Però fins i tot sense un tooling perfecte val: el contracte ha de ser localitzable, versionat i comprensible.

Què ha d’incloure un contracte d’API pràctic

• Propòsit i àmbit: Què lliura l’API — i què expressament no?
• Model de dades incl. semàntica: Quins camps són obligatoris, quins són opcionals? Què vol dir concretament «Status»?
• Comportament en errors: Quins codis d’error/llistats de classes d’error existeixen, què és transitori (té sentit reintentar) i què és permanent?
• Objectius de rendiment i disponibilitat: No com a SLA de màrqueting, sinó com a objectiu operatiu (p. ex. latència objectiu, finestres de manteniment).
• Limitacions: Rate limiting (limitació de peticions), mides màximes, paginació, timeouts.
• Seguretat: Autenticació (p. ex. OAuth 2.0), autorització (rols/Scopes), transport (TLS), registre/auditoria.
• Regles de canvi: Versionat, terminis de deprecació, via de comunicació.

Important per a persones no desenvolupadores: el contracte redueix la necessitat de coordinació. La direcció de projecte i l’àrea funcional obtenen claredat sobre si una exigència «entra en el contracte» o si requereix una nova API/versió. En explotació, el contracte és la referència per fer un triatge net dels incidents: es tracta d’un problema de dades, d’un problema d’autorització o d’un problema de disponibilitat?

Versionat i Breaking Changes: L’entrebanc de governança més habitual

La majoria de problemes d’integració no sorgeixen a l’hora de la primera implementació, sinó durant els canvis. Breaking Change vol dir: un canvi que obliga els consumidors existents a adaptar el seu client; en cas contrari el procés deixa de funcionar. Exemples clàssics són camps renombrats, camps obligatoris canviats o semàntica modificada (p. ex. valors d’estat).

Regles pragmàtiques que funcionen en el dia a dia

• La compatibilitat és l’estàndard: Sempre que sigui possible, dissenyar els canvis perquè els consumidors antics continuïn operant (p. ex. afegir nous camps opcionals).
• Els Breaking Changes requereixen una nova versió: La versió pot indicar-se en la ruta, en un header o com un producte d’API separat — l’important és la separació clara.
• Deprecació amb termini: Una versió antiga no s’apaga «demà». Hi ha un termini definit i una rutina de comunicació.
• El Sunset és un procés: L’apagada es fa amb monitoratge de qui encara accedeix i amb una escalada final cap a l’owner.

Per a la direcció d’IT, aquest és el nucli econòmic: sense regles de versionat, els canvis es tornen costosos, perquè cada projecte ha de reconstruir la compatibilitat amb versions anteriors o perquè les releases queden bloquejades. Amb regles clares disminueixen els costos derivats i els equips poden treballar en paral·lel.

Seguretat d’API a la pràctica: uniformitat en lloc de „cada sistema a la seva manera“

La seguretat en interfícies rarament falla per la criptografia, sinó per la inconsistencia. Un sistema utilitza Basic Auth, un altre API-Keys, un tercer llistes blanques d’IP internes. Mentre tot sigui intern sembla factible. Alhora d’integrar partners, xarxes de teletreball, requisits de Zero-Trust o en la resposta a incidents, això esdevé arriscat.

Estàndards mínims que gairebé sempre són aplicables

• Xifrat del transport (TLS): Cap excepció per a „intern“. Fins i tot en entorns interns hi ha risc d’intercepció i de configuracions errònies.
• Identitat centralitzada, allà on sigui possible: SSO/Identity Provider i tokens (p. ex. OAuth 2.0 / OpenID Connect) redueixen solucions a mida. OAuth 2.0 és un estàndard per a l’autorització delegada; els tokens porten permisos i són limitats en el temps.
• Least Privilege: Els consumidors obtenen només els drets que necessiten (Scopes/Rollen), no „Admin, perquè és més fàcil“.
• No posar dades sensibles a les URLs: Les ID estan bé; dades personals o contingut confidencial no han d’anar en paràmetres de consulta, ja que poden acabar als logs i als proxies.
• Registre auditable: Qui va cridar què i quan? Com a mínim a nivell de sistema amb correlació i detalls d’errors, sense registrar dades personals de manera innecessària.

Governança vol dir aquí: definir un Security-Profil per cada classe d’API (intern, partnerfähig, públic) i vincular-hi els requisits corresponents. Això evita que cada projecte renegociï què és „suficientment segur“.

Operació i observabilitat: sense mesurabilitat no hi ha SLAs fiables

Les APIs són programari d’operació. Per això, la monitorització, el registre i la traçabilitat (capacitat de seguir transaccions a través de sistemes) han d’estar dins la governança. Observabilitat no vol dir només „un panell de control“, sinó la capacitat d’interpretar senyals (mètriques, logs, traces) per inferir l’estat d’un sistema.

Què compta realment en el dia a dia

• ID de correlació: Un identificador únic que acompanya cada petició i apareix en els logs de tots els sistemes implicats. Això redueix la cerca d’errors d’hores a minuts.
• Golden Signals: latència, taxa d’errors, trànsit i saturació (CPU, fils, cues). Aquestes quatre perspectives sovint són suficients per a un diagnòstic inicial estable.
• Rate Limiting & Backpressure: Quan un consumidor „satura“, el sistema ha de poder protegir-se (Quotas, encolament, rebuig controlat).

La governança estableix aquí la directriu que aquestes coses han d’existir – no pas necessàriament quina eina s’ha d’utilitzar. Precisament els equips més petits en surten beneficiats si defineixen per cada classe d’interfície un estàndard mínim i l’exigeixen de manera consistent.

Regles de disseny per a interfícies robustes: menys sorpreses, menys casos excepcionals

Molts problemes s’originen en implementacions „creatives“: formats especials, paginació incoherent, objectes d’error inconsistents. La governança no ha de prescriure cada qüestió de format, però unes quantes directrius tècniques estalvien molt de temps més endavant al suport i a l’ampliació.

Directrius provades per a les API REST en l’entorn empresarial

• Identificadors de recursos estables: Les ID no han de canviar quan es corregeixen les dades mestres. Si no, es trenquen les referències.
• Idempotència: Una crida repetida (p. ex. per reintent) no ha de provocar duplicacions. Idempotència significa: la mateixa sol·licitud condueix al mateix estat final.
• Classes d’error clares: La distinció entre 4xx (errors del client) i 5xx (errors del servidor) ha de ser fiable perquè els consumidors puguin reaccionar de forma útil.
• Estandarditzar paginació i filtratge: Grans volums de dades no han de lliurar-se „tot d’una“. Si no, apareixen timeouts i problemes de memòria.
• Evolució d’esquema: Afegir nous camps és normal – els consumidors han de poder-ho gestionar sense bloquejar-se.

Això és rellevant per a la direcció de projecte perquè impacta directament en l’esforç i els riscos: si els consumidors compleixen estàndards robustos, disminueix el nombre de „hotfixes d’interfície“ després dels llançaments.

Cicle de vida de l’API com a procés lleuger: de la idea fins a la desactivació

Sense un procés de cicle de vida, les API es „construeixen i s’obliden“. Un cicle de vida pràctic consta de pocs punts de control orientats als riscos reals. L’objectiu és crear claredat d’hora, sense alentir els projectes.

Un model de 6 fases que evita la burocràcia

1. Intake: Breu descripció del cas d’ús, dades, consumidors, criticitat. Resultat: decisió „API vs. altra via d’integració“.
2. Contract First: Esbós i acord del contracte (p. ex. OpenAPI). Resultat: abast clar, menys malentesos.
3. Build: Implementació incloent perfil de seguretat, registre i monitoratge bàsic.
4. Go-live Readiness: Comprovació d’artefactes d’operació (Runbook, alerts, responsables, finestres de manteniment).
5. Operate: Operació normal amb ritme de revisió (errors, latència, costos, feedback dels consumidors).
6. Deprecate & Retire: Les versions antigues s’anuncien i s’esborren de manera planificada, incloent prova de qui encara les utilitza.

Important: aquests punts de control no són „aprovacions des de la torre d’ivori“, sinó breus punts de control que donen suport als equips. En la pràctica sovint n’hi ha prou amb una revisió de 30–45 minuts per cada llançament d’API, si el contracte i els estàndards mínims estan definits.

Tooling: Què ajuda sense haver d’iniciar un projecte de plataforma

Moltes empreses ajornin la governança perquè creuen que primer cal comprar una plataforma de gestió d’API. Això rarament és el millor primer pas. El tooling hauria de donar suport al procés — no substituir-lo.

Elements pragmàtics d’alt valor

• Portal d’API central o secció de Wiki: Un lloc on consten els contractes, els registres de canvis i els responsables. Important és la facilitat per trobar-los.
• Repositori per a especificacions: Fitxers OpenAPI versionats i notes de migració. Així els canvis són rastrejables.
• Flux de tickets per a canvis: Una plantilla simple: «Què canvia? Trencador (breaking)? Termini? Responsable? Indicacions de prova?»
• Checks automatitzats: Linting d’especificacions, línies base de seguretat, smoke tests després del desplegament.

Si això existeix, un API-Gateway o una suite de gestió poden ser útils – sobretot si hi ha consumidors externs, quotes, autenticació centralitzada o analítica detallada. La governança assegura que el gateway no s’implanti només ‚posat davant‘, sinó que s’utilitzi de manera consistent.

Dades i semàntica: la governança no acaba a l’endpoint

Molts problemes d’integració són en realitat problemes de dades: definicions poc clares, fonts duplicades, dades mestres contradictòries. Una API pot ser tècnicament correcta i, malgrat això, provocar decisions errònies des del punt de vista funcional si la semàntica no està definida amb claredat.

La governança d’API hauria d’incloure per tant una regla senzilla: per a objectes de dades centrals (client, proveïdor, article, comanda) cal una font definida de sistema de registre, és a dir, el sistema capdavanter. Els canvis en aquests objectes han de ser rastrejables, i els consumidors han de saber quins camps són «vinculants». Això no és un macroprojecte de governança de dades, sinó una mesura de seguretat operativa concreta.

Això és especialment útil en processos de modernització: quan un sistema antic s’ha de substituir o desconnectar pas a pas, la claredat sobre la sobirania de les dades determina si la migració es fa de manera controlada o si apareixen fonts fantasma addicionals.

Col·laboració entre TI i l’àrea de negoci: la governança com a eina de comunicació

Un conflicte comú: les àrees de negoci volen resultats ràpids, TI vol estabilitat. La governança d’API pot ajudar a mitigar aquest conflicte si s’utilitza com a vocabulari comú.

En la pràctica això vol dir:

• Definir responsables funcionals que representin la semàntica i les prioritats (no només «TI decideix»).
• Fer visibles els canvis com a impacte: «Quins processos i sistemes es veuen afectats?»
• Establir criteris d’acceptació per a les interfícies: no només «endpoint disponible», sinó «comportament d’errors definit, monitoratge actiu, estratègia de reversió clara».

Així la governança no es converteix en un fre sinó en una base per a la planificació: les direccions de projecte poden planificar millor les dependències i els decisors obtenen arguments de risc més sòlids que un simple «això és tècnicament difícil».

Un pla de 30 dies per començar: començar petit, ser conseqüent

Qui vulgui introduir governança sovint fracassa per objectius massa grans. Un millor enfocament és un llançament curt i clar que aporti benefici operatiu immediat.

Setmana 1: Crear transparència

• Inventariar les 20 interfícies principals (primers els processos crítics).
• Assignar un responsable per interfície (funcional/tècnic).
• Marcar risc: ús extern, dades de caràcter personal, molts consumidors, historial d’inestabilitat.

Setmana 2: Establir estàndards mínims

• Un document resum «API-Standard»: autenticació, registre (incl. ID de correlació), versionament, termini de deprecació.
• Plantilla per al contracte d’interfície i per a la sol·licitud de canvi.

Setmana 3: Pilot per a dues APIs

• Adaptar dues APIs representatives al nou estàndard (una interna, una amb socis externs).
• Activar la supervisió/alertes i crear un runbook.

Setmana 4: Consolidar el procés

• Revisió breu dins del cicle de llançament (30–45 Minuten) per a APIs noves o modificades.
• Comunicar la regla de deprecació i incorporar-la al procés de tiquets.

Després de 30 dies la governança no està «acabat», però esdevé real: hi ha visibilitat, estàndards i un ritme. Normalment és el punt en què els equips perceben que cal menys coordinació, perquè les expectatives són més clares.

Conclusió: La governança d’API és una eina d’operacions, no una etiqueta de gestió

El caos d’interfícies rarament és un error aïllat: és un patró de manca de responsabilitat, de contractes inexistents i de canvis sense una comunicació clara. Per això una bona governança d’API no cal que sigui extensa, però sí que sigui consistent. Qui comença amb un inventari, rols clars, un contracte d’interfície pragmàtic, regles de versionat i requisits mínims de seguretat i d’observabilitat, redueix fallades, accelera projectes i fa la modernització més planificable.

Si voleu ordenar de manera estructurada el vostre entorn d’interfícies i establir una governança d’API que s’adapti als recursos i a la realitat de la vostra empresa, ho podem aclarir en una primera conversa:

Per a aquest tema també és important la gestió d’interfícies. L’article situa aquests aspectes de manera comprensible i mostra en què cal parar atenció en el dia a dia.

Parlar d’un projecte o d’un pla de modernització amb Net-Base.