La estructura básica de una API en IBM API Connect 10 con el DataPower API Gateway: el contrato OpenAPI con la extensión x-ibm-configuration, la protección con Client ID y Client Secret, el producto con sus planes, y la validación y publicación con el CLI apic. Basada en la documentación oficial de IBM, con la API y el producto completos en el README.md de la izquierda.
¿Qué vas a aprender?
- Las piezas de API Connect 10: API, producto, planes, catálogos y aplicaciones.
- La estructura de una API: el contrato OpenAPI y la extensión
x-ibm-configuration. - Cómo proteger la API con Client ID y Client Secret.
- Cómo definir un producto con planes y límites de llamadas.
- Validar, publicar y probar la API con el CLI
apic.
Requisitos previos
- Acceso a IBM API Connect 10 (API Manager) con una organización proveedora y un catálogo (por ejemplo,
sandbox). - El toolkit de API Connect (CLI
apic) de la misma versión que tu servidor, en Windows con PowerShell. - Un servicio de backend al que redirigir las llamadas.
- Conocer lo básico de OpenAPI (ver la guía del contrato OpenAPI 3 con OAuth y API Key).
Paso a paso
1. Entiende las piezas
| Pieza | Qué es |
|---|---|
| API (YAML) | El contrato OpenAPI más la extensión x-ibm-configuration, que dice al gateway cómo procesar cada llamada. |
| Producto (YAML) | Empaqueta una o varias APIs y define los planes (límites de llamadas) con los que se ofrecen. |
| Catálogo | El entorno donde se publica el producto: sandbox para pruebas, y los que crees (por ejemplo, producción). |
| Aplicación consumidora | La da de alta el desarrollador en el portal, obtiene su Client ID y Client Secret y se suscribe a un plan. |
| Gateway | El DataPower API Gateway (recomendado) o el compatible con v5, que ejecuta la API. |
2. Elige la versión de OpenAPI
- OpenAPI 2.0 (Swagger) funciona en los dos tipos de gateway. Es la que usamos en esta guía.
- OpenAPI 3.0 solo funciona en el DataPower API Gateway y con limitaciones: un único
serversy sin variables en su URL, sincallbacksnilinks(una API que los tenga no se publica), sin OpenID Connect y sin API keys en cookies.
3. Conoce la extensión x-ibm-configuration
Es lo que convierte un contrato OpenAPI en una API ejecutable en el gateway:
x-ibm-configuration:
gateway: datapower-api-gateway # o datapower-gateway (gateway compatible con v5)
type: rest # rest o wsdl
phase: realized # identified, specified o realized
enforced: true # el gateway aplica la API
testable: true # se puede probar desde API Manager
cors:
enabled: true
properties: {} # valores por defecto (por ejemplo, target-url)
catalogs: {} # valores por catálogo (sandbox, produccion…)
assembly:
execute: [] # las políticas, en orden
Las políticas de assembly.execute se ejecutan en orden. Las más habituales: invoke (llamar al backend), set-variable, map, validate, gatewayscript, switch u operation-switch, ratelimit y log.
4. Escribe la API
Una API de pedidos que reenvía las llamadas al backend y exige Client ID y Client Secret. La URL del backend es una propiedad (target-url) con un valor distinto para el catálogo sandbox:
swagger: '2.0'
info:
title: Pedidos
version: 1.0.0
basePath: /pedidos/v1
schemes:
- https
consumes:
- application/json
produces:
- application/json
securityDefinitions:
clientId:
type: apiKey
in: header
name: X-IBM-Client-Id
clientSecret:
type: apiKey
in: header
name: X-IBM-Client-Secret
security:
- clientId: []
clientSecret: []
x-ibm-configuration:
gateway: datapower-api-gateway
type: rest
phase: realized
enforced: true
testable: true
cors:
enabled: true
properties:
target-url:
value: https://backend.empresa.local/pedidos
description: URL del servicio de backend
catalogs:
sandbox:
properties:
target-url: https://backend-pre.empresa.local/pedidos
assembly:
execute:
- invoke:
version: 2.0.0
title: Llamar al backend
target-url: $(target-url)$(api.operation.path)
paths:
/pedidos:
get:
operationId: listarPedidos
summary: Lista los pedidos
responses:
'200':
description: Lista de pedidos
/pedidos/{pedidoId}:
get:
operationId: leerPedido
summary: Consulta un pedido
parameters:
- name: pedidoId
in: path
required: true
type: string
responses:
'200':
description: El pedido
'404':
description: No existe el pedido
Sobre la URL del invoke: IBM indica que no hay que añadir a mano a target-url la ruta ni los parámetros de la operación. El patrón $(target-url)$(api.operation.path) para reenviar la ruta de cada operación es el que se recomienda en la comunidad de IBM ($(request.path) incluye además el basePath); compruébalo en tu versión con la herramienta de pruebas de API Manager.
5. Protege la API con Client ID y Client Secret
Las dos definiciones apiKey del ejemplo identifican a la aplicación consumidora: el gateway comprueba que el Client ID pertenece a una aplicación suscrita a un plan del producto, y el Client Secret, que es la suya.
- Como máximo dos definiciones de API key: una de Client ID y una de Client Secret.
- El Client Secret necesita el Client ID, y los dos deben ir en el mismo sitio (cabecera o query).
- En el DataPower API Gateway, el nombre de la cabecera es libre si indicas el tipo con
x-key-type: client_idoclient_secret; con los nombresX-IBM-Client-IdyX-IBM-Client-Secretfunciona en los dos gateways. - Para OAuth, la API se enlaza con un proveedor OAuth de API Connect y se combina con la definición de Client ID.
6. Define el producto y sus planes
El producto ofrece la API en dos planes: uno básico, sin aprobación, y otro con más llamadas que requiere aprobación. Los nombres de los planes son una palabra (letras, números, - o _) de hasta 20 caracteres:
product: 1.0.0
info:
name: pedidos-producto
title: Producto de pedidos
version: 1.0.0
gateways:
- datapower-api-gateway
visibility:
view:
enabled: true
type: public
tags: []
orgs: []
subscribe:
enabled: true
type: authenticated
tags: []
orgs: []
plans:
basico:
title: Básico
description: 100 llamadas por hora
approval: false
rate-limits:
default:
value: 100/hour
hard-limit: false
premium:
title: Premium
description: 1000 llamadas por hora, con aprobación
approval: true
rate-limits:
default:
value: 1000/hour
hard-limit: true
apis:
pedidos:
$ref: pedidos_1.0.0.yaml
Los límites se escriben como 100/hour o 50/1hour (o unlimited). Con hard-limit: true, las llamadas que lo superan se rechazan.
7. Inicia sesión con el CLI
# Ver los registros de usuarios (realms) del servidor de gestión
apic identity-providers:list --scope provider --server api-manager.empresa.local --fields title,realm
# Iniciar sesión en la organización proveedora
apic login --server api-manager.empresa.local --username desarrollador --realm provider/default-idp-2
Si tu instalación usa inicio de sesión único, el toolkit ofrece apic login --server <servidor> --sso.
8. Crea los archivos con el toolkit (opcional)
En lugar de escribirlos desde cero, el toolkit genera la API y el producto, que luego completas:
apic create:api --title "Pedidos" --version 1.0.0 --gateway-type datapower-api-gateway --target-url https://backend.empresa.local/pedidos
apic create:product
9. Valida la API y el producto
apic validate pedidos_1.0.0.yaml
apic validate pedidos-producto_1.0.0.yaml
--no-extensions valida solo la parte OpenAPI estándar, y --product-only, el producto sin sus APIs.
10. Publica en el catálogo
apic products:publish pedidos-producto_1.0.0.yaml --server api-manager.empresa.local --org empresa --catalog sandbox
apic logout --server api-manager.empresa.local
Para no repetir el catálogo en cada comando: apic config:set catalog=....
11. Prueba la API como consumidor
Da de alta una aplicación en el portal del catálogo, suscríbela a un plan y usa su Client ID y Client Secret. La URL del gateway incluye la organización y el catálogo delante del basePath:
Invoke-RestMethod -Uri "https://gateway.empresa.local/empresa/sandbox/pedidos/v1/pedidos" -Headers @{
"X-IBM-Client-Id" = $env:CLIENT_ID
"X-IBM-Client-Secret" = $env:CLIENT_SECRET
}
Errores habituales
La API con OpenAPI 3.0 no se publica
O el producto usa el gateway compatible con v5 (OpenAPI 3.0 solo funciona en el DataPower API Gateway), o el contrato tiene algo no admitido: más de un servers, variables en su URL, callbacks o links.
401 al llamar a la API
Faltan las cabeceras de Client ID o Client Secret, no son de una aplicación suscrita a un plan de este producto en este catálogo, o la suscripción está pendiente de aprobación.
404 al llamar a la API
La URL no coincide: revisa la organización, el catálogo y el basePath, que el producto esté publicado en ese catálogo y que la ruta y sus parámetros coincidan con los de paths.
El backend recibe una ruta incorrecta
No añadas a mano la ruta o la query a target-url. Revisa qué variable usas para reenviar la ruta (api.operation.path no incluye el basePath; request.path, sí).
«apic validate» da errores en x-ibm-configuration
phase, enforced, testable y cors.enabled son obligatorios, y todas las claves distinguen mayúsculas de minúsculas.
El producto se publica pero la API no aparece en el plan
Una API tiene que estar en la sección apis del producto para que un plan la incluya, con la referencia correcta a su archivo.
El CLI no deja iniciar sesión
Usa un toolkit de la misma versión que el servidor y el realm correcto (provider/... para una organización proveedora); apic identity-providers:list te dice cuáles hay.
Siguientes pasos
- Añadir un proveedor OAuth y exigir token además del Client ID (ver la guía del contrato OpenAPI 3 con OAuth y API Key).
- Validar las peticiones contra el contrato con la política
validatey transformar respuestas conmap. - Automatizar la validación y la publicación con
apicdesde un pipeline (ver la guía de CI/CD con GitHub Actions). - Definir un catálogo de producción con aprobación de suscripciones y límites estrictos.