Todas las guías
  1. Inicio
  2. Guías técnicas
  3. APIs

APIsNivel intermedio

Estructura básica de una API en IBM API Connect 10

7 min de lectura

Todas las guías

Estructura básica de una API en IBM API Connect 10

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

PiezaQué 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álogoEl entorno donde se publica el producto: sandbox para pruebas, y los que crees (por ejemplo, producción).
Aplicación consumidoraLa da de alta el desarrollador en el portal, obtiene su Client ID y Client Secret y se suscribe a un plan.
GatewayEl 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 servers y sin variables en su URL, sin callbacks ni links (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_id o client_secret; con los nombres X-IBM-Client-Id y X-IBM-Client-Secret funciona 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.

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 validate y transformar respuestas con map.
  • Automatizar la validación y la publicación con apic desde 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.

Compartir

Más guías sobre

Ver todas las guías

Otras guías técnicas

Ver todas las guías

IntegraciónIntermedio

Comandos básicos de administración de TIBCO ActiveSpaces 5.2

Los comandos del día a día en TIBCO ActiveSpaces 5.2: servicio de realm sobre servidores FTL, tibdg, definición del grid, tablas, arranque de procesos, estado, escalado con copysets, checkpoints y logs.

Leer la guía 8 min de lectura

DevOpsBásico

Estructura básica de un CI/CD con GitHub Actions

Un pipeline completo con GitHub Actions: pruebas en cada push y pull request, imagen Docker en GitHub Container Registry y despliegue a un entorno protegido, con un workflow listo para copiar.

Leer la guía 6 min de lectura

DesarrolloBásico

Buenas prácticas de desarrollo en Java con Spring Boot

Las prácticas que más se notan en un servicio Spring Boot: estructura, inyección por constructor, DTOs, validación, errores, configuración, transacciones, logs, comentarios, pruebas y calidad automatizada.

Leer la guía 8 min de lectura

Contacto

Construye hoy tu próxima ventaja competitiva

Hablemos sobre cómo podemos ayudarte. Te respondemos con una propuesta técnica clara, sin compromiso.

Solicita información

Los campos marcados con son obligatorios.