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

Guía de Bitflow Solutions. Versión web: https://bitflow-solutions.com/guias-tecnicas/estructura-api-ibm-api-connect-10/

## ¿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

### OpenAPI 2.0 o 3.0

- 2.0: ambos gateways
- 3.0: solo DataPower API Gateway; un único servers sin variables; sin callbacks, links ni OpenID Connect; API keys no en cookies

### x-ibm-configuration

```yaml
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
```

### API completa (pedidos_1.0.0.yaml)

```yaml
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
```

Nota: target-url con $(target-url)$(api.operation.path) es el patrón recomendado en la comunidad de IBM; compruébalo en tu versión.

### Producto (pedidos-producto_1.0.0.yaml)

```yaml
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
```

### Iniciar sesión

```powershell
# 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
```

### Crear con el toolkit

```powershell
apic create:api --title "Pedidos" --version 1.0.0 --gateway-type datapower-api-gateway --target-url https://backend.empresa.local/pedidos
apic create:product
```

### Validar

```powershell
apic validate pedidos_1.0.0.yaml
apic validate pedidos-producto_1.0.0.yaml
```

### Publicar

```powershell
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
```

### Probar

```powershell
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.

Fuente: documentación de IBM API Connect v10 (ibm.com/docs) y referencia del CLI (ibm-apiconnect.github.io/clidocs).
