Com preparar productes i APIs per al desplegament a l'API Manager. Arquitectura CTTI. Generalitat de Catalunya

Introducció

El Servei d’Integració Contínua és un servei a disposició dels proveïdors d’aplicacions per a automatitzar el desplegament de les aplicacions.

L’API Manager Corporatiu és una plataforma en modalitat SaaS basada en la solució IBM API Connect 10 Reserved Instance. Aquest servei permet gestionar el cicle de vida de les APIs de manera senzilla i segura amb l’objectiu de facilitar-ne tant la seva publicació com el seu consum.

Organització de catàlegs, espais i productes

L’organització de catàlegs, espais i productes és la següent:

Hi ha quatre catàlegs segons el tipus d’entorn i el tipus de visibilitat: privat_pre, public_pre, privat i public.
Cada codi de diàleg disposarà d’un espai propi amb la nomenclatura “CD” + <codi_diàleg> (agrupació de productes). Per exemple: “CD0192”.
Un producte és una agrupació d’APIs i plans que les acompanyen (unitat mínima a versionar, desplegar i subscriure).

Govern

IBM API Connect disposa d’un servei de govern de la publicació de APIs que permet aplicar determinades regles per a validar aspectes de govern de l’organització. Els detalls de la funcionalitat es poden consultar en la documentació oficial d’IBM en el següent enllaç: Validating an API or product document by using the governance service

En la publicació de noves versions de APIs o productes s’inclou un nou pas en el qual es realitza aquesta validació afectant la continuïtat del desplegament en funció del resultat: si hi ha errors en la validació contra les regles de govern de API Manager definides per l’oficina tècnica, el desplegament no continuarà.

Per a ampliar més informació sobre el model de govern, consultar la documentaición de APIM en el següent enllaç: Servei d’API Manager Corporatiu.

En el log de la fase en la pipeline es bolcarà el detall de les validacions realitzades i els advertiments o errors trobats.

2026-06-12 12:01:44.925  Product file: /home/jenkins/agent/workspace/3292-APM/3292-APM-apim-test-pipeline/3292-APM-apim-test-pipeline/9/product.yml
2026-06-12 12:01:44.925  Referenced API files (1):
2026-06-12 12:01:44.925    - /home/jenkins/agent/workspace/3292-APM/3292-APM-apim-test-pipeline/3292-APM-apim-test-pipeline/9/api.yml
2026-06-12 12:01:44.925  >>> apic --mode governance compliance:validate --org ctti --server api.db40-c57f0fcb.eu-de.apiconnect.cloud.ibm.com --rulesets sic-corporate-product --output /tmp /home/jenkins/agent/workspace/3292-APM/3292-APM-apim-test-pipeline/3292-APM-apim-test-pipeline/9/product.yml
2026-06-12 12:01:47.486  ================================================================================
2026-06-12 12:01:47.486  File   : /home/jenkins/agent/workspace/3292-APM/3292-APM-apim-test-pipeline/3292-APM-apim-test-pipeline/9/product.yml
2026-06-12 12:01:47.486  Ruleset: sic-corporate-product
2026-06-12 12:01:47.486  Report : /tmp/ComplianceResult.yaml
2026-06-12 12:01:47.486  total_results: 1
2026-06-12 12:01:47.486  created_at  : 2026-06-12 10:01:47.154Z
2026-06-12 12:01:47.486  summary: warn=1
2026-06-12 12:01:47.486  --------------------------------------------------------------------------------
2026-06-12 12:01:47.486    [WARN ] sic-corporate-product:1.0.0 / prd-pla-02-name-tier-period-pattern
2026-06-12 12:01:47.486      path : plans/prueba_rendimiento
2026-06-12 12:01:47.486      lines: 55-65
2026-06-12 12:01:47.486      api  : product.yml (3292 Technical Product:5.0.6)
2026-06-12 12:01:47.486      msg  : El nombre del plan ubicado en #/plans/prueba_rendimiento no sigue el patrón {tier} o  {tier}-{funcional} con tier en [default-plan, bronze, silver, gold]. Ejemplos válidos: "default-plan", "bronze-auth", "silver", "gold-users".
2026-06-12 12:01:47.486  
2026-06-12 12:01:47.486  >>> apic --mode governance compliance:validate --org ctti --server api.db40-c57f0fcb.eu-de.apiconnect.cloud.ibm.com --rulesets sic-corporate-api --output /tmp /home/jenkins/agent/workspace/3292-APM/3292-APM-apim-test-pipeline/3292-APM-apim-test-pipeline/9/api.yml
2026-06-12 12:01:50.015  ================================================================================
2026-06-12 12:01:50.015  File   : /home/jenkins/agent/workspace/3292-APM/3292-APM-apim-test-pipeline/3292-APM-apim-test-pipeline/9/api.yml
2026-06-12 12:01:50.015  Ruleset: sic-corporate-api
2026-06-12 12:01:50.015  Report : /tmp/ComplianceResult_1.yaml
2026-06-12 12:01:50.015  total_results: 7
2026-06-12 12:01:50.015  created_at  : 2026-06-12 10:01:49.908Z
2026-06-12 12:01:50.015  summary: error=1, warn=6
2026-06-12 12:01:50.015  --------------------------------------------------------------------------------

Addicionalment es compondrà un fitxer json amb el resum que s’adjuntarà com a artefacte al log d’execució de la pipeline per a poder ser utilitzat posteriorment.

{
    "summary":     {
        "by_severity":         {
            "warn": 7,
            "error": 1
        },
        "total": 8,
        "files_with_findings": 2,
        "files_validated": 2
    },
    "files":     [
                {
            "report_file": "/tmp/ComplianceResult.yaml",
            "file": "/home/jenkins/agent/workspace/3292-APM/3292-APM-apim-test-pipeline/3292-APM-apim-test-pipeline/9/product.yml",
            "counts": {"warn": 1},
            "returncode": 0,
            "findings": [            {
                "severity": "warn",
                "path": "plans/prueba_rendimiento",
                "rule_name": "prd-pla-02-name-tier-period-pattern",
                "api_name": "product.yml",
                "doc_title": "3292 Technical Product:5.0.6",
                "start_line": 55,
                "message": "El nombre del plan ubicado en #/plans/prueba_rendimiento no sigue el patrón {tier} o  {tier}-{funcional} con tier en [default-plan, bronze, silver, gold]. Ejemplos válidos: \"default-plan\", \"bronze-auth\", \"silver\", \"gold-users\".",
                "ruleset_name": "sic-corporate-product:1.0.0",
                "end_line": 65,
                "product_title": "3292 Technical Product:5.0.6"
            }],
            "ruleset": "sic-corporate-product",
            "created_at": "2026-06-12 10:01:47.154Z",
            "total_results": 1
        },
                {
            "report_file": "/tmp/ComplianceResult_1.yaml",
            "file": "/home/jenkins/agent/workspace/3292-APM/3292-APM-apim-test-pipeline/3292-APM-apim-test-pipeline/9/api.yml",
            "counts":             {
                "warn": 1,
                "error": 1
            },
            "returncode": 0,
            "findings":             [
                                {
                    "severity": "warn",
                    "path": "info/description",
                    "rule_name": "api-doc-01-description-min-length",
                    "api_name": "api.yml",
                    "doc_title": "3292 API Piloto V3:5.0.0",
                    "start_line": 3,
                    "message": "\"info.description\" tiene menos de 50 caracteres. Amplíala para aportar contexto al consumidor de la API.",
                    "ruleset_name": "sic-corporate-api:1.0.0",
                    "end_line": 4
                },
                                {
                    "severity": "error",
                    "path": "info/x-ibm-name",
                    "rule_name": "api-nam-02-xibmname-starts-with-codi",
                    "api_name": "api.yml",
                    "doc_title": "3292 API Piloto V3:5.0.0",
                    "start_line": 9,
                    "message": "\"info.x-ibm-name\" debe empezar por el código de diálogo del proyecto (p.ej. \"3292-customer-profile\"). Valor actual: \"api-piloto-v3\".",
                    "ruleset_name": "sic-corporate-api:1.0.0",
                    "end_line": 9
                }
            ],
            "ruleset": "sic-corporate-api",
            "created_at": "2026-06-12 10:01:49.908Z",
            "total_results": 2
        }
    ],
    "detail": "",
    "product_file": "/home/jenkins/agent/workspace/3292-APM/3292-APM-apim-test-pipeline/3292-APM-apim-test-pipeline/9/product.yml"
}

Validacions addicionals

A més de la validació contra les regles de govern abans descrita, s’aplicaran uns mecanismes de validació addicionals (snippets) que poden implicar canvis respecte a la definició inicial de productes i APIs realitzada pel proveïdor:

La visibilitat del producte serà sempre de tipus authenticated:

visibility:
  view:
    type: authenticated
    orgs: []
    tags: []
    enabled: true
  subscribe:
    type: authenticated
    orgs: []
    tags: []
    enabled: true

No es permetrà configurar especificitats singulars per a les APIs dins un pla. En aquest sentit, en cas que la variable APIC_PRESERVE_ASSEMBLY tingui el valor de false, la secció x-ibm-configuration.assembly.execute serà reemplaçada aplicant la configuració de target-url especificada al fitxer aca.yml de forma que sigui possible dur a terme un desplegament multientorn, tenint en compte la regla de nomenclatura aplicada al basePath.

execute:
  - gatewayscript:
      title: gatewayscript
      version: 2.0.0
      description: Set new request path
      source: |
        const requestPath = context.get('request.path');
        const newRequestPath = requestPath.replace(/^\/\d*\.*\d*/, "");
        context.set('new.request.path', newRequestPath);
  - invoke:
      title: invoke
      version: 2.0.0
      verb: keep
      target-url: '<replace_target_url>$(new.request.path)'
      follow-redirects: false
      timeout: 60
      parameter-control:
        type: blocklist
      header-control:
        type: blocklist
        values:
          - ^X-IBM-Client-Id$
      inject-proxy-headers: true

Nomenclatura

El SIC aplica una sèrie d’estàndards de nomenclatura amb l’objectiu de facilitar la identificació a simple vista de productes i APIs publicades per part dels subscriptors i, a més, mitigar el possible risc de solapament de recursos. Les regles de nomenclatura aplicades són les següents:

Productes:
- name obligatori i immutable que es correspon amb el codi de diàleg, el caràcter separador “-” i un text descriptiu que serveixi per identificar la funcionalitat del producte com, per exemple, el nom del projecte. Per exemple: “0192-apim_demo_project”.
- title obligatori amb prefix de codi de diàleg, un espai en blanc i un text lliure. Per exemple: “0192 APIM Demo Project”.
APIs:
- x-ibm-name obligatori amb prefix de codi de diàleg, el caràcter separador ‘-’ i l’identificador de l’API. Per exemple: “0192-api_a”.
- basePath inclou el codi de diàleg. Per exemple: “/0192/api_a”. Per tal de resoldre la crida al target-url de l’aplicació, s’implementa un pas a l’Assembly que s’encarrega d’eliminar el codi de diàleg del requestPath (en cas que el valor d’APIC_PRESERVE_ASSEMBLY sigui false).

En qualsevol cas, si aquests criteris no s’acompleixen a la configuració del producte o les APIs, el SIC durà a terme els reemplaçaments necessaris per a assegurar la seva aplicació (en cas que el valor d’APIC_PRESERVE_ASSEMBLY sigui false). Donat el nom del producte és immutable, aquest no es demana de cara a l’execució de les pipelines operatives de gestió del cicle de vida: DELETE, DEPRECATE, REPLACE, RETIRE i SUPERSEDE.

Categories de cerca

Amb l’objectiu de permetre l’aplicació de criteris de cerca sobre productes i APIs publicades als diferents catàlegs, el SIC s’encarrega de la injecció automàtica de dos nivells estàndards de categories per codi de diàleg i nom del projecte. Aquestes categories no invalidaran en cap cas les que es puguin haver indicat a la configuració, simplement s’afegiran si no hi són.

Exemples

A continuació, es mostren exemples amb els criteris aplicats:

Exemple de configuració de producte:

info:
  version: 1.0.1
  title: 0192 APIM Demo Project
  name: 0192-apim_demo_project
  categories:
    - '0192'
    - '0192/apim_demo_project'

Exemple de configuració d’API:

swagger: "2.0"
info:
  version: 1.0.1
  title: 0192 APIM Demo Project Api_a
  x-ibm-name: 0192-api_a
basePath: /0192/api_a
x-ibm-configuration:
  ...
  categories:
    - '0192'
    - '0192/apim_demo_project'
    - '0192/apim_demo_project/api_a'
  ...

Preparació de productes i APIs

Un cop fet el desenvolupament amb API Designer, caldrà exportar els yml de definició del producte i les seves APIs per a repositar-los al sistema de gestió de codi font (SCM - Source Code Management) del SIC d’acord amb les següents premisses:

Cada producte es correspondrà amb un projecte dins el codi de diàleg adient, de forma que tota la gestió posterior de pipelines i creació de peticions Remedy o Jira s’associïn a l’aplicació corresponent. Per aquest mateix motiu, no està contemplat la creació de subgrups de projectes, tot i que l’eina ho permeti.
Per a desplegaments en SIC 3.0, els projectes poden tenir tantes branques com siguin necessàries, però sempre s’haurà d’incloure la branca MASTER i el contingut d’aquesta branca serà amb el que treballaran les pipelines de desplegament per defecte. No obstant això, el sistema permetrà opcionalment desplegar el codi font associat a la branca EVOLUTIUS.
Per a desplegaments en SIC +, se seguirà el model Gitops tal com s’ha definit per a la resta de projectes de SIC+ i el detall dels quals pot veure’s en el següent enllaç: Exemple e2e API MANAGER
Les pipelines seran les encarregades de generar els TAGS de Release de codi corresponents tan bon punt es desplegui amb èxit a producció.

Preparació de la integració al SIC 3.0

Per tal de configurar la integració al SIC 3.0, tots els projectes hauran de disposar de la carpeta /sic al primer nivell de carpeta i, dins d’aquesta carpeta, caldrà crear l’arxiu de configuració aca.yml que proporcionarà la configuració necessària:

Variable	Requerit	Descripció	Valor per defecte	Exemple
APIC_PRODUCT_FILE	No	Ruta i nom del fitxer descriptor per al desplegament de l’aplicació a l’Api Manager. La variable només serà requerida en cas que la ruta i/o nom del fitxer difereixi del suggerit	product.yml	APIC_PRODUCT_FILE: ‘product_v1.0.0.yaml’
APP_NAME	No	Nom corresponent al producte que es vagi a desplegar. Aquest nom no ha de contenir el codi de diàleg del projecte, ja que aquest serà inclòs de manera automàtica després de realitzar-se el desplegament amb el format -<APP_NAME>. En cas que no es configuri aquesta variable en el ACA, se li assignarà per defecte el nom de la carpeta del projecte de GIT.	Nom de la carpeta del projecte	APP_NAME: ’technicalproduct’
APIC_PRESERVE_ASSEMBLY	No	Curricular que indica si s’ignora o no la regla que reemplaça l’acoblament, a través dels valors true o false, conservant l’acoblat original del YAML de l’API (secció assembly al YAML) creat pel desenvolupador, en cas que el camp s’informi amb el valor true. Això permetrà desplegar l’API amb lògica personalitzada.	false	APIC_PRESERVE_ASSEMBLY: true
APIC_TARGET_URL	Si	URL de destí de les APIs si és comuna a totes, tot i que pot conviure amb APIC_TARGET_URL_{N} per especificitats.	-	APIC_TARGET_URL: ‘https://backend/api’
APIC_TARGET_URL_{N}	No	URL de destí de les APIs si NO és comuna a totes les APIs permetent definir especificitats, tot i que pot conviure amb APIC_TARGET_URL global: - Format de la clau: APIC_TARGET_URL_{0-9a-zA-Z} - Format del valor: <api-file-name-with-extension>:<target-url>	-	APIC_TARGET_URL_1: ‘api_1.0.0.yml:https://backend/api’
APIC_GATEWAY_SERVICES	No	Gateway services en els quals aplicar el desplegament dels quals tingui configurats l’espai. Els valors poden ser ‘All’ o una llista dels gateway services separat per comes. Si no s’informa, es desplegarà en tots, equivalent a informar ‘All’	-	APIC_GATEWAY_SERVICES: ‘azure-intranet-pro,azure-internet-pro’

Per exemple:

version: 2.0.0 # aca schema version
info:
  version: 1.0.1
  description: APIM Demo Project
global-env:
  - APIC_PRODUCT_FILE: 'product.yml'
  - APP_NAME: 'technicalproduct'
  - APIC_PRESERVE_ASSEMBLY: true
components:
  - deployment:
      environments:
        - name: privat_pre
          actions:
            deploy:
              steps:
                - execution:
                    env:
                      - APIC_TARGET_URL: 'https://common-backend/pre' # aplicable a totes les apis excepte API_C
                      - APIC_TARGET_URL_1: 'api_c.yml:https://backend-apic/pre'
                      - APIC_GATEWAY_SERVICES: 'All'
        - name: public_pre
          actions:
            deploy:
              steps:
                - execution:
                    env:
                      - APIC_TARGET_URL: 'https://common-backend/pre' # aplicable a totes les apis excepte API_C
                      - APIC_TARGET_URL_1: 'api_c.yml:https://backend-apic/pre'
                      - APIC_GATEWAY_SERVICES: 'All'
        - name: privat
          actions:
            deploy:
              steps:
                - execution:
                    env:
                      - APIC_TARGET_URL: 'https://common-backend/pro' # aplicable a totes les apis excepte API_C
                      - APIC_TARGET_URL_1: 'api_c.yml:https://backend-apic/pro'
                      - APIC_GATEWAY_SERVICES: 'azure-intranet-pro,aws-intranet-pro'
        - name: public
          actions:
            deploy:
              steps:
                - execution:
                    env:
                      - APIC_TARGET_URL: 'https://common-backend/pro' # aplicable a totes les apis excepte API_C
                      - APIC_TARGET_URL_1: 'api_c.yml:https://backend-apic/pro'
                      - APIC_GATEWAY_SERVICES: 'aws-internet-pro,azure-internet-pro'
notifications:
  email:
    recipients:
      - noreply@gencat.cat

On es pot comprovar que s’ha definit una target-url global i una d’específica per a l’API_C.

Per a més informació, podeu consultar: Com construir el fitxer ACA

Preparació de la integració al SIC+

En el següent enllaç es pot consultar el detall i un exemple complet de desplegament de APIM des de SIC+: Exemple e2e API MANAGER

Modificació de plans

Mitjançant l’operativa replau es podran modificar els plans assignats a pipelines ja desplegades. Per a fer-ho, hem de definir un fitxer yaml al costat dels fitxers de producte i APIs amb la següent estructura:

plans:
- source: default-plan
  target: silver
- source: bronze
  target: bronze
- source: gold
  target: silver
- source: silver
  target: silver

En SIC 3.0, quan s’invoqui la pipeline REPLACE, en el formulari on s’indica entorn i versions d’entrada i sortida, s’ha afegit un nou camp desplegable que oferirà un llistat dels fitxers yaml que s’hagi trobat en el repositori amb l’estructura abans indicada.

Si seleccionem algun d’ells, aplicarà aquest mapatge de plans en el reemplaçament. Si indiquem Auto, mantindrà els plans actuals tal com estan.

En el cas de SIC+, en el formulari d’inputs en invocar el workflow, s’haurà d’especificar la ruta relativa dins del repostiorio juntament amb el nom del fitxer amb el mapatge de plans a aplicar.

apim-replace-map-sic+.png

Si no s’especifica cap valor o s’especifica Auto, mantindrà els plans tal com estan ara mateix.

Publicació de APIs

La publicació d’una nova versió de producte i les APIs associades es realitza invocant la pipeline PUBLISH en SIC 3.0 o l’operativa PUBLISH en el workflow de CD si és en SIC+

A cada producte li correspondrà publicar els seus APIs en un conjunt de service gateways de destí que configurarà l’oficina tècnica de APIM per a cada cas i això vindrà donat. Per defecte el desplegament es realitza en tots els service gateways configurats, però és possible especificar desplegar només en un subconjunt d’aquests gateways.

Publicació des de SIC 3.0

En el cas de SIC 3.0, la manera d’especificar els service gateway de destí serà mitjançant una variable que es configurarà en el fitxer ACA.yml tal com es pot veure en aquest exemple:

components:
 - deployment:
      environments:
        - name: privat_pre
          actions:
            deploy:
              steps:
                - execution:
                    env:
                      - APIC_TARGET_URL: 'https://backend/pre'
                      - APIC_GATEWAY_SERVICES: 'azure-intranet-pre,azure-internet-pre'
                      # - APIC_GATEWAY_SERVICES: 'All'

Possibles valors de APIC_GATEWAY_SERVICES:

No s’especifica: desplega en tots els GW. Comportament per defecte.
Es posa “All|all|ALL”, desplega en tots els GW. Comportament per defecte.
Llista de GW separada per comes: desplegarà en aquesta llista.

Publicació des de SIC+

En el cas de SIC+, els service gateways de destí han d’especificar-se com a inputs en la invocació del workflow de CD:

apim-publish-gw-sic+.png apim-replace-map-sic+.png

Possibles valors de Gateways to deploy:

No s’especifica: desplega en tots els GW. Comportament per defecte.
Es posa “All|all|ALL”, desplega en tots els GW. Comportament per defecte.
Llista de GW separada per comes: desplegarà en aquesta llista.

Funcionament

El SIC s’encarrega de la publicació i el desplegament automatitzat de les APIs, atorgant la màxima agilitat i autonomia als equips de desenvolupament. En aquest sentit, es proporciona un conjunt de operacions que permeten gestionar el seu cicle de vida d’una forma estandarditzada:

PUBLISH: publicació d’una nova versió d’un producte i APIs associades. El sistema permet redesplegar versions als catàlegs preproductius sempre que no hagin arribat a producció. De manera prèvia a la publicació, es realitzarà una validació de producte i APIs a publicar contra les regles de govern definides per l’oficina. Si existeixen errors, s’avortarà la publicació.
INFO: obtenció d’informació del producte dins d’un catàleg (versions, subscripcions i altres). Caldrà seleccionar el catàleg del qual es desitja informació.
Operatives:
- DELETE: eliminació del producte. Caldrà seleccionar el catàleg sobre el qual es desitja esborrar i indicar la versió del producte (CURRENT_PRODUCT_VERSION). Per exemple: 1.1.0.
- DEPRECATE: deprecació d’una versió del producte sense deixar cap versió vigent. Caldrà seleccionar el catàleg sobre el qual es desitja deprecar i indicar la versió del producte (CURRENT_PRODUCT_VERSION). Per exemple: 1.1.0.
- REPLACE: retirada d’una de les versions vigents del producte i migració de subscripcions. S’eliminarà el draft o esborrany de la versió retirada. Caldrà seleccionar el catàleg sobre el qual es desitja reemplaçar, indicar la versió actual del producte (CURRENT_PRODUCT_VERSION) i la nova versió del producte (NEW_PRODUCT_VERSION). Per exemple: 1.1.0. També es podrà indicar un nou mapatge de plans tal com s’ha indicat anteriorment.
- RETIRE: retirada d’una versió del producte sense deixar cap versió vigent (les subscripcions es perden). S’eliminarà el draft o esborrany de la versió retirada. Caldrà seleccionar el catàleg sobre el qual es desitja retirar i indicar la versió del producte (CURRENT_PRODUCT_VERSION). Per exemple: 1.1.0.
- SUPERSEDE: deprecació d’una de les versions vigents del producte i marcat de subscripcions “migrated”. S’eliminarà el draft o esborrany de la versió retirada. Caldrà seleccionar el catàleg sobre el qual es desitja fer el supersede, indicar la versió actual del producte (CURRENT_PRODUCT_VERSION) i la nova versió del producte (NEW_PRODUCT_VERSION). Per exemple: 1.1.0.

Per a més informació, podeu consultar: Servei d’API Manager Corporatiu.

Les pipelines notificaran dels resultats a les adreces de correu assignades.

Projecte d’exemple

Podeu descarregar el següent Projecte d’exemple, que mostra una configuració completa d’un producte.

Si teniu qualsevol dubte o problema podeu revisar les Preguntes Freqüents o utilitzar els canals de Suport.

Data d'actualització: 11-09-2024

Cercador

Centre de Telecomunicacions i Tecnologies de la Informació

Com preparar productes i APIs per al desplegament a l'API Manager