API

Resumen

API significa Application Programming Interface: una interfaz de programación de aplicaciones. Es un contrato que define cómo un componente de software puede ser usado por otro. Especifica qué operaciones están disponibles, qué entradas aceptan, qué salidas producen, cómo se reportan los errores y qué garantías de estabilidad ofrece.

Importa porque casi todo el software moderno se construye componiendo APIs. Tu frontend consume la API del backend. Tu backend consume APIs de bases de datos, servicios de pago, proveedores de email y plataformas cloud. Tu código llama APIs de librerías y del sistema operativo. Entender qué hace que una API sea buena —clara, estable, bien documentada, con alcance definido— es una habilidad fundamental que atraviesa stacks, lenguajes y paradigmas.

Alcance y supuestos

Este paquete cubre APIs como concepto general: contratos entre componentes, operaciones, entradas, salidas, errores, versionado, documentación y principios de diseño comunes a web APIs, library APIs y system APIs.

No cubre metodologías completas de diseño de APIs, lenguajes de especificación, implementación de frameworks específicos ni detalles de protocolos. Asume que entiendes programación básica, llamadas a funciones, estructuras de datos y comunicación cliente-servidor.

Modelo mental

Piensa en el tablero de control de un auto. El conductor no necesita saber cómo funciona el motor de combustión interna, la transmisión ni el sistema de inyección. Solo necesita conocer la interfaz: el volante gira las ruedas, el acelerador aumenta la velocidad, el freno la reduce, el tablero muestra información relevante.

Una API es ese tablero de control aplicado al software. El componente que expone la API dice: "estas son las operaciones que puedes hacer, estos son los datos que necesito, esto es lo que te devuelvo, y estas son las reglas". El componente que consume la API no necesita saber nada sobre la implementación interna. Si el motor cambia de gasolina a eléctrico, mientras el tablero funcione igual, el conductor no necesita reaprender a manejar.

Este principio aplica a todas las escalas. Una función con una firma clara es una API. Una clase con métodos públicos es una API. Un servicio web con endpoints REST es una API. Una librería con su documentación es una API. El patrón es el mismo: contrato explícito, implementación oculta.

Uso práctico

Diseña APIs cuando necesitas que componentes de software interactúen sin acoplarse a implementaciones concretas:

• ✅ Exponer servicios backend para consumo interno, mobile apps o third parties.
• ✅ Definir contratos entre equipos: el equipo A expone una API que el equipo B consume.
• ✅ Encapsular lógica compleja detrás de operaciones simples y bien documentadas.
• ✅ Versionar cambios para no romper consumidores existentes.
• ❌ No expongas tu modelo interno directamente; la API debe ser un contrato diseñado, no un reflejo de tu base de datos.
• ❌ No cambies la semántica de una operación sin cambiar su versión o su nombre.

Ejemplo trabajado: diseñar la API de un servicio de pagos

Supón que necesitas un servicio de pagos. Otros equipos y servicios lo consumirán. La API no es el código interno; es el contrato público:

// Contrato de la API: operaciones, entradas y salidas
interface PaymentServiceAPI {
  createPayment(request: CreatePaymentRequest): Promise<CreatePaymentResponse>;
  getPayment(paymentId: string): Promise<Payment>;
  refundPayment(paymentId: string, reason: string): Promise<Refund>;
  listPayments(filter: PaymentFilter): Promise<PaginatedResult<Payment>>;
}

// Cada operación tiene tipos explícitos
type CreatePaymentRequest = {
  amountCents: number;
  currency: "CLP" | "USD";
  customerId: string;
  description: string;
  idempotencyKey: string; // evita cobros duplicados
};

type CreatePaymentResponse = {
  paymentId: string;
  status: "processing" | "completed" | "failed";
  createdAt: string;
};

// Los errores son parte del contrato, no excepciones genéricas
type APIError = {
  code:
    | "invalid_amount"
    | "currency_not_supported"
    | "customer_not_found"
    | "duplicate_request"
    | "insufficient_funds"
    | "service_unavailable";
  message: string;
  details?: Record<string, unknown>;
};

Lo que hace buena a esta API:

1. Operaciones con propósito claro: createPayment, getPayment, refundPayment, listPayments. Una operación, una responsabilidad.
2. Tipos explícitos de entrada y salida: quien consume sabe exactamente qué enviar y qué esperar.
3. Errores tipados y documentados: invalid_amount vs insufficient_funds no son lo mismo, y quien consume puede manejar cada caso.
4. Clave de idempotencia: idempotencyKey evita cobros duplicados en reintentos.
5. Paginación para listas: PaginatedResult<T> evita respuestas gigantes que matan al cliente.

Antes de publicar una API, cinco preguntas:

1. ¿Qué operaciones necesita el consumidor? No expongas lo que crees que es útil; expón lo que los consumidores realmente necesitan.
2. ¿Qué errores pueden ocurrir y cómo los comunicas? Un error genérico 500 no es una API; es una confesión de que no diseñaste los fallos.
3. ¿Cómo versionarás los cambios? ¿Nueva ruta, header, query param?
4. ¿Cómo autenticas, autorizas y limitas el consumo?
5. ¿Dónde está la documentación y cómo sabe el consumidor si algo cambió?

Evidencia

• MDN Web Docs, Introduction to web APIs presenta APIs desde un nivel alto: qué son, cómo funcionan, cómo usarlas en código y cómo se estructuran.