ODS Inquiry API
| Este documento describe la Versión 2 de la ODS Inquiry API. Para obtener más información sobre el versionado de la Inquiry API y la documentación de la Versión 1, consulta la visión general del versionado. |
Descripción general
La ODS Inquiry API expone datos capturados por ODS y está dividida en varias capas de abstracción. Para la especificación OpenAPI completa, consulta ODS Inquiry V2 Specification.
Capa de objetos
La capa de objetos permite buscar tipos de datos de ODS de bajo nivel y sin procesar. Esta API no tiene conocimiento de las implementaciones más específicas de estos tipos y, por lo tanto, la búsqueda es limitada. Si necesitas buscar un objeto de datos con atributos específicos del tipo, consulta las APIs de Catalogue.
Esta API devuelve objetos que generalmente se mapean uno a uno con los tipos almacenados.
| Searching For | URL |
|---|---|
All process objects |
|
All custom objects |
|
All MDS objects |
|
All PDS objects |
|
Capa de catálogo
La capa de catálogo es una API fuertemente tipada, que permite parámetros de búsqueda específicos por tipo, p. ej., buscar un objeto MDS de transacción de transferencia de crédito pain.001, por creditorAgentBic, o buscar un objeto de proceso de evento del sistema, por level, source y type.
| Type | Example URL |
|---|---|
ISO 20022 MDS Objects |
|
Message Logs |
|
System Events |
|
Process Flow Events |
|
Process Flow Definitions |
|
Capa de vistas
La capa de vistas es una API de alto nivel centrada en el negocio. Los datos normalmente se construyen a partir de los tipos de datos brutos de ODS en el momento de la ingesta, aunque también pueden construirse a partir de los datos de ODS en el momento de la consulta.
Los parámetros de búsqueda para estos tipos son específicos del tipo que se esté buscando.
| Type | Example URL |
|---|---|
Search Payment Summaries |
|
Get Payment Summary by unitOfWorkId |
|
Get Unit Of Work Details |
|
Get Unit Of Work Graphs |
|
Casos de uso de la API
Encontrar un pago
La manera más rápida de buscar un pago es mediante el endpoint de payment summary que admite un gran número de parámetros de búsqueda.
curl "http://localhost:8080/api/v2/views/summaries/payments?transactionId=some-transaction-id"Encontrar un pago por un identificador personalizado
Esto puede lograrse usando los Alternative Identifiers que se han asociado a una unidad de trabajo.
curl "http://localhost:8080/api/v2/views/summaries/payments?alternativeIdentifierName=SomeClientIdentifier&alternativeIdentifierValue=some-clients-custom-identifier-value"El alternative identifier debe estar asociado a la unidad de trabajo de antemano, ya sea a través de IPF Processing Data o enviado por separado mediante el endpoint de adjuntos de la ODS Ingestion API.
Ver el resumen y los detalles de un pago
Si se conoce el unitOfWorkId del pago, este puede utilizarse para obtener el resumen y también los detalles de una unidad de trabajo.
curl "http://localhost:8080/api/v2/views/summaries/payments/some-unit-of-work-id"
curl "http://localhost:8080/api/v2/views/details/some-unit-of-work-id"Encontrar un objeto ISO 20022 MDS
Puedes encontrar objetos MDS usando la API de búsqueda de nivel inferior. Esta API no admite parámetros de búsqueda para tipos específicos de ISO 20022. Puedes proporcionar el unitOfWorkId si se conoce.
curl "http://localhost:8080/api/v2/all/mds-objects?unitOfWorkId=some-unit-of-work-id"Si conoces el tipo del objeto MDS que estás buscando, utiliza la API de catálogo de objetos MDS, que acepta parámetros de búsqueda específicos por tipo, p. ej., creditorName para una transacción pain.001.
curl "http://localhost:8080/api/v2/catalogue/mds-objects/PAIN_001_CREDIT_TRANSFER_TRANSACTION?creditorName=Emma"Encontrar una solicitud enviada a otro sistema
Si conoces el unitOfWorkId, clientRequestId o primaryAssociation, puedes encontrar todos los mensajes enviados/recibidos como parte de la unidad de trabajo asociada con ese id, usando la API de catálogo de objetos de proceso de message logs.
curl "http://localhost:8080/api/v2/catalogue/process-objects/message-logs?clientRequestId=998436be-4815-4dfd-9c96-77d6d888a365&direction=SENT&messageType=SanctionsRequest"Estructura del módulo
El módulo ods-inquiry está compuesto por varios submódulos.
ods-inquiry-api
Contiene las especificaciones OpenAPI, los tipos de modelo Java generados, los tipos de campos de búsqueda (agrupando campos de búsqueda en un único POJO), la validación (p. ej., campos de búsqueda de fecha de summary y de amount de summary) y la construcción de URIs.
ods-inquiry-spring
Genera el andamiaje de los controladores de Spring a partir de cada especificación, incluye implementaciones de controladores de Spring y configuración de Spring.
Lo mínimo requerido para una aplicación Spring WebFlux que aloje la ODS Inquiry API.
Las implementaciones de los controladores delegan en interfaces en ods-inquiry-port, y la aplicación debe proporcionar una implementación de estas interfaces.
ods-inquiry-port
Contiene interfaces que deben implementarse por la aplicación para admitir los controladores en ods-inquiry-spring.
ods-inquiry-client
Un cliente Java basado en conectores, para uso por proyectos downstream, como implementaciones de cliente que requieran conectividad con ODS Inquiry, y el backend de la GUI, que hace proxy de solicitudes desde la UI del navegador hacia ODS.
ods-inquiry-test-client
Clientes de prueba de ODS Inquiry para cada versión de Inquiry API, pensados para su uso dentro de suites de pruebas e2e. Carece de muchas características importantes que ofrece el cliente basado en conectores.
Es probable que este cliente se marque como obsoleto para su eliminación, o envuelva al cliente basado en conectores y proporcione una interfaz más simple para pruebas.
ods-inquiry-test-data-generators
Genera instancias aleatorias pero válidas de tipos de modelo de ODS Inquiry para su uso en pruebas. A veces necesitas algunos datos válidos, pero en realidad no te importa cuáles sean esos datos.
Se proporcionan generadores para tipos de solicitud, como campos de búsqueda o parámetros de consulta/ruta, y tipos de respuesta, como PaymentSummaryView.
Generación de código
Cada versión de especificación en ods-inquiry-api se procesa con openapi-generator, usando el back-end generador openapi, configurado para producir una única especificación json para cada especificación yaml de entrada.
La generación de código Java se realiza en dos partes: primero los modelos y luego el andamiaje del controlador de Spring.
Modelos
Cada versión de especificación en ods-inquiry-api se procesa con openapi-generator, usando el back-end generador spring, configurado para generar solo modelos, bajo el paquete com.iconsolutions.ipf.ods.inquiry.model.
El resultado de construir este módulo es un jar que contiene especificaciones OpenAPI json para cada versión de Inquiry API y todos los tipos de modelo de Inquiry generados. También incluye algo de código no generado para validaciones de tipos de API, construcción de URIs y agrupaciones de campos de búsqueda.
Este jar puede usarse downstream, proporcionando acceso a los tipos generados y/o para generar código adicional a partir de cada especificación. Este jar se usa en el siguiente paso, generando el andamiaje del controlador de Spring.
Controladores de Spring
El módulo ods-inquiry-spring depende de ods-inquiry-api y usa las especificaciones json contenidas dentro de su jar de salida.
Cada especificación se procesa con openapi-generator, usando el back-end generador spring, configurado para generar solo interfaces, bajo el paquete com.iconsolutions.ipf.ods.inquiry.api.{api-version}.
El resultado de construir este módulo es un jar que contiene el andamiaje de controladores de Spring generado, incluidas las implementaciones de los controladores y la configuración de Spring necesaria para habilitar estos controladores en una aplicación Spring Boot.
Los controladores y las interfaces generadas de ODS Inquiry API Versión 1 están bajo el paquete com.iconsolutions.ipf.ods.inquiry.api. Las versiones posteriores se generan bajo sus propios paquetes, p. ej., com.iconsolutions.ipf.ods.inquiry.api.v2.
|
Consulta la sección Servidor Spring para más información.
Servidor Spring
El módulo ods-inquiry-spring está pensado como un starter que puede incluirse en cualquier aplicación Spring Boot que quiera servir la ODS Inquiry API.
Genera las interfaces de los controladores de Spring e implementa esos controladores.
Los controladores delegan en interfaces de búsqueda, definidas en ods-inquiry-port.
Cuando la aplicación que sirve la ODS Inquiry API se inicia, registrará la versión de lanzamiento de la ODS Inquiry API.
2023-04-12 13:34:03.295 INFO 1 --- [ main] c.i.i.o.inquiry.api.OdsInquiryApiConfig : ODS Inquiry API Version 2.2.34Gestión de errores
Las ODS Inquiry APIs definen un tipo API Error.
Cualquier controlador generado que produzca una jakarta.validation.ConstraintViolationException da como resultado una respuesta http 400, con un payload que contiene información sobre los errores de validación.
Grafos
Los grafos se construyen utilizando detalles de la unidad de trabajo y definiciones de flujos de proceso. La aplicación que sirve la ODS Inquiry API no necesita saber cómo construir grafos, solo cómo devolver detalles de unidad de trabajo y definiciones de flujos de proceso.
Puertos
La aplicación que sirve la ODS Inquiry API utilizando el andamiaje de controladores generado y las implementaciones de controladores proporcionadas debe proporcionar beans para cada uno de los tipos definidos en ods-inquiry-port.
Estas son interfaces de búsqueda que son agnósticas a la persistencia y actualmente están implementadas en la ODS Inquiry Application.
Se pueden usar implementaciones stub para estas interfaces si es necesario, para construir una aplicación ODS Inquiry "lite". Así es como se prueba la funcionalidad del controlador.
Spring Boot Actuator
La versión de lanzamiento de la ODS Inquiry API se añade al endpoint Info de Spring Boot Actuator.
{
"ODS Inquiry API": {
"version": "2.2.34"
}
}Seguridad y configuración
Se espera que los controladores se sirvan desde una aplicación Spring Boot WebFlux. Consulta la documentación de Spring para más información.
La seguridad queda a cargo de la aplicación que implementa, en este caso, la aplicación ODS Inquiry. Como ejemplo, la aplicación ODS Inquiry puede configurarse para requerir un servidor de autenticación OAuth2, y todas las solicitudes (con algunas excepciones en una whitelist) deben estar autenticadas.
Cliente
El cliente se divide en varias Client APIs diferentes; cada una está deshabilitada por defecto y debe habilitarse explícitamente. Por defecto, las Client APIs habilitadas utilizan la especificación de Inquiry API V2. Configurar una versión diferente de Inquiry API habilitará las Client APIs para la versión especificada y deshabilitará todas las demás versiones. Consulta Configurar Client APIs para ver las APIs que pueden habilitarse.
Si tu aplicación ya habilita las V1 Client APIs y quieres seguir usándolas, la versión se DEBE configurar como ods.inquiry.client.version=1. Para más información sobre las V1 Client APIs y el versionado, consulta la visión general del versionado.
|
Inicio rápido
Si conoces la Client API que necesitas, p. ej., necesitas encontrar batch summaries utilizando Inquiry API V2, la configuración mínima requerida, sin autenticación, es la siguiente:
ods.inquiry.client {
version = 2
summaries.enabled = true
http.client {
host = "ods-inquiry-host"
port = 80
}
}Entonces se pone a disposición un bean de Spring del tipo com.iconsolutions.ipf.ods.inquiry.Summaries, y puede inyectarse mediante autowired en tu aplicación Spring.
Para más opciones de configuración, consulta la documentación de Configuración.
Patrones de uso
Todos los métodos de la Client API toman un objeto de solicitud y devuelven un objeto de respuesta. Los objetos de solicitud y respuesta difieren según el tipo de solicitud. Hay dos tipos: búsqueda y obtención por id.
Búsqueda
Las solicitudes de búsqueda aceptan un PageableParameters opcional/nulo.
Si no se proporcionan, se usan los valores por defecto configurados, con la propiedad ods.inquiry.client.pagination.default-page-size.
El tamaño de página por defecto es 50.
Las solicitudes de búsqueda aceptan un objeto de campos de búsqueda opcional, y su tipo depende de la Client API que se use. El objeto de campos de búsqueda no debe ser nulo y, por defecto, es una instancia vacía.
final class BatchSummaryFinder {
private final Summaries summaries;
BatchSummaryFinder(final Summaries summaries) {
this.summaries = summaries;
}
CompletionStage<List<SummaryView>> findCompletedBatchSummaries() {
return summaries.search(SearchSummariesRequest.builder()
.journeyType(JourneyType.BATCH)
.searchFields(SummarySearchFields.builder().globalStatus("COMPLETED").build())
.build())
.thenApply(response -> response.getValue().getItems());
}
CompletionStage<List<SummaryView>> findCompletedBatchSummariesWithPagination() {
return summaries.search(SearchSummariesRequest.builder()
.journeyType(JourneyType.BATCH)
.searchFields(SummarySearchFields.builder().globalStatus("COMPLETED").build())
.pageable(PageableParameters.builder().size(100).build())
.build())
.thenApply(response -> response.getValue().getItems());
}
CompletionStage<List<SummaryView>> findCompletedBatchSummariesWithContexts(final ProcessingContext processingContext,
final SupportingContext supportingContext) {
return summaries.search(SearchSummariesRequest.builder()
.processingContext(processingContext)
.supportingContext(supportingContext)
.journeyType(JourneyType.BATCH)
.searchFields(SummarySearchFields.builder().globalStatus("COMPLETED").build())
.build())
.thenApply(response -> response.getValue().getItems());
}
}Obtener por id
Las solicitudes de obtención por id requieren un id no nulo, y la respuesta (una instancia de com.iconsolutions.ipf.ods.inquiry.GetResponse) es Found o NotFound.
Para una solicitud de obtención por id con respuesta http con estado 404, se devuelve NotFound al llamante del cliente.
final class BatchSummaryGetter {
private final Summaries summaries;
BatchSummaryGetter(final Summaries summaries) {
this.summaries = summaries;
}
CompletionStage<SummaryView> getBatchSummaryOrThrow(final String unitOfWorkId) {
return summaries.get(GetSummaryByUnitOfWorkIdRequest.builder()
.id(unitOfWorkId)
.journeyType(JourneyType.BATCH)
.build())
.thenApply(response -> response.getValue().getItem()); //Throws an exception when there is no item
}
CompletionStage<SummaryView> getBatchSummaryOrLogAndThrow(final String unitOfWorkId) {
return summaries.get(GetSummaryByUnitOfWorkIdRequest.builder()
.id(unitOfWorkId)
.journeyType(JourneyType.BATCH)
.build())
.thenApply(Response::getValue)
.thenApply(response -> {
if (response instanceof SummaryNotFound) {
log.info("Couldn't find batch summary by unitOfWorkId {}, but it really should exist!", unitOfWorkId);
throw new IllegalStateException("Cannot proceed, no batch summary");
}
return response.getItem();
});
}
CompletionStage<SummaryView> getBatchSummaryWithContexts(final String unitOfWorkId,
final ProcessingContext processingContext,
final SupportingContext supportingContext) {
return summaries.get(GetSummaryByUnitOfWorkIdRequest.builder()
.id(unitOfWorkId)
.journeyType(JourneyType.BATCH)
.processingContext(processingContext)
.supportingContext(supportingContext)
.build())
.thenApply(response -> response.getValue().getItem());
}
}Contextos de procesamiento y de soporte
Todos los objetos de solicitud aceptan un processing context opcional y un supporting context opcional. No pueden ser nulos y, si no se proporcionan en la solicitud, por defecto son sus instancias vacías.
El processing context y el supporting context estarán presentes en las entradas de message log, si se registran.
Los campos del processing context se enviarán como http headers.
Registrador de mensajes
El registro de mensajes es condicional a la existencia de un bean de tipo com.iconsolutions.ipf.core.messagelogger.MessageLogger.
Si no existe, entonces se omite el registro de mensajes.
El patrón de solicitud/respuesta descrito arriba significa que las entradas de message log tienen nombres significativos, p. ej., una solicitud/respuesta para un batch summary podría ver dos entradas de message log con los nombres GetSummaryByUnitOfWorkIdRequest y SummaryFound.
Las entradas de message log pueden personalizarse, incluidos sus nombres, con una instancia de com.iconsolutions.ipf.core.connector.MessageLogEntryEnricher.
Si existe un bean de este tipo, se aplicará a todas las entradas de message log de solicitud/respuesta.
Resiliencia
Por defecto, el cliente reintentará las solicitudes http que reciban códigos de estado de respuesta en la lista configurada en ods.inquiry.client.resiliency-settings.retryable-status-codes.
Cualquier otro código de respuesta se trata como un error y la solicitud no se volverá a intentar. Los reintentos se intentan un número configurado de veces y, cuando se agotan, se lanza una excepción.
Las solicitudes de obtención por id que reciben una respuesta 404 no se reintentarán, y se devolverá NotFound al cliente.
Si necesitas reintentar en este caso, p. ej., si esperas que el summary exista eventualmente, tendrás que manejarlo por tu cuenta.
Consulta Configurar resiliencia para opciones de configuración.
Autenticación
OAuth2
Cuando la autenticación OAuth está habilitada, con ods.inquiry.client.security.oauth2.enabled = true, las solicitudes realizadas con la Client API se enriquecerán con un bearer token, que se obtiene de un servidor de autenticación.
Consulta Configurar autenticación OAuth2 para opciones de configuración.
Configuración
La Client API debe configurarse para seleccionar qué versión de Inquiry API usar y qué Client APIs habilitar.
| Property | Default | Notes |
|---|---|---|
|
|
Selecciona para qué versión de Inquiry API crear las Client APIs. Opciones disponibles: |
Las siguientes propiedades de configuración son específicas para las V2 Client APIs. Si quieres usar las V1 Client APIs, la versión se DEBE configurar como ods.inquiry.client.version=1. Para más información sobre las V1 Client APIs y el versionado, consulta la visión general del versionado.
|
Toda la configuración de las Client APIs vive bajo ods.inquiry.client, y todas las propiedades listadas a continuación deben ir con este prefijo.
| Property | Default | Notes |
|---|---|---|
|
|
Habilita el bean |
|
|
Habilita el bean |
|
|
Habilita el bean |
|
|
Habilita el bean |
|
|
Habilita el bean |
|
|
Habilita el bean |
|
|
Habilita el bean |
| Property | Default | Notes |
|---|---|---|
|
|
El host de ODS Inquiry |
|
|
El puerto de ODS Inquiry |
| Property | Default | Notes |
|---|---|---|
|
|
Una duración ISO8601. El tiempo máximo para esperar una respuesta del servidor, tras lo cual se lanza una excepción. |
|
|
El número mínimo de llamadas fallidas antes de abrir el circuit breaker |
|
|
Las solicitudes solo se reintentarán si el código de estado http de la respuesta es uno de estos valores |
|
|
El número máximo de solicitudes a realizar antes de rendirse y lanzar una excepción. |
| Property | Default | Notes |
|---|---|---|
|
|
El tamaño de página a utilizar en las búsquedas cuando no se proporciona programáticamente |
| Property | Default | Notes |
|---|---|---|
|
|
Habilita la autenticación Oauth2 |
|
|
La url desde la cual solicitar un token |
|
|
El host del servidor de autenticación |
|
|
El puerto del servidor de autenticación |
|
|
Con qué frecuencia obtener un token de autenticación |
|
|
Con cuánta antelación al vencimiento del token debe renovarse el token |
|
|
Forma parte de las credenciales necesarias para obtener un token |
|
|
Forma parte de las credenciales necesarias para obtener un token |
|
|
Forma parte de las credenciales necesarias para obtener un token |
|
|
Forma parte de las credenciales necesarias para obtener un token |