Principios de Diseño de API

Los buenos principios de diseño de API garantizan que las interfaces sean comprensibles, mantenibles y escalables, tanto para desarrolladores como para clientes automatizados.

Descripción compacta

Los principios de diseño de API son directrices que sigues al planificar e implementar interfaces para construir APIs consistentes, predecibles y duraderas. El centro está en la orientación a recursos, donde modelasprocesos empresariales como usuarios, pedidos o productos como URLs e interactúas con ellos usando métodos HTTP. Una buena API es sin estado, idempotente, versionada y entrega respuestas de error inequívocas. Utiliza paginación para grandes volúmenes de datos, caché para rendimiento y convenciones de nomenclatura claras para legibilidad. La seguridad, documentación y extensibilidad se consideran desde el inicio, no se añaden después.

Actualmente trabajo muchísimo con APIs, por ejemplo para bots de IA, interfaces de chat impulsadas por IA o para descargar y procesar automáticamente documentos como patentes. Te enamorarás de un buen diseño de API y muy pronto odiarás los diseños deficientes.

Quizás te preguntes por qué deberías programar una interfaz API. Déjame responderte brevemente. “¡Para tus propios programas!”

Sí, programo muchas herramientas en Python y a veces las necesito en otra herramienta. ¿Por qué integrar siempre y copiar código cuando puedo acceder a ello simplemente a través de una interfaz? De esta forma solo necesito corregir un bug en un lugar.

Ejemplo: Mi framework FastAPI necesita un limpiador de texto y un script de documentos. Fue mucho más simple crear una API, porque poco después descubrí errores en el limpiador que no tuve que resolver dos veces.

Para diseñar APIs decentes, existen algunos buenos principios y reglas:

Componentes importantes del diseño de API

Orientación a recursos

La orientación a recursos significa que construyes tu API alrededor de objetos empresariales. En lugar de exponer funciones o acciones, defines recursos y utilizas métodos HTTP para leerlos, crearlos, modificarlos o eliminarlos. Un artículo se direcciona por ejemplo a través de /articles/123, no a través de /getArticle?id=123. Esto hace que la API sea intuitiva y fácil de recordar.

Convenciones de nomenclatura consistentes

Utiliza consistentemente letras minúsculas, guiones o guiones bajos y formas plurales. URLs como /order-items, /customers e /invoices/42/payments son fáciles de leer y siguen una jerarquía clara. Evita camelCase, abreviaciones y variaciones ortográficas para conceptos similares.

Ausencia de estado

Cada solicitud a la API debe contener toda la información que el servidor necesita para procesarla. El servidor no almacena estado de sesión entre solicitudes. La información de autenticación se transmite en cada request, por ejemplo en el encabezado Authorization. Esto hace que la API sea escalable y resistente a fallos.

Expresar verbos a través de métodos HTTP

Utiliza GET, POST, PUT, PATCH y DELETE correctamente. GET es para acceso de lectura, POST para crear nuevos recursos, PUT para reemplazos completos, PATCH para actualizaciones parciales y DELETE para eliminación. Evita acciones en URLs como /articles/123/delete.

Idempotencia

Las operaciones idempotentes proporcionan el mismo resultado cuando se invocan repetidamente. GET, PUT y DELETE son idempotentes, POST normalmente no lo es. Para operaciones no idempotentes puedes usar claves de idempotencia para evitar doble carga accidental. Esto es especialmente importante para pagos, pedidos y reservas.

Versionado

Las APIs cambian con el tiempo. Un versionado claro, por ejemplo a través de la ruta /v1/customers o a través de encabezados, permite que los clientes sigan utilizando la API mientras introduces nuevas funcionalidades. Evita cambios incompatibles en versiones existentes.

Gestión clara de errores

Las respuestas de error deben contener códigos de estado HTTP consistentes y mensajes de error significativos. Por ejemplo, utiliza 400 Bad Request para entradas inválidas, 404 Not Found para recursos desconocidos y 409 Conflict para conflictos. Los objetos de error estructurados según RFC 7807 ayudan a los clientes a procesar errores automáticamente.

Paginación

No entregues grandes conjuntos de resultados de una sola vez. Utiliza paginación, ya sea a través de números de página, offset y limit o basada en cursor. La paginación basada en cursor es más adecuada para conjuntos de datos muy grandes y datos en tiempo real, porque no tiene problemas con resultados desplazados.

HATEOAS

HATEOAS significa Hipermedia como motor del estado de la aplicación. La respuesta de una API contiene entonces enlaces a recursos relacionados y acciones posibles. De esta forma, un cliente puede explorar la API en gran medida de forma dinámica sin necesidad de conocer URLs codificadas.

Caché y rendimiento

Utiliza encabezados HTTP como ETag, Last-Modified y Cache-Control para reducir solicitudes repetidas. El caché reduce la carga del servidor y mejora los tiempos de respuesta. Para datos estáticos o que cambian raramente, tiene sentido un caché más largo, para datos en tiempo real preferiblemente uno corto o ninguno.

Seguridad desde el inicio

Utiliza HTTPS, autentica y autoriza accesos, valida entradas e implementa limitación de velocidad. Evita datos sensibles en URLs, registra eventos relevantes para la seguridad y presta atención a las recomendaciones de OWASP para APIs.

Documentación y contratos

Una API es solo tan buena como su documentación. OpenAPI Specification te permite describir la API de forma legible por máquina, incluir ejemplos y apoyar pruebas y generación de código.

Ejemplo práctico

Imagina una tienda en línea que gestiona artículos, clientes y pedidos. La API podría ofrecer los siguientes recursos:

GET    /api/v1/products              Lista de todos los productos con paginación
GET    /api/v1/products/42           Vista de detalle de un producto
POST   /api/v1/orders                Crear nuevo pedido
PUT    /api/v1/orders/123            Reemplazar pedido completamente
PATCH  /api/v1/orders/123/status     Actualizar estado del pedido
DELETE /api/v1/orders/123             Eliminar pedido
GET    /api/v1/orders/123/items      Elementos de un pedido

Una solicitud POST para un nuevo pedido podría verse así:

POST /api/v1/orders
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Idempotency-Key: 9f8e7d6c-5b4a-3210-9f8e-7d6c5b4a3210

{
  "customerId": 123,
  "items": [
    { "productId": 42, "quantity": 2 },
    { "productId": 7, "quantity": 1 }
  ],
  "shippingAddress": {
    "street": "Musterstraße 12",
    "city": "Berlin",
    "zip": "10115"
  }
}

La respuesta en caso de creación exitosa:

HTTP/1.1 201 Created
Location: /api/v1/orders/98765
Content-Type: application/json

{
  "orderId": 98765,
  "status": "created",
  "total": 79.97,
  "links": {
    "self": "/api/v1/orders/98765",
    "items": "/api/v1/orders/98765/items",
    "cancel": "/api/v1/orders/98765/cancel"
  }
}

FAQ: Principios de Diseño de API

1. ¿Qué significa diseño de API orientado a recursos?

El diseño orientado a recursos consiste en construir tu interfaz alrededor de objetos de negocio concretos. Cada recurso tiene una URL única, y los métodos HTTP definen las acciones sobre ese recurso.

2. ¿Por qué una API debe ser sin estado?

Una API sin estado no almacena información de sesión en el servidor. Cada solicitud contiene todos los datos necesarios. Esto simplifica el escalado, la distribución de carga y la depuración, porque cada petición es independiente.

3. ¿Qué es idempotencia y por qué es importante?

Idempotencia significa que varias solicitudes idénticas producen el mismo resultado. Es crucial para manejar de forma segura los problemas de red y los reintentos, por ejemplo en pagos u órdenes.

4. ¿Qué métodos HTTP se deben usar en una API REST?

GET lee datos, POST crea recursos, PUT reemplaza recursos completamente, PATCH actualiza recursos parcialmente y DELETE elimina recursos. Esta semántica debe mantenerse consistentemente.

5. ¿Cómo se versionan correctamente las APIs?

La forma más común es incluir la versión en la ruta, como /v1/customers. Alternativamente, puedes controlar las versiones mediante encabezados o Content Negotiation. Lo importante es que los cambios incompatibles se introduzcan en nuevas versiones.

6. ¿Qué es HATEOAS?

HATEOAS es un principio donde las respuestas de la API incluyen enlaces a recursos relacionados y acciones. El cliente puede explorar la API dinámicamente sin necesidad de codificar URLs.

7. ¿Por qué es importante la paginación?

La paginación evita transferir grandes volúmenes de resultados de una sola vez. Reduce el tiempo de carga, la carga del servidor y el consumo de memoria en el cliente. Sin paginación, listas con miles de registros pueden hacer que la API sea inutilizable.

8. ¿Qué son Problem Details?

Problem Details son formatos de error estandarizados según RFC 7807. Contienen campos como type, title, status, detail e instance. Los clientes pueden evaluar los errores de forma uniforme y mostrar mensajes útiles a los usuarios.

9. ¿Cuál es la diferencia entre PUT y PATCH?

PUT reemplaza completamente un recurso con la representación enviada. PATCH realiza solo un cambio parcial. Si solo deseas cambiar el estado de una orden, usas PATCH, no PUT.

10. ¿Cómo deben estructurarse las URLs en una API REST?

Las URLs deben ser jerárquicas, legibles y consistentes. Usa formas plurales, guiones y letras minúsculas. Los ejemplos incluyen /orders, /orders/123/items o /customers/42/addresses.

11. ¿Qué es una Idempotency Key?

Una Idempotency Key es un valor único que el cliente proporciona en solicitudes no idempotentes. El servidor utiliza esta clave para detectar ejecuciones duplicadas y procesarlas solo una vez.

12. ¿Por qué HTTPS es obligatorio para las APIs?

HTTPS cifra la transmisión de datos y protege contra la interceptación y manipulación. Las APIs modernas transmiten tokens de autenticación y datos sensibles. Sin HTTPS, la API no puede operarse de forma segura.

13. ¿Qué es Content Negotiation?

Content Negotiation permite que cliente y servidor negocien el formato de datos y el idioma de la respuesta. A través del encabezado Accept, el cliente indica qué formatos entiende, como application/json o application/xml.

14. ¿Qué es API Rate Limiting?

Rate Limiting limita el número de solicitudes que un cliente puede hacer en un período determinado. Protege contra sobrecargas, abuso y ataques DDoS. Los clientes reciben información sobre sus límites a través de encabezados como X-RateLimit-Remaining.

15. ¿Por qué es importante la documentación de API?

La buena documentación permite que los desarrolladores comprendan rápidamente la API y la utilicen correctamente. Reduce las solicitudes de soporte, previene errores y facilita la integración. OpenAPI es un formato común para documentación legible por máquinas.

Continuando con la ruta de aprendizaje de APIs

El siguiente artículo en la ruta de aprendizaje de APIs aborda principios de diseño API-First — por qué la especificación de la API debe preceder a la implementación y cómo funciona el desarrollo impulsado por API.

Fuentes

Lecturas recomendadas sobre desarrollo de APIs

Si quieres profundizar en diseño de APIs, REST y arquitectura de software, te recomendamos los siguientes libros:

Keine Bücher für Kategorie "api-development" gefunden.

Täglicher Artikel