Desarrollo de APIs en 2026: buenas prácticas de diseño y seguridad

Publicado: 2026-06-15 · Actualizado: 2026-10-28

Por Goiko, Founder & AI Solutions CTO de GUGŌ Creative

Buenas prácticas para desarrollar APIs en 2026: diseño, versionado, OWASP API Top 10, autenticación, límites, idempotencia, OpenAPI y APIs para agentes y MCP.

Una buena API en 2026 se diseña como un contrato estable y se protege como la puerta de entrada a tus datos. En la práctica: describe recursos y operaciones en OpenAPI antes de programar; publica una versión nueva solo cuando rompas la compatibilidad; autoriza cada objeto y cada propiedad, no solo al usuario; limita el uso por cliente; haz idempotentes las operaciones que crean o cobran algo; devuelve los errores en formato estándar (RFC 9457) y deja trazas para seguir cada petición.

Lo nuevo es quién la consume: cada vez más llamadas llegan de agentes de IA que leen la documentación, eligen la operación y reintentan solos, a menudo a través del Model Context Protocol (MCP). Una API bien hecha se expone a un agente con una capa fina; una con autorización floja o sin idempotencia multiplica sus fallos a la velocidad del agente. Para casi todo lo demás, REST con OpenAPI sigue siendo la opción por defecto.

Diseño de APIs: el contrato antes que el código

Las guías de diseño de Google, publicadas como propuestas de mejora de APIs (AIP), parten de los recursos: primero los sustantivos —pedidos, clientes, facturas— y sus relaciones, después su esquema y al final los métodos. Casi todo cabe en cinco métodos estándar —obtener, listar, crear, actualizar y borrar— y los métodos a medida se reservan para lo que no encaja. Y advierten de que una API no tiene por qué ser una copia de la base de datos.

Semántica HTTP correcta. GET no cambia nada; PUT y DELETE son idempotentes; POST no lo es, según la especificación de HTTP (RFC 9110).
Identificadores opacos. OWASP recomienda valores aleatorios, como los UUID, para que nadie recorra registros ajenos cambiando un número, aunque no sustituyen a comprobar permisos.
Paginación desde el primer día. Según AIP-158, añadirla después rompe a los clientes; los tokens de página deben ser opacos y nunca sustituyen a la autorización.
Operaciones largas asíncronas: la API responde enseguida con un recurso de operación que el cliente consulta después.

Escribe el contrato primero y revísalo con quien lo va a consumir: cambiar un campo en un documento cuesta minutos; con clientes en producción, semanas. El encaje con el resto del sistema está en arquitectura de software.

REST, GraphQL, gRPC o MCP: tabla comparativa

Criterio	REST con OpenAPI	GraphQL	gRPC	Servidor MCP
Encaja en	APIs públicas, de socios e integraciones	Apps propias que combinan muchos datos en una pantalla	Comunicación interna entre servicios	Dar herramientas y datos a agentes de IA
Contrato	OpenAPI con JSON Schema	Esquema GraphQL tipado	Protocol Buffers	Herramientas con esquema JSON
Riesgo típico	Autorización por objeto mal resuelta	Consultas profundas o en lote que esquivan límites	Cambios de contrato sin control de compatibilidad	Exceso de permisos e inyección indirecta
Cuándo evitarlo	Pantallas que exigen muchas llamadas encadenadas	API pública sencilla	Clientes de navegador o de terceros	Como sustituto de una API bien diseñada

La combinación sensata suele ser REST con OpenAPI como base, GraphQL si un frontend propio lo necesita y gRPC, con contratos en Protocol Buffers, entre servicios internos. Si eliges GraphQL, la guía de OWASP pide limitar profundidad y cantidad, analizar el coste de las consultas, controlar los lotes y desactivar la introspección en producción. Un servidor MCP no sustituye a nada de esto: es un adaptador para agentes sobre la misma API.

Versionado de APIs sin romper a los clientes

La regla de AIP-180 es que los clientes no deben romperse dentro de una versión mayor. Añadir métodos o campos opcionales es compatible; quitar o renombrar campos, cambiar su tipo o su valor por defecto, o añadir campos obligatorios, no.

Solo versión mayor y en la ruta, como /v1. Según AIP-185, las mejoras compatibles se publican sin cambiar de versión y la anterior convive durante un periodo razonable y bien comunicado; para retirar funciones beta, Google recomienda 180 días.
Retirada anunciada en la respuesta: la cabecera Deprecation (RFC 9745, de marzo de 2025) indica desde cuándo un recurso está obsoleto, y Sunset, cuándo dejará de responder.
Inventario de versiones. OWASP incluye en su lista la gestión deficiente del inventario (API9): versiones antiguas y endpoints de depuración que siguen expuestos sin vigilancia.

Seguridad de APIs: el OWASP API Security Top 10

La lista de OWASP para APIs sigue siendo la edición de 2023, y la mitad de sus riesgos son de autorización o de límites de uso, no de cifrado.

Autorizar cada objeto, propiedad y función (API1, API3 y API5). Estar autenticado no da derecho a ver ese pedido ni a cambiar ese campo. OWASP pide comprobarlo en cada acceso y cubrirlo con tests antes de desplegar.
Limitar el consumo (API4) y proteger los flujos sensibles (API6): tamaño de las peticiones, registros por página, frecuencia por cliente, límites de gasto con servicios de terceros y freno a la automatización abusiva de compras o reservas.
Validar las URL que descarga el servidor (API7) para que nadie lo use como puente hacia la red interna.
Configuración segura (API8): HTTPS, CORS restrictivo y errores sin detalles internos.
Desconfiar de las APIs de terceros (API10) y validar sus respuestas como cualquier entrada.

Autenticación y autorización

La autenticación, el riesgo API2 de esa lista, depende de quién llama. Una clave de API identifica a una aplicación en integraciones sencillas entre servidores, no a una persona. OAuth 2.0 con credenciales de cliente sirve entre máquinas, y el flujo de código de autorización con PKCE, para aplicaciones que actúan en nombre de un usuario. Las buenas prácticas de seguridad de OAuth 2.0 (RFC 9700), de enero de 2025, obligan a usar PKCE en clientes públicos, desaconsejan el flujo implícito, prohíben el de contraseña del propietario y recomiendan restringir cada token a su audiencia y a los permisos mínimos.

A eso se suman tokens de vida corta, credenciales nunca en la URL y claves que se rotan sin redesplegar. Y una regla de fondo: el token dice quién llama, no qué puede ver.

Límites de uso y errores que se entienden

Cuando un cliente supera su cuota, la API responde con el estado 429 Too Many Requests (RFC 6585) y, si puede, la cabecera Retry-After con el tiempo de espera. Los límites se aplican por clave, usuario u organización, no solo por IP. Las cabeceras RateLimit y RateLimit-Policy siguen siendo un borrador del IETF: se pueden usar, avisando de que el formato puede cambiar.

Para los errores, RFC 9457, que sustituye al RFC 7807, define el formato application/problem+json con tipo de problema, título, estado HTTP, detalle e instancia afectada, y pide no exponer trazas internas. Como también los leerá un agente, Anthropic recomienda en su guía de herramientas para agentes mensajes que digan qué corregir: «la fecha de entrega debe ser posterior a hoy» permite rectificar; «400 Bad Request», no.

Idempotencia: reintentar sin duplicar

Una petición es idempotente si repetirla tiene el mismo efecto que hacerla una vez. HTTP define como idempotentes GET, PUT y DELETE; con POST, si se corta la conexión, el cliente no sabe si la primera petición llegó a aplicarse, y en un pedido o un pago reintentar a ciegas es duplicar. La solución es una clave de idempotencia que genera el cliente:

Cabecera Idempotency-Key. El borrador del IETF, en su versión 08 de octubre de 2026 y aún sin rango de RFC, propone claves únicas —se recomiendan UUID—, un 422 si se reutiliza con otro contenido y un 409 si la original sigue en curso.
Una referencia en producción: Stripe guarda la primera respuesta de cada clave, compara los parámetros de los reintentos y puede descartar las claves cuando tienen al menos 24 horas.
Implementación atómica: clave, huella del contenido y resultado se guardan en la misma transacción que la operación; Google usa un campo request_id con el mismo fin (AIP-155).

Observabilidad: poder seguir cada petición

Trazas distribuidas con W3C Trace Context para seguir una petición por todos los servicios que toca, instrumentadas con OpenTelemetry para no atarte a un proveedor.
Métricas por operación y cliente: errores, latencia en percentiles 50, 95 y 99, respuestas 429 y consumo por clave.
Logs estructurados y auditoría de escrituras: quién cambió qué, cuándo y con qué credencial, sin guardar tokens ni datos personales innecesarios.
Una identidad por agente, para distinguir su tráfico del de las personas y poder limitarlo o cortarlo.

Documentación con OpenAPI

La especificación OpenAPI va por la versión 3.2: la 3.2.0 es de septiembre de 2025 y la 3.2.1, una revisión de correcciones, de septiembre de 2026. Su Schema Object es un superconjunto de JSON Schema 2020-12, el dialecto que usan por defecto las herramientas MCP, y la 3.2 permite describir respuestas en streaming y agrupar etiquetas en jerarquías. Un buen documento incluye:

Descripciones pensadas para quien no conoce tu dominio, que es también lo que leerá un agente.
Ejemplos de petición y respuesta que funcionan, y los errores posibles.
Autenticación, alcances, límites y el estado de cada operación: estable, beta u obsoleta.

Trátalo como código: versionado y comprobado en la integración continua para detectar cambios incompatibles antes de publicarlos.

APIs para agentes de IA y servidores MCP

MCP es un protocolo abierto basado en JSON-RPC en el que un servidor ofrece a las aplicaciones de IA recursos, prompts y herramientas. Su especificación vigente, la revisión 2026-07-28, exige consentimiento explícito del usuario antes de invocar una herramienta y obliga a desconfiar de las anotaciones de herramientas que lleguen de servidores no fiables.

Anthropic, en la guía citada, desaconseja envolver cada endpoint en una herramienta: mejor agrupar los pasos que van juntos, devolver datos con significado en lugar de identificadores crípticos, paginar con valores por defecto sensatos y describir cada herramienta como a una persona nueva del equipo.

Con transporte HTTP, la autorización de MCP se basa en OAuth 2.1: el servidor publica sus metadatos de recurso protegido (RFC 9728), el cliente indica para qué servidor pide el token (RFC 8707) y el servidor comprueba que se emitió para él. El servidor no puede aceptar ni reenviar tokens de otros servicios; si llama a otra API, usa una credencial propia con alcances mínimos. La especificación de herramientas obliga además a validar entradas, controlar el acceso, limitar la frecuencia de invocación y sanear las salidas.

Y lo que devuelve tu API —el comentario de un cliente, la descripción de un ticket— puede contener instrucciones que el agente lea como órdenes: es la inyección indirecta que describe OWASP. Separa herramientas de lectura y de escritura, pide confirmación humana en las sensibles y aplica los controles de seguridad en agentes de IA en producción.

Ejemplo hipotético: API de pedidos para socios y un agente interno

El escenario siguiente es hipotético e ilustrativo, no un caso de cliente. Un distribuidor quiere que sus socios creen pedidos desde sus sistemas y que su equipo comercial los prepare con un asistente. Se diseña una API REST con contrato OpenAPI; cada socio usa OAuth con credenciales de cliente y alcances de lectura o escritura, y unos tests comprueban que no puede leer pedidos de otro aunque conozca su identificador. Crear un pedido exige clave de idempotencia, los errores siguen el RFC 9457 y cada socio tiene una cuota con respuesta 429.

Para el asistente se crea un servidor MCP sobre la misma API, con identidad propia y dos herramientas: buscar pedidos y preparar un borrador. El agente nunca confirma un pedido; lo hace una persona desde el CRM, con el patrón de integrar ERP, CRM e IA.

Cuánto cuesta desarrollar una API

Nuestro informe de precios 2026 no publica un rango para una API aislada, porque casi siempre forma parte de una plataforma o de una integración. Las referencias más cercanas son:

Plataforma interna con varios roles, permisos e integraciones: 35.000-70.000 €, en 12-20 semanas.
SaaS empresarial con APIs públicas, seguridad reforzada y escala: 90.000-150.000 € o más, en 24-32 semanas.

Se suman la infraestructura cloud, entre 50 y 500 € al mes según tráfico y datos, y el mantenimiento, del 15 al 25 % del coste de desarrollo al año. Los desgloses están en cuánto cuesta desarrollar software a medida y cuánto cuesta desarrollar un SaaS.

Errores frecuentes

Autenticar sin autorizar cada objeto, el primer riesgo de la lista de OWASP.
Publicar la base de datos tal cual, de modo que cada cambio interno rompe a los clientes.
Añadir la paginación cuando ya hay clientes.
POST sin idempotencia en pedidos, pagos o envíos.
Límites solo por IP y versiones antiguas olvidadas.
Un servidor MCP con permisos de administrador o que reenvía el token del usuario.

Preguntas frecuentes

¿REST o GraphQL en 2026?

REST con OpenAPI es la opción por defecto para APIs públicas, de socios e integraciones: es simple, aprovecha la caché HTTP y lo entiende cualquier cliente. GraphQL compensa cuando aplicaciones propias necesitan combinar muchos datos en una sola consulta, siempre que se limiten la profundidad y el coste de las consultas.

¿Cómo versionar una API sin romper a los clientes?

Publica los cambios compatibles —añadir campos opcionales o métodos— sin cambiar de versión, y crea una versión mayor nueva solo cuando quites, renombres o cambies el tipo de algo. Mantén la anterior durante un periodo de transición y anuncia su retirada con las cabeceras Deprecation y Sunset.

¿Qué medidas de seguridad debe tener una API?

Autorización por objeto, propiedad y función en cada petición, autenticación con tokens de vida corta y alcances mínimos, límites de uso, validación de entradas, HTTPS, configuración segura, inventario de versiones y registro de accesos. El OWASP API Security Top 10 es la referencia para revisarlo.

¿Necesito un servidor MCP si ya tengo una API?

Solo si quieres que la usen agentes o asistentes de IA de forma estándar. El servidor MCP es una capa sobre tu API que expone herramientas pensadas para un modelo, con su propia autorización OAuth y permisos mínimos. Si la API de debajo es débil, el servidor MCP hereda sus fallos. Ver agentes de IA para empresas.