Guía de APIs para Product Managers

Una API define cómo puede utilizar un software los datos o las capacidades de otro sistema. Para un Product Manager que evalúa una integración, el trabajo consiste en relacionar el recorrido previsto del cliente con las operaciones, los permisos y el comportamiento que realmente ofrece la API. La lista de funcionalidades de un proveedor rara vez basta para saber si la integración permitirá construir la experiencia planteada.

Esta guía introduce los conceptos de las APIs HTTP necesarios para seguir esa investigación: peticiones y respuestas, métodos, controles de acceso y el trabajo que exige una integración después del lanzamiento. Utiliza un historial de pedidos hipotético de Mercato, una plataforma de comercio electrónico. Para empezar con una vista visual, puede consultarse la infografía de APIs. Si la propia API es el producto que se ofrece a desarrolladores, el artículo de gestión de APIs como producto aborda la adopción, la priorización y su evolución.

Leer una petición a partir de un requisito del cliente

Mercato quiere mostrar a los clientes sus últimos pedidos, con el estado del pago y el importe. El frontend llama a una operación del backend que puede devolver los pedidos de la cuenta autenticada. En una API HTTP, el endpoint es la dirección donde se expone una operación; el método indica cómo pretende actuar la petición sobre ese recurso. Los parámetros de consulta permiten concretar lo que se pide, por ejemplo limitando el número de resultados.

La siguiente petición y su respuesta JSON son ilustrativas; no corresponden a un endpoint real. JSON organiza los datos en campos con nombre y valores. Aquí, la respuesta contiene un pedido y un cursor para continuar recorriendo los resultados:

GET /orders?limit=20

{
  "orders": [
    {"id": "ord_8421", "status": "paid", "total": 49.90, "currency": "EUR"}
  ],
  "next_cursor": "page_2"
}

Para convertir esa respuesta en un requisito, el equipo necesita saber qué significa «paid», si el importe incluye el envío y cómo se representan la moneda y las unidades. En este ejemplo, el importe se expresa en euros; otro proveedor podría utilizar unidades menores u otra representación. La interfaz debe apoyarse en el contrato documentado, sin deducir esos significados de un valor de muestra.

El cursor de la página siguiente también cambia el trabajo. Si solo se recupera la primera respuesta, los pedidos antiguos podrían parecer inexistentes. La API REST de GitHub ofrece un ejemplo real de paginación que utiliza enlaces de respuesta para encontrar más páginas. Cada proveedor elige su mecanismo, por lo que hay que comprobar la documentación concreta y qué ocurre si los datos cambian entre peticiones.

Reconocer qué pretende hacer una operación

El método y el endpoint deben leerse juntos. Una API puede ofrecer la consulta de pedidos y la creación de reembolsos como operaciones distintas, con permisos diferentes. El mismo método HTTP puede utilizarse en muchos recursos, y el proveedor define qué operaciones están disponibles.

Métodos habituales en APIs HTTP
Método	Significado que hay que comprobar en el contrato
GET	Recuperar una representación, como el estado actual de un pedido.
POST	Enviar datos para su procesamiento; crear un pago es uno de sus posibles usos.
PUT	Crear o sustituir el estado del recurso en la dirección indicada.
PATCH	Aplicar una modificación parcial a un recurso.
DELETE	Solicitar la eliminación del recurso. Hay que comprobar las reglas del proveedor sobre conservación y borrado definitivo.

Una respuesta combina un código de estado con cabeceras y, cuando corresponde, un cuerpo. Las cabeceras contienen metadatos como el tipo de contenido, enlaces de paginación o credenciales de acceso en una petición. El cuerpo puede incluir los registros solicitados, el estado de una operación o información estructurada sobre un error. Una respuesta HTTP correcta confirma el resultado descrito por ese endpoint; no significa necesariamente que haya terminado todo el proceso de negocio.

En Mercato, una petición podría aceptarse mientras el pago sigue pendiente. El historial de pedidos debe representar ese estado con precisión. Si la API no ofrece un campo que necesita el diseño, habrá que cambiar el requisito, encontrar otra fuente o ampliar la API antes de prometer esa información al cliente.

Establecer de quién son los datos que puede utilizar la integración

La autenticación comprueba la identidad o las credenciales que presenta quien llama; la autorización determina las acciones y los recursos permitidos. Poder llamar a una API no implica poder leer los pedidos de cualquier cliente. El backend de Mercato debe aplicar las reglas de cada cuenta, también si alguien cambia el identificador de un pedido en la petición.

Las claves privadas y los tokens de acceso de OAuth aparecen con frecuencia en la documentación de integraciones, pero sus capacidades dependen del proveedor. OAuth es un marco de autorización que puede ofrecer acceso delegado o en nombre de la propia aplicación. La comparación de claves de API y OAuth desarrolla sus consecuencias para los permisos, la renovación de credenciales y la desconexión. La explicación de autenticación frente a autorización distingue la identidad de las acciones permitidas.

Traducir los fallos a la experiencia del cliente

La gestión de fallos empieza por interpretar la respuesta. Un código 401 señala que faltan credenciales de autenticación o no son válidas; un 403 indica que el servidor rechaza la petición. Un 429 señala un exceso de peticiones según las reglas del servicio, mientras que un 500 informa de una condición inesperada en el servidor. El cuerpo del error y la documentación aportan el contexto para decidir qué debe hacer la aplicación.

En el historial de pedidos de Mercato, no poder recuperar los datos no debe presentarse como prueba de que el cliente nunca ha comprado. El equipo puede distinguir un fallo de carga de un resultado vacío y decidir si cabe mostrar información recuperada anteriormente, indicando su vigencia. La decisión depende de los datos y sus consecuencias; una estimación de entrega antigua y un estado de pago incierto necesitan tratamientos distintos.

Un timeout introduce otro caso: el sistema que llama ha dejado de esperar sin saber necesariamente si el receptor actuó. Reintentar automáticamente una petición que crea un pago necesita salvaguardas distintas de las de una consulta de lectura. El artículo sobre webhooks y polling sigue un pago incierto a través de sus actualizaciones, duplicados y recuperación.

Planificar más allá de la primera respuesta correcta

Una integración sigue consumiendo capacidad después del lanzamiento. La paginación, las comprobaciones repetidas y el trabajo de recuperación pueden multiplicar las peticiones. La guía de límites de peticiones explica cómo afectan las restricciones del proveedor a ese tráfico. Las estimaciones de coste deben utilizar el patrón de consultas esperado y el modelo de facturación, sin asumir una llamada por cada acción del cliente.

Las actualizaciones pueden llegar mediante consultas programadas o notificaciones de eventos. Un webhook puede avisar a Mercato de un cambio en el pedido y una consulta a la API recuperar los detalles. La combinación adecuada depende del retraso aceptable y de los requisitos de recuperación. Son partes de una integración que pueden complementarse.

Los contratos de las APIs también evolucionan. Un proveedor puede cambiar una operación, añadir campos o retirar una versión. El identificador de versión puede aparecer en una cabecera o en la URL, pero por sí solo no explica la compatibilidad ni el periodo de soporte. Conviene asignar quién revisa los avisos, evalúa su efecto y reserva capacidad para las migraciones necesarias. La documentación de versiones de GitHub muestra cómo comunica estas políticas un proveedor.

Convertir la revisión de la API en una definición de integración

Una definición útil recoge el comportamiento del cliente y las evidencias que lo respaldan. Ingeniería puede investigar las operaciones y sus limitaciones, mientras Producto ajusta el alcance antes de que esas limitaciones se conviertan en un problema de lanzamiento. Para el historial de pedidos de Mercato, la revisión cubriría:

Los pedidos de qué cuenta se devuelven y cómo se restringe el acceso a esa cuenta.
Si los campos disponibles cubren la pantalla prevista, incluidos el estado del pago, los importes y la información de entrega.
Cómo se recuperan las siguientes páginas y qué vigencia necesita la información mostrada.
Qué ve el cliente durante un error, un retraso o un resultado incierto.
Qué límites y cargos se aplican al funcionamiento habitual y a la recuperación.
Quién supervisa la integración, atiende las incidencias y sigue los cambios del proveedor.

La documentación puede describir el contrato, y un entorno de pruebas o una prueba controlada ayudan a comprobar un supuesto. Ninguno sustituye la revisión de las condiciones de producción y los casos relevantes. Si el equipo publica su propia API HTTP, una descripción OpenAPI permite registrar operaciones y esquemas de forma estructurada; no demuestra que el servicio en ejecución cumpla todos los requisitos.

Para situar los componentes, puede seguirse el diagrama de arquitectura de un checkout. Si la decisión inmediata es ofrecer una API como producto e invertir en ella, el siguiente paso es gestión de APIs como producto. El libro APIs para Product Managers desarrolla los conceptos técnicos y las decisiones de integración introducidos aquí.