API-First: Per Que la teva Startup Hauria de Pensar en APIs des del Primer Dia

La historia es repeteix constantment. Una startup construeix el seu producte web. Frontend i backend acoblats, logica de negoci barrejada amb logica de presentacio, dades que flueixen per camins que nomes el desenvolupador original enten. El producte funciona. Els usuaris arriben.

I llavors algu diu: "Necessitem una app mobil." O "Aquest client enterprise vol integrar el nostre servei a la seva plataforma." O "Oferirem una versio white-label."

I de sobte tot s'atura. Perque no hi ha una API neta. El que hi ha es un monolit on l'unica forma d'accedir a les dades es a traves del frontend web. I reescriure aixo porta mesos.

Dissenyar el teu producte com API-first no es sobreenginyeria. Es la decisio que et permet evitar aquesta reescriptura. I el millor: no costa mes temps al principi. Nomes requereix pensar diferent.

Que significa realment API-first

API-first no significa "tenir una API." Gairebe tot producte modern te algun tipus d'API. API-first significa una cosa mes especifica: dissenyes el contracte de l'API abans de construir la implementacio.

L'API es el producte. Tot el demes (el teu frontend web, la teva app mobil, les teves integracions) son consumidors d'aquesta API. Cap te privilegis especials. El teu frontend web fa les mateixes crides que faria un client extern.

El flux de treball canvia fonamentalment:

1. Defineixes el contracte: Quins endpoints existeixen, quins parametres accepten, quines respostes retornen, quins errors son possibles.
2. Documentes el contracte: OpenAPI/Swagger, amb exemples reals per a cada endpoint.
3. Crees mocks: El frontend pot comencar a construir contra endpoints simulats que retornen dades d'exemple.
4. Desenvolupes en paral·lel: Frontend i backend treballen simultaneament contra el contracte acordat.
5. Integres i testes: Quan els dos costats estan llestos, la integracio es verificar que tot compleix el contracte.

Aixo no es teoria. Es com treballen els equips d'enginyeria mes productius que conec.

Els beneficis concrets per a una startup

No et vendré API-first amb arguments abstractes. Aquests son els beneficis que veuras a la practica:

Frontend i backend es desenvolupen de forma independent. El teu dissenyador pot iterar sobre la UI sense dependre de que el backend estigui acabat. El teu enginyer de backend pot optimitzar queries sense tocar el frontend. Els deploys son independents. Els bugs s'ailllen mes facil.

Afegir una app mobil es trivial. Si la teva API ja serveix tot el que el frontend web necessita, una app mobil nomes necessita consumir els mateixos endpoints. No hi ha logica duplicada, no hi ha endpoints nous que crear. L'API ja existeix i esta documentada.

Les integracions amb tercers es tornen plug-and-play. Quan un client vol connectar el teu servei amb el seu CRM, no necessites construir una integracio custom. La teva API publica ja hi es, documentada i testada.

Els tests son mes clars. Testejar una API es mes senzill que testejar un frontend acoblat a un backend. Fas una request, verifiques la response. Sense navegadors, sense DOM, sense flakiness.

Escalar es mes facil. Pots escalar la teva API independentment del teu frontend. Pots cachejar responses a nivell d'API. Pots afegir rate limiting sense tocar el codi de negoci.

REST vs GraphQL: quan fer servir cada un

La primera decisio tecnica en una estrategia API-first es el protocol. El 2024, les dues opcions dominants son REST i GraphQL.

REST es l'opcio per defecte. Si no tens un motiu especific per a GraphQL, fes servir REST. Es mes simple, te millor tooling, tots els enginyers el coneixen, els caches d'HTTP funcionen de forma nativa, i la depuracio es trivial amb qualsevol eina que parli HTTP.

GraphQL te sentit quan:

• El teu frontend necessita dades de multiples recursos en una sola pantalla i l'over-fetching amb REST es un problema real (no teoric).
• Tens multiples clients (web, mobil, TV) amb necessitats de dades molt diferents.
• El teu graf de dades es complex i les relacions entre entitats son profundes.

GraphQL NO te sentit quan:

• Tens un sol frontend i un backend simple.
• El teu equip no te experiencia amb GraphQL (la corba d'aprenentatge es real).
• Values la simplicitat operacional (caching, monitoritzacio i seguretat son mes complexos amb GraphQL).

Per a la majoria de startups en fase primerenca, REST amb endpoints ben dissenyats es la resposta correcta. Sempre pots afegir GraphQL com una capa a sobre de la teva API REST mes endavant.

Disseny practic d'una API REST solida

Aquests son els principis que separen una API ben dissenyada d'una que genera dolor:

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

Codis d'estat HTTP correctes. 200 per a exit, 201 per a creacio, 400 per a error del client, 401 per a no autenticat, 403 per a no autoritzat, 404 per a no trobat, 422 per a validacio fallida, 500 per a error del servidor. No retornis 200 amb un body que diu {"error": true}.

Paginacio des del dia 1. Tot endpoint que retorni llistes ha d'estar paginat. No importa que avui nomes tinguis 50 registres. Quan en tinguis 50.000, canviar un endpoint de no-paginat a paginat trenca tots els clients que el consumeixen. Cursor-based pagination es mes robusta que offset/limit per a dades que canvien frequentment.

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

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

No inventis un format diferent per a cada endpoint. El frontend necessita poder parsejar errors de forma generica.

Versionat des del principi. /api/v1/users. Quan necessitis fer breaking changes, crees /api/v2/users i mantens v1 durant un periode de transicio. Sense versionat, cada canvi a l'API pot trencar clients existents.

Autenticacio estandard. JWT per a la majoria de casos. OAuth2 si necessites que tercers accedeixin a dades dels teus usuaris. No inventis el teu propi sistema d'autenticacio. Fes servir una llibreria provada i segueix els estandards.

Els errors que mes veig

Despres de revisar desenes d'APIs de startups, aquests son els patrons que mes dolor causen:

• Exposar IDs interns. Si la teva base de dades usa IDs autoincrement, un atacant pot enumerar tots els teus recursos. Fes servir UUIDs o IDs publics separats dels interns.
• No tenir rate limiting. Sense rate limiting, un script mal fet (o malintencionat) pot tombar la teva API. Implementa rate limiting des del principi, encara que sigui generous (1.000 requests per minut es raonable per comencar).
• Naming inconsistent. Un endpoint fa servir user_id, un altre fa servir userId, un altre fa servir UserID. Tria una convencio i mantin-la a tota l'API. Aquest es un problema sorprenentment frequent quan diversos desenvolupadors contribueixen sense una guia d'estil.
• Responses que retornen massa. Un endpoint /users que retorna el hash del password, el token de sessio i dades internes. Dissenya les teves responses pensant en que necessita el client, no en que te la teva base de dades.
• No documentar. Una API sense documentacio es una API que nomes l'autor pot fer servir. OpenAPI/Swagger no es opcional. Es part del producte.

El flux de treball API-first a la practica

Aixi es veu un sprint en un equip API-first:

1. Planificacio: L'equip defineix quina funcionalitat es construira i dissenya els endpoints necessaris. S'escriu el contracte en OpenAPI.
2. Mock: Es lleven endpoints mock que retornen dades d'exemple seguint el contracte. Eines com Prism o Mockoon ho fan en minuts.
3. Desenvolupament paral·lel: El frontend construeix contra els mocks. El backend implementa la logica real. Tots dos treballen al mateix temps sense bloquejar-se mutuament.
4. Integracio: Quan tots dos estan llestos, es connecta el frontend al backend real. Si el contracte s'ha respectat, aixo hauria de funcionar amb canvis minims.
5. Tests de contracte: Tests automatitzats verifiquen que la implementacio real compleix exactament el contracte definit. Si algu canvia l'API sense actualitzar el contracte, els tests fallen.

Aquest flux elimina el major coll d'ampolla en equips de producte: la dependencia seqüencial entre frontend i backend.

Per que aixo importa per a la teva startup

API-first no es una moda. Es una decisio arquitectonica que determina la teva velocitat de desenvolupament a mig termini. Les startups que adopten API-first des del principi poden:

• Llancar una app mobil en setmanes, no mesos.
• Integrar amb partners sense construir res custom.
• Pivotar el seu frontend sense tocar el backend.
• Oferir versions white-label reutilitzant la mateixa API.
• Escalar frontend i backend de forma independent.

A Conectia, els enginyers de backend que connectem amb startups europees pensen API-first per defecte. No perque sigui una buzzword, sino perque han vist que passa quan no ho fas: reescriptures costoses, integracions doloroses i mesos perduts.

Un enginyer senior que dissenya la teva API correctament des del dia u no es un cost, es una inversio que es paga sola la primera vegada que necessites connectar un nou client al teu sistema.

---

Necessites un backend engineer que dissenyi la teva API des del primer dia pensant en escala i integracio? Parla amb un CTO — connectem amb enginyers senior que construeixen APIs que no hauras de reescriure.