Què és una API? Guia en llenguatge planer per a creadors d'apps

Una API (interfície de programació d'aplicacions) és una manera definida perquè un programari demani dades a un altre, o li faci fer alguna cosa. La teva app envia una sol·licitud en un format acordat —«dona'm les reserves de demà», «cobra 20 euros a aquesta targeta», «resumeix aquest text»— i l'altre sistema envia una resposta estructurada. Les API són la manera en què les peces d'una app es comuniquen entre si, i com la teva app utilitza serveis externs com pagaments, correu, mapes i IA.

Per què les API importen quan construeixes amb IA

Gairebé totes les apps útils estan fetes de peces que es comuniquen mitjançant API:

• Dins de la teva app, les pantalles del navegador criden l'API del teu propi backend per carregar i desar dades.
• Fora de la teva app, el teu backend crida les API d'altres empreses: Stripe per cobrar pagaments, un proveïdor de correu per enviar rebuts, un proveïdor de models d'IA per generar text.

Quan demanes a un generador d'apps amb IA que «accepti pagaments» o «afegeixi un resum amb IA», el que realment fa és escriure codi que crida una API. Conèixer les bases t'ajuda a entendre què necessita la IA de tu (normalment un compte amb aquest servei i una clau d'API), on poden anar malament les coses i quant costaran.

Una analogia de la vida quotidiana

Pensa en un restaurant. No entres a la cuina a cuinar. Llegeixes la carta, dius al cambrer el que vols d'una manera que la cuina entén, i el cambrer et porta el menjar —o et diu que el plat s'ha acabat.

• La carta és la documentació de l'API: una llista del que pots demanar i com.
• El cambrer és l'API: l'única manera acordada perquè les sol·licituds entrin i les respostes surtin.
• La cuina és l'altre sistema: no cal que sàpigues com funciona per dins.
• La teva comanda és la sol·licitud; el plat és la resposta.

La cuina pot canviar els seus forns i el seu personal sense que t'afecti, sempre que la carta es mantingui. Aquest és el valor real d'una API: permet que dos sistemes treballin junts sense que cap dels dos necessiti saber com està construït l'altre.

Com funciona una sol·licitud d'API web

La majoria d'API que trobaràs són API web que funcionen sobre HTTP, el mateix protocol que utilitza el teu navegador. Cada sol·licitud té algunes parts:

I cada resposta té:

JSON (JavaScript Object Notation) és un format de text senzill de noms i valors entre claus. És la manera estàndard en què les API web intercanvien dades.

REST: l'estil més habitual

REST és una convenció àmpliament utilitzada per dissenyar API web. Cada tipus de cosa té la seva pròpia URL, i els mètodes estàndard indiquen què li fas. Així podria ser una API REST per a una app de reserves:

PUT també existeix i convencionalment substitueix un registre sencer, mentre que PATCH només canvia els camps que envies.

Codis d'estat que veuràs més sovint:

Quan la teva app falla, el codi d'estat sovint és la pista més ràpida. Un 401 d'un proveïdor de pagaments normalment vol dir que falta o és incorrecta una clau d'API; un 429 vol dir que crides massa sovint.

REST no és l'únic estil —també existeixen GraphQL i les API d'estil RPC—, però REST és el que utilitzen la majoria de serveis i backends construïts amb IA.

Un exemple pràctic: la confirmació d'una reserva

Quan un client reserva una tall de cabell en una app de perruqueria, poden passar diverses crides d'API en un o dos segons:

1. La pàgina de reserves al navegador envia POST /api/reserves amb el servei, l'hora i les dades del client al teu backend.
2. El teu backend comprova que el torn està lliure, desa la reserva a la base de dades i retorna 201 Created.
3. El teu backend crida l'API d'un proveïdor de correu amb la seva clau secreta: «envia aquesta confirmació a lena@exemple.com».
4. Si hi ha una paga i senyal, el teu backend demana a l'API del proveïdor de pagaments que creï una sessió de pagament i envia el client allà.
5. Més tard, el proveïdor de pagaments crida la teva app per dir que el pagament s'ha completat. Aquesta crida inversa és un webhook.

Els dos primers passos són la teva pròpia API entre frontend i backend. Els passos 3–5 són API de tercers.

Termes habituals explicats

Errors habituals i idees equivocades

• Posar claus secretes al frontend. Qualsevol cosa del codi que s'executa al navegador pot ser vista per qualsevol que visiti el lloc. Les claus secretes han de quedar-se al servidor, en variables d'entorn o secrets.
• Enganxar claus al xat. L'historial del xat pot ser desat. Utilitza la funció de secrets de la teva eina de construcció, i canvia qualsevol clau que hagis exposat.
• Suposar que una API és gratuïta. Moltes API cobren per sol·licitud o per unitat d'ús —les API de models d'IA cobren per tokens. Comprova els preus i estableix límits de despesa. Consulta com utilitzar les API de LLM.
• No gestionar els errors. Els serveis externs cauen, s'esgoten el temps i arriben a límits. Demana missatges d'error raonables i reintents.
• Confiar en el navegador. La teva pròpia API ha de comprovar els permisos per si mateixa. Amagar un botó no impedeix que algú cridi l'endpoint directament.
• Utilitzar claus en viu mentre proves. Utilitza les claus del mode de prova fins que estiguis preparat per llançar.

Què demanar a la teva eina de construcció IA

• «Quines API externes utilitza aquesta app, i quant costa cada una?»
• «Crida l'API de pagaments només des del servidor. Llegeix la clau d'una variable d'entorn.»
• «Llista cada endpoint de la nostra API, què fa i qui pot cridar-lo.»
• «Comprova al servidor que l'usuari connectat és propietari de la reserva abans d'actualitzar-la o eliminar-la.»
• «Si l'API de correu falla, desa la reserva igualment i registra l'error.»
• «De moment, utilitza el mode de prova del proveïdor.»

API a Mythex

Mythex pot construir la teva pròpia API —com a part d'una web app, o com a backend separat en Node, Python (FastAPI), C# o Java que funciona al costat del teu frontend— i escriure el codi que crida serveis externs. Afegeixes les seves claus com a secrets del projecte en lloc de posar-les al xat, i estan disponibles per a la teva app durant la previsualització i un cop publicada. La documentació té receptes per integrar qualsevol API i construir un backend d'API REST.

Preguntes