FAQ

Conceptes generals

Què és l’API Manager Corporatiu i per què serveix?

És una plataforma corporativa basada en IBM API Connect que permet als departaments i proveïdors d’aplicacions de la Generalitat gestionar el cicle de vida dels seus API de manera segura i senzilla. Facilita la publicació, la descoberta, el consum i la monitorització d’APIs, tant públiques com privades, en entorns d’intranet i extranet.

Quines funcionalitats principals ofereix el servei?

• Catàleg per versionar i descobrir APIs. 

• Autoservei per a subscripció a API mitjançant plans definits. 

• Portal per a desenvolupadors amb documentació associada. 

• Anàlisi d’ús i control de consum d’APIs. 

• Aplicació de polítiques d’ús i seguretat. 

• Integració amb autenticació GICAR (KeyCloak Corporatiu). 

• Servei ofert en modalitat SaaS de pagament per ús. 
  
  

Quins elements componen la plataforma?

• Portal per a desenvolupadors. Element per a consumidors d’APIs, on poden consultar les APIs disponibles, obtenir informació sobre el seu ús, sol·licitar-hi accés mitjançant una subscripció i realitzar proves de crides a APIs. 

• Portal de gestió d’APIs. Element per a gestors d’APIs, on podeu administrar accessos, recursos, APIs, productes i analitzar dades d’accés i consum. 

• API Gateway. Element tecnològic escalable que gestiona les peticions en temps d’execució, aplicant polítiques i redirigint les sol·licituds als backends corresponents.  

• Analytics. Element que permet filtrar, ordenar i afegir les dades de les peticions a les APIs per monitoritzar-les i obtenir informació sobre el seu ús. 
  
  

Quina és la versió del servei d’IBM API CONNECT en ús?

La versió actual de la instància reservada de l’IBM API Connect és la 10.0.8, i la versió del microprogramari de l’IBM Datapower Gateway versió és la 10.5.x, encara que en un futur proper s’actualitzarà a la 10.6.x.

Quins tipus d’API Gateways estan disponibles?

El servei ofereix infraestructura compartida on-premise desplegada a CPD2. En el futur proper es procedirà a la seva ampliació desplegant de forma conteneritzada noves Gateways a CPD4 i els hiperescalars (AWS, Azure, GCP).

Com s’organitza la plataforma en termes de catàlegs, espais i productes?

IBM API Connect compta amb el següent sistema organitzatiu:

• Catàleg. Col·lecció de productes que permet separar les APIs i la seva publicació en diferents entorns (exemple: PRE i PRO). En el cas de CTTI, es compta amb 4 catàlegs: PRIVAT-PRE, PRIVAT, PUBLIC-PRE i PUBLIC. 

• Espai. Partició dins d’un catàleg per separar la gestió de productes entre equips. En el cas de CTTI, es generen espais per codi de diàleg amb la nomenclatura següent: CDXXXX.

• Producte. Unitat mínima que agrupa APIs i plans, i que es versiona i desplega conjuntament. 

• API. Ha d’estar inclosa en, almenys, un producte i un pla del producte per poder ser desplegada. 

• Pla. Controla l’accés i l’ús de les API dins d’un producte. Compte amb un límit de “rate” i un límit de “burst”.
  
  

Com s’organitza la documentació del servei API Manager Corporatiu?

La documentació està organitzada en tres seccions principals: 

• Proveïdors. Recursos per a usuaris que desenvolupen APIs i productes a la plataforma. 

• Consumidors. Recursos per a usuaris que consumeixen APIs i productes disponibles a la plataforma. 

• Operatives. Recursos que descriuen les operatives i els procediments que l’Oficina Tècnica pot realitzar.  
  
  

Proveïdors

Com puc publicar una API a la plataforma?

Per publicar una API, heu de seguir els passos següents:

1. Dissenyeu l’API utilitzant les plantilles proporcionades en format OpenAPI 3.0 o 2.0.

2. Desenvolupar i provar l’API en un entorn local utilitzant eines com l’IBM API Connect Toolkit i l’entorn de proves local (LTE).

3. Pujar els fitxers de definició (YAML) al dipòsit corresponent a GitLab o GitHub, segons l’entorn de desplegament (SIC 3.0 o SIC+).

4. Sol·licitar el desplegament a través de les pipelines configurades a Jenkins (SIC 3.0) o workflows a GitHub (SIC+).  
   
   

Com puc sol·licitar proves de rendiment per als meus APIs?

Per sol·licitar proves de rendiment: 

1. Obre un tiquet ACOAPIM a JIRA indicant les APIs a provar, volum de trucades, horari proposat i entorn (normalment PRE). 

2. L’Oficina Tècnica avaluarà la viabilitat de la prova en termes de volum i horari. 

3. Si s’aprova, es coordinarà amb l’equip de CPD per a l’execució de la prova i, si s’ha sol·licitat, la recopilació de mètriques. 

4. Després de la prova, s’han de proporcionar les mètriques obtingudes al proveïdor si s’han sol·licitat.

Tot el detall a la següent url: https://canigo.ctti.gencat.cat/plataformes/apim/rendiment/

Quina documentació està disponible per als proveïdors d’APIs?

Els proveïdors d’APIs tenen accés a diversos recursos que detallen les característiques i les metodologies de treball del servei d’API Manager. Entre ells s’inclouen manuals de conceptes generals, guies de desenvolupament, plantilles en formats OpenAPI 3.0 i 2.0, estàndards de nomenclatura, bones pràctiques i documentació sobre polítiques i extensions personalitzades. Aquests recursos estan disponibles a la secció de proveïdors de la documentació oficial: https://canigo.ctti.gencat.cat/plataformes/apim/documentacio/#prove%C3%AFdors.

On puc trobar les plantilles per desenvolupar APIs?

Les plantilles per al desenvolupament d’APIs en formats OpenAPI 3.0 i 2.0, així com la plantilla de producte, estan disponibles a la secció de proveïdors de la documentació oficial: https://canigo.ctti.gencat.cat/plataformes/apim/documentacio/#prove%C3%AFdors.

Quines guies estan disponibles per al desplegament d’APIs i productes?

La documentació proporciona una guia de desplegament que detalla com desplegar APIs i productes als entorns de l’API Manager Corporatiu. Aquesta guia inclou passos per utilitzar eines com l’IBM API Connect Toolkit i l’entorn de proves local (LTE). Es pot trobar aquesta guia tant a la secció de proveïdors de la documentació oficial, https://canigo.ctti.gencat.cat/plataformes/apim/documentacio/#prove%C3%AFdors, com a la secció de desplegament de Canigó: https://canigo.ctti.gencat.cat/plataformes/apim/desplegament/

Quins estàndards de nomenclatura i bones pràctiques cal seguir?

La documentació inclou documents específics sobre estàndards de nomenclatura i bones pràctiques per al desenvolupament d’APIs i productes. Aquests documents ajuden a garantir la coherència i qualitat en els desenvolupaments realitzats a la plataforma i es poden trobar a la secció de proveïdors de la documentació oficial: https://canigo.ctti.gencat.cat/plataformes/apim/documentacio/#prove%C3%AFdors.

Què són les polítiques i extensions personalitzades a l’API Manager?

Les polítiques i extensions personalitzades són fragments de codi que fan una funcionalitat específica que es poden utilitzar a l’entorn de l’API Manager Corporatiu per adaptar el comportament de les API segons les necessitats del projecte. El document DT Polítiques i Extensions proporciona un disseny tècnic amb descripcions més detalladament d’aquestes polítiques i extensions, així com guies per a la seva implementació, i es pot trobar a la secció de proveïdors de la documentació oficial: https://canigo.ctti.gencat.cat/plataformes/apim/documentacio/#prove%C3%AFdors

Com puc importar polítiques personalitzades per fer les proves en local?

Al document Manual importació polítiques entorn local es poden trobar detalls on es troben els fitxers corresponents per descarregar i el procés d’importació de polítiques personalitzades a l’entorn local, utilitzant eines com l’IBM API Connect Toolkit i l’LTE. Es pot trobar aquesta guia a la secció de proveïdors de la documentació oficial: https://canigo.ctti.gencat.cat/plataformes/apim/documentacio/#prove%C3%AFdors.

Com puc muntar el LTE (Local Testing Environment) per fer les proves en local?

Los detalles de la instalación y configuración del LTE, que incluye instrucciones para instalar y configurar el entorno local de IBM API Connect, está disponible en el documento Guia d’instal·lació i configuració de LTE en la sección de proveedores en la documentación oficial: https://canigo.ctti.gencat.cat/plataformes/apim/documentacio/#prove%C3%AFdors.. 

Com se sol·licita l’obertura de regles de tallafocs entre l’API Manager (Intranet) i el backend?

• Per a les regles de tallafocs amb origen API Manager i la destinació backend (aplicació), se sol·licita a través d’un tiquet ACOAPIM facilitant la següent plantilla emplenada:

  Petició obertura de Regles Firewall

  • Entorn: PRE/PRO

  • **IPs:**x.x.x.x

  • Port: xxx

  • Protocol: TCP/UDP (Per defecte TCP)

  • Codi i nom de la vostra aplicació: xxxx

  • En quin CPD està allotjada la vostra aplicació: xxxx

• Per a les regles amb origen aplicació i la destinació API Manager (Intranet)

  Han de sol·licitar/realitzar les configuracions de tallafocs corresponents els mateixos responsables del projecte. Per això, se sol·licita a l’oficina les IPs i ports dels Gateways per als entorns que correspongui a través del tiquet ACOAPIM.

Nota: Per als entorns Public i public-pre d’API Manager NO cal obrir regles de tallafocs, atès que estan exposats a internet i el poden consumir tant un consumidor extern com intern de CTTI.

No puc accedir a ACOAPIM/ACOCLDSIC. Com puc sol·licitar els permisos?

Per sol·licitar permisos als diferents JIRAs, cal fer-ho a través del portal d’autoservei ÁTOM fent clic a la secció Gestió accés d’usuaris.

Cal proporcionar les dades requerides.

Un cop assignats els permisos, caldrà accedir als JIRA que corresponguin per verificar que ja es disposa d’accés:

• ACOAPIM: https://cstd-ctti.atlassian.net/jira/software/c/projects/ACOAPIM/issues/

• ACOCLDSIC: https://cstd-ctti.atlassian.net/jira/software/c/projects/ACOCLDSIC/issues/
  
  

He accedit a l’IBM CLOUD però no aconsegueixo visualitzar l’etiqueta “CTTI” per la secció de “Services”.

En cas que no podeu veure l’etiqueta ctti a la secció de Services, cal demanar permís de lectura (Rol-API Manager Developer) a l’OFT d’API Manager a través d’un tiquet JIRA ACOAPIM, facilitant el correu associat amb el compte de GICAR.

Consumidors

Quines són les urls dels portals de desenvolupadors?

Les URL dels portals de desenvolupadors són les següents:

• PRE INTRANET (privat-pre): https://portal.db40-c57f0fcb.eu-de.apiconnect.appdomain.cloud/ctti/privat-pre 

• PRO INTRANET (privat): https://portal.db40-c57f0fcb.eu-de.apiconnect.appdomain.cloud/ctti/privat  

• PRE INTERNET (public-pre): https://portal.db40-c57f0fcb.eu-de.apiconnect.appdomain.cloud/ctti/public-pre 

• PRO INTERNET (public): https://portal.db40-c57f0fcb.eu-de.apiconnect.appdomain.cloud/ctti/public  
  
  

Com puc consumir una API publicada?

Per consumir una API: 

1. Accedeix al portal de desenvolupadors i registra’t creant una nova organització consumidora o unint-te a una existent mitjançant invitació. 

2. Crea una aplicació per obtenir les credencials corresponents. 

3. Consulta el catàleg d’APIs disponibles i subscriu-te, fent ús de l’aplicació creada, al producte que contingui l’API del teu interès mitjançant el pla corresponent. 

4. Utilitza les credencials corresponents per fer crides a l’API segons la documentació proporcionada.  
   
   

Quins recursos estan disponibles per als consumidors d’APIs?

Els consumidors d’APIs disposen d’un manual específic que explica els conceptes generals del servei, com subscriure’s i consumir les API disponibles a la plataforma. Aquest manual es troba a la secció de consumidors de la documentació oficial: https://canigo.ctti.gencat.cat/plataformes/apim/documentacio/#consumidors.

He fet una trucada a l’API i m’ha donat 401 Unauthorized, com ho puc solucionar?

L’error 401 Unauthorized indica error en l’autenticació del client per part del servidor i generalment es deu als motius següents:

1. Capçaleres Client ID i/o Client Secret mal configurades.

   En aquest cas, cal comprovar que el Client Id que s’ha configurat a la capçalera de la petició és el correcte. El valor del Client Id és la clau que s’obté en crear l’aplicació al portal de desenvolupadors.

   Nota: En cas que l’API estigui definit amb seguretat Client Id + Client Secret, cal revisar que el camp Client Secret estigui ben configurat també.

2. L’aplicació associada amb el Client Id en ús no està subscrita al producte de l’API desplegat a l’API Manager.

   En aquest cas, cal comprovar que l’aplicació creada al Portal de desenvolupadors té una subscripció activa sobre el producte de l’API sobre el qual es fan les trucades.

   Per a més informació, vegeu apartat 4 del manual de consumidors, que es troba a la secció de consumidors de la documentació oficial: https://canigo.ctti.gencat.cat/plataformes/apim/documentacio/#consumidors.

3. El token OAuth no és correcte.

   En aquest cas, cal comprovar dos punts:

   • El token està configurat a la capçalera Authorization, i el seu valor segueix el format següent: Bearer (token)

   • (En cas que la configuració d’OAuth inclogui scopes) Reviseu que el token OAuth generat inclou els scopes especificats en la definició de l’API.

Operatives

Quin suport ofereix l’Oficina Tècnica de l’API Manager?

L’Oficina Tècnica proporciona assistència i ajuda amb les tasques següents:  

• Configuració de permisos d’usuaris i accessos. 

• Creació d’espais i assignació de gateways. 

• Configuració de certificats TLS i proveïdors OAuth. 

• Validació de seguretat de les APIs i plans de consum dels productes. 

• Definició de fitxers YAML i resolució de problemes relacionats amb l’API Manager. 

• Gestió de subscripcions i anàlisi d’ús. 

• Gestió de regles de tallafocs.

Què inclou el Manual d’operatives de l’Oficina Tècnica API Manager?

Aquest manual descriu les operatives que l’Oficina Tècnica d’API Manager pot fer durant l’acompanyament de projectes o el manteniment del servei dins la plataforma SaaS d’API Connect. Inclou procediments per a la configuració de permisos d’usuaris, creació d’espais, assignació de gateways, configuració de certificats TLS i proveïdors OAuth, entre d’altres. Aquest manual es troba a la secció de operatives de la documentació oficial: https://canigo.ctti.gencat.cat/plataformes/apim/documentacio/#operatives