API-first: per què la teva startup hauria de pensar en les APIs des del primer dia

Fa anys que veig repetir-se la mateixa història. Una startup construeix el seu producte web. Frontend i backend fortament acoblats, lògica de negoci barrejada amb lògica de presentació, dades que circulen per camins que només entén el desenvolupador original. El producte funciona. Els usuaris arriben.

I llavors algú diu: «Necessitem una app mòbil.» O «Aquest client enterprise vol integrar el nostre servei a la seva plataforma.» O «Traguem una versió white-label.»

I de cop tot s'atura. Perquè no hi ha cap API neta. El que hi ha és un monòlit on l'única manera d'accedir a les dades és a través del frontend web. I reescriure-ho costa mesos.

Dissenyar el producte com a API-first no és sobreenginyeria. És la decisió que t'estalvia aquesta reescriptura. I et concedeixo l'objecció òbvia: abans del product-market fit, escriure primer el contracte sí que sembla cerimònia, i sí que et demana una certa disciplina d'entrada. Però el preu és pensar diferent, no construir més — i l'alternativa és la reescriptura que costa mesos.

Què vol dir API-first, de debò

API-first no vol dir «tenir una API». Gairebé tots els productes moderns tenen alguna mena d'API. API-first vol dir una cosa més concreta: dissenyes el contracte de l'API abans de construir-ne la implementació.

L'API és el producte. Tota la resta — el frontend web, l'app mòbil, les integracions — són consumidors d'aquesta API. Cap no rep tracte de favor. El teu frontend web fa les mateixes crides que faria un client extern.

El flux de treball canvia de soca-rel:

1. Defineixes el contracte: quins endpoints hi ha, quins paràmetres accepten, quines respostes retornen, quins errors són possibles.
2. Documentes el contracte: OpenAPI/Swagger, amb exemples reals per a cada endpoint.
3. Crees mocks: el frontend pot començar a construir contra endpoints simulats que retornen dades d'exemple.
4. Desenvolupes en paral·lel: frontend i backend treballen alhora contra el contracte acordat.
5. Integres i testes: quan totes dues bandes estan a punt, integrar és només comprovar que tot compleix el contracte.

Això no és teoria. És com treballen de debò els equips d'enginyeria més productius que conec.

Els beneficis concrets per a una startup

No et vull vendre l'API-first amb arguments abstractes. Aquests són els beneficis que veuràs a la pràctica:

Frontend i backend evolucionen de manera independent. El dissenyador pot iterar sobre la UI sense esperar que el backend estigui enllestit. L'enginyer de backend pot optimitzar queries sense tocar el frontend. Els desplegaments són independents. Els bugs s'aïllen més fàcilment.

Afegir una app mòbil esdevé trivial. Si l'API ja serveix tot el que necessita el frontend web, una app mòbil només ha de consumir els mateixos endpoints. Ni lògica duplicada ni endpoints nous a crear. L'API ja existeix i està documentada.

Les integracions amb tercers passen a ser plug-and-play. Quan un client vol connectar el teu servei amb el seu CRM, no cal construir cap integració a mida. L'API pública ja hi és, documentada i provada.

Els tests són més clars. Provar una API és més senzill que provar un frontend acoblat a un backend. Fas una petició i en verifiques la resposta. Sense navegadors, sense DOM, sense flakiness.

Escalar és més fàcil. Pots escalar l'API independentment del frontend. Pots fer cache de respostes a nivell d'API. Pots afegir rate limiting sense tocar la lògica de negoci.

REST per defecte, GraphQL per excepció

La primera decisió tècnica d'una estratègia API-first és el protocol. El 2024, les dues opcions dominants són REST i GraphQL.

REST és l'opció per defecte. Si no tens un motiu concret per fer servir GraphQL, fes servir REST. És més simple, té millor tooling, tots els enginyers el coneixen, les caches HTTP funcionen de manera nativa i depurar és trivial amb qualsevol eina que parli HTTP.

GraphQL té sentit quan:

• El frontend necessita dades de múltiples recursos en una sola pantalla i l'over-fetching amb REST és un problema real (no teòric).
• Tens diversos clients (web, mòbil, TV) amb necessitats de dades molt diferents.
• El graf de dades és complex i les relacions entre entitats són profundes.

GraphQL NO té sentit quan:

• Tens un sol frontend i un backend simple.
• El teu equip no té experiència amb GraphQL (la corba d'aprenentatge és real).
• Valores la simplicitat operativa (la cache, el monitoratge i la seguretat són més complexos amb GraphQL).

Per a la majoria de startups en fase inicial, REST amb endpoints ben dissenyats és la resposta correcta. Sempre hi ets a temps d'afegir GraphQL com una capa per sobre de l'API REST.

Sis decisions que separen una API REST sòlida d'una que fa patir

Aquests són els principis que separen una API ben dissenyada d'una que genera maldecaps:

Naming consistent. Substantius en plural per als recursos, verbs HTTP per a les accions. /users, /orders, /products. No pas /getUser, /createOrder, /deleteAllProducts. El verb HTTP ja indica l'acció: GET, POST, PUT, DELETE.

Codis d'estat HTTP correctes. 200 per a èxit, 201 per a creació, 400 per a error del client, 401 per a no autenticat, 403 per a no autoritzat, 404 per a no trobat, 422 per a validació fallida, 500 per a error del servidor. No retornis un 200 amb un body que digui {"error": true}.

Paginació des del primer dia. Tot endpoint que retorni llistes ha d'anar paginat. Tant és que avui només tinguis 50 registres: quan en tinguis 50.000, passar un endpoint de no paginat a paginat trenca tots els clients que el consumeixen. La paginació per cursor és més robusta que offset/limit per a dades que canvien sovint.

Errors estandarditzats. Defineix un format d'error consistent i fes-lo servir a tota l'API:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "El camp email és obligatori",
    "details": [
      {"field": "email", "message": "Aquest camp és obligatori"}
    ]
  }
}

No t'inventis un format diferent per a cada endpoint. El frontend ha de poder parsejar els errors de manera genèrica.

Versionat des del principi. /api/v1/users. Quan hagis de fer breaking changes, crea /api/v2/users i mantén la v1 durant un període de transició. Sense versionat, qualsevol canvi a l'API pot trencar clients existents.

Autenticació estàndard. JWT per a la majoria de casos. OAuth2 si necessites que tercers accedeixin a les dades dels teus usuaris. No et muntis el teu propi sistema d'autenticació. Fes servir una llibreria contrastada i segueix els estàndards.

Els errors que veig més sovint

Després d'haver revisat desenes d'APIs de startups, aquests són els patrons que fan més mal:

• Exposar IDs interns. Si la base de dades fa servir IDs autoincrementals, un atacant pot enumerar tots els teus recursos. Fes servir UUIDs o IDs públics separats dels interns.
• No tenir rate limiting. Sense rate limiting, un script mal escrit (o un de maliciós) pot tombar-te l'API. Implementa'l des del principi, encara que sigui generós (1.000 peticions per minut és raonable per començar).
• Naming inconsistent. Un endpoint fa servir user_id, un altre userId, un altre UserID. Tria una convenció i mantén-la a tota l'API. És un problema sorprenentment habitual quan hi contribueixen diversos desenvolupadors sense una guia d'estil.
• Respostes que retornen massa coses. Un endpoint /users que retorna el hash de la contrasenya, el token de sessió i dades internes. Dissenya les respostes a partir del que necessita el client, no del que té la teva base de dades.
• No documentar. Una API sense documentació és una API que només pot fer servir qui l'ha escrita. OpenAPI/Swagger no és opcional: és part del producte.

El flux de treball que t'elimina el coll d'ampolla més gran

Un sprint en un equip API-first té aquesta pinta:

1. Planificació: l'equip defineix quina funcionalitat es construirà i dissenya els endpoints necessaris. El contracte s'escriu en OpenAPI.
2. Mocking: s'aixequen endpoints mock que retornen dades d'exemple seguint el contracte. Eines com Prism o Mockoon ho fan en qüestió de minuts.
3. Desenvolupament en paral·lel: el frontend construeix contra els mocks; el backend implementa la lògica real. Tots dos avancen alhora sense bloquejar-se.
4. Integració: quan tots dos estan a punt, el frontend es connecta al backend real. Si el contracte s'ha respectat, hauria de funcionar amb canvis mínims.
5. Tests de contracte: tests automatitzats verifiquen que la implementació real compleix exactament el contracte definit. Si algú canvia l'API sense actualitzar el contracte, els tests fallen.

Aquest flux elimina el coll d'ampolla més gran dels equips de producte: la dependència seqüencial entre frontend i backend.

API-first és una decisió de velocitat, no una moda

És una decisió arquitectònica que determina la teva velocitat de desenvolupament a mitjà termini. Les startups que adopten API-first des del principi poden:

• Llançar una app mòbil en setmanes, no en mesos.
• Integrar-se amb partners sense construir res a mida.
• Pivotar el frontend sense tocar el backend.
• Oferir versions white-label reutilitzant la mateixa API.
• Escalar frontend i backend de manera independent.

A Conectia, els enginyers de backend que connectem amb startups europees pensen en API-first per defecte. No perquè sigui una buzzword, sinó perquè han vist què passa quan no ho fas: reescriptures cares, integracions doloroses i mesos llençats.

Un enginyer sènior que et dissenyi bé l'API des del primer dia no és un cost: és una inversió que s'amortitza la primera vegada que has de connectar un client nou al teu sistema.

---

Necessites un enginyer de backend que et dissenyi l'API des del primer dia pensant en escala i integració? Parla amb un CTO — et connectem amb enginyers sènior que construeixen APIs que no hauràs de reescriure.