Gobierno de Apis

Consideraciones generales

Presentador:
Yvon Zalec.
Objetivo

Presentar un conjunto de actividades que deben ser

tomadas en cuenta para la gestión de las apis
durante su ciclo de vida.
A partir de estas actividades conocer las mejores
prácticas y experiencias que se adhieren al estilo
arquitectónico REST de la web.

2
Actividades

1. Taxonomía: Clasificación del api, definición del

recurso, operaciones e identificadores.
2. Atributos de la API: sintaxis, semántica, contenido.
3. Políticas de versionado.
4. Documentación.
5. Monitorización.
6. Metodología.
7. Actividades del Rol.
Taxonomía / Clasificación

Capa Presentación Capa Negocio Capa Soporte

API UX canal 1 API BS

Account V1

API UX canal 2 API BS

Customer V2

API SP Keyboard
API UX canal 3 API BS Loan V1 V1

4
Taxonomía: Clasificación

1
Presentación
1. ¿Qué considerar como api de Presentación?
• Satisfacción de requerimiento funcional
• Entrega de información pertinente
2. ¿Qué considerar como api de Negocio?
• Estándares en la comunicación comunes
APIS • Permite interacción con entidades de negocio
• Acceso a los procesos del negocio
• Uso y encapsulamiento de procesos repetitivos
3 2
Soporte Negocio
3. ¿Qué considerar cono api de Soporte?
• Atender un requerimiento en específico
• Algunas librerías o conectores de acceso

5
Taxonomía: Recurso, operaciones e identificadores
Están diseñadas alrededor de recursos
Las apis REST

como una entidad de negocio que será expuesta por la API

Definimos un
recurso
persona, cuenta, producto y/o servicio
Ejemplos:

Sustantivos si, verbos no. Lo importante aquí es no usar verbos y enfocarnos en los sustantivos que describen a cada recurso
Tener en cuenta:
Plural mejor que singular, para lograr uniformidad

Uso de guiones para mejorar el entendimiento de los nombres

Debe permitir el uso natural de los métodos HTTP

Métodos HTTP:

que es un URI que identifica de forma única ese recurso

Un recurso tiene
un identificador

6
Taxonomía: Recurso y operaciones

La siguiente tabla resume las convenciones comunes

adoptadas por la mayoría de las implementaciones de REST.
Tenga en cuenta que no todas estas solicitudes podrían
implementarse; Depende del escenario específico.

Recurso
POST GET PUT DELETE
/customers Crea un nuevo cliente Obtiene lista de clientes Modifica en forma Borra los clientes
masiva
/customers/1 - Obtiene el cliente 1 Modifica el cliente 1 Elimina el cliente 1

/customers/1/orders Crea una orden para el Obtiene una lista de Modifica masivamente Elimina todas las
cliente 1 ordenes del cliente 1 las ordenes del cliente 1 ordenes del cliente 1

7
Taxonomía: Identificadores de recursos

Las API de REST utilizan identificadores de recursos

uniformes (URI) para abordar los recursos. En el
diseño de las URIS se busca comunicar la
funcionalidad de la API.

Vs

8
Taxonomía: Identificadores de recursos -
Visión funcional:
Descomposición
Funcional

Área de
Negocio

Dominio de
Negocio

Dominio de
Servicio

9
Taxonomía: ¿Qué es BIAN?

BIAN – Banking Industry Architecture Network / Red de Arquitectura de la Industria Bancaria

BIAN es una asociación de bancos, proveedores de soluciones e instituciones educativas con el objetivo
compartido de definir un estándar de operación de servicio semántico para la industria bancaria.

Su misión es ayudar y guiar a la industria bancaria hacia un enfoque basado en el consenso para lograr
una arquitectura flexible que esté estrechamente alineada con los objetivos comerciales de mayor agilidad y
reducción de costos.

10
 Taxonomía: BIAN: Service Land Sape v7
Los aspectos de negocio fundamentales de los bancos se encuentran definidos en 3 niveles que son:

Área de Negocio
Agrupa un conjunto de capacidades

Dominio de Negocio
Colección coherente de capacidades

Dominio de Servicio
Capacidades empresariales

BIANServiceLandscapev7.0 - Servicio de Panorama Simplificado

https://bian.org/servicelandscape/

11
Taxonomía: BIAN: Ubicar una funcionalidad

Área de Negocio

Dominio de Negocio

Dominio de Negocio

Dominios de Servicio

12
BIAN: Definir una api

La definición de los servicios y/o Apis trae consigo ciertos componentes:

Las API Rest tienen una URL base, la url base esta definida por la plataforma
(schemas, host) y el base path.
En ocasiones el endpoint o funcionalidad dentro de la api será representada por el Path
Operation, quedando :

Funcionalidad
1
Plataforma Base Path

Funcionalidad Path
2
Plataforma Base Path
Operation

13
BIAN: Definir una api

Componentes de la URL:

Plataforma Schema Host

Base Path Api type Api version Api name

Path Identificadores Subrecursos Controladores

Operation

14
 BIAN: Definir una api V1
Base Path. Prefijo de todos los paths de la Api.
Ejemplo: bs/loans-deposit/current-account/v1/current-accounts

Api Type Dominio Versión Nombre

Funcional Api del Api
Experiencia
UX

Business
BS Dominio de Dominio de
V1 Nombre
Negocio Servicio Recurso
Soporte
SP

15
BIAN: Definir una api

Todo lo aplicado anteriormente puede representarse en la siguiente tabla

16
 Atributos de la API: sintaxis, semántica

Una Plataforma común para el uso de mensajes

¿Que es
la ISO Busca que los servicios hablen un mismo idioma, es decir, que todos sus atributos se definan de una misma forma
en todos los servicios
20022? ISO 20022 es solo un ejemplo de un estándar utilizado en la industria financiera.

La sintaxis es el formato en el que se estructura la información de un mensaje. Es el formato, o el "lenguaje"

La barrera utilizado para expresar esa información.

de la XML es una de las sintaxis más populares para codificar documentos (o mensajes) electrónicamente en Internet.

sintaxis La arquitectura REST permite a los proveedores de API entregar datos en múltiples formatos, como texto sin
formato, HTML, XML, YAML y JSON, que es una de sus características más queridas.

O interpretación de términos.
La barrera
semántica Especialistas en diferentes dominios han desarrollado su propio vocabulario. Diferentes palabras pueden referirse
al mismo concepto o, peor aún, la misma palabra puede tener diferentes significados.

Estos nombres diferentes crean dificultades cuando se busca una integración de un extremo a otro. Necesita
conocimientos expertos para comprender lo que quieren decir los especialistas y cómo conciliar la información.
17
Atributos de la API: contenido

18
Atributos de la Api: BIAN

Con BIAN implementado ISO 20022 se busca que los servicios hablen un mismo
idioma, es decir, que todos sus atributos se definan de una misma forma en
todos los servicios.

19
 Atributos de la Api : BIAN

Referencias ISO 20022

documentType Tipo de Documento https://www.iso20022.org/standardsrepository/type/Person

documentNumber Número de Documento https://www.iso20022.org/standardsrepository/type/Person

20
Políticas de Versionado

Versionado Semántico 2.0.0:

Dado un número de versión MAYOR.MENOR.PARCHE, se incrementa:
1.la versión MAYOR cuando realizas un cambio incompatible en el API,
2.la versión MENOR cuando añades funcionalidad que compatible con versiones
anteriores, y
3.la versión PARCHE cuando reparas errores compatibles con versiones anteriores.

• GET descomposición-funcional/v1/recurso
Url

• Accept: application/vnd.company.myapp-v3+js
Header • Content-Type: application/vnd.company.myapp-v3+jsonon

21
Documentación

1. Formato de documentación:
✓ Doc
✓ HTML
✓ RAML / Swagger

2. ¿Dónde se deja la documentación?

3. ¿Quién es el responsable de tener la
documentación actualizada?

22
Monitorización:

1. Estadísticas de uso:
✓ Número de solicitudes por aplicación.
✓ Número de solicitudes por usuario (si es posible).
✓ Número de solicitudes por recurso.

2. Alertas

23
Metodología
Development
1. Definición
2. ¿fake? Servidor de mocks
3. Desarrollo Definición
Testing /
validation

4. Testing / validation
5. Implementación
6. Obsolescencia Implementación

Obsolescencia

24
Metodología

Design First: el plan se convierte en un contrato legible por humanos y máquinas (API), como un documento
Swagger, a partir del cual se construye el código.

Code First: según el plan de negocios, la API se codifica directamente, a partir de la cual se puede generar
un documento humano o legible por máquina, como un documento Swagger

25
Actividades de Gobierno

✓ Definición funcional de las apis.

✓ Definición del versionado.
✓ Definición del estándar.
✓ Validación de las apis.
✓ Capacitación a los desarrolladores.

26