ODS Inquiry API V2
| Este documento describe la Versión 2 de la ODS Inquiry API. Para más información sobre la Consulta API versionado, y la documentación de la Versión 1, consulte el visión general de versionado. |
Descripción general
El ODS Inquiry API expone datos capturados por ODS, y se divide en varias capas de abstracción. Para el completo OpenAPI especificación, consulte ODS Inquiry V2 Specification.
Object Layer
La capa de objetos permite buscar datos en bruto de bajo nivel ODS tipos de datos. Este API no tiene conocimiento de las implementaciones más específicas de estos tipos, y por lo tanto la búsqueda es limitada. Si necesita buscar un objeto de datos con atributos específicos de tipo, consulte la Catalogue APIs.
Este API devuelve objetos que generalmente se corresponden uno a uno con los tipos almacenados.
-
Object Layer Ejemplos
| Buscando Por | URL |
|---|---|
Todos los objetos de proceso |
|
Todo custom objetos |
|
Todo MDS objetos |
|
Todo PDS objetos |
|
Catalogue Layer
La capa de catálogo es un tipo fuertemente definido API, que permite parámetros de búsqueda específicos por tipo, por ejemplo, buscar un pain.001 transacción de transferencia de crédito MDS objeto, por creditorAgentBic, o buscando un objeto de proceso de evento del sistema, por nivel, fuente y tipo.
-
Catalogue Layer Ejemplos
| Tipo | Ejemplo de URL |
|---|---|
ISO 20022 MDS Objetos |
|
Message Logs |
|
System Events |
|
Process Flow Events |
|
Process Flow Definitions |
|
View Layer
La capa de vista es una centrada en los negocios de alto nivel. API. Los datos se construyen típicamente a partir de los crudos ODS tipos de datos en el momento de la ingestión, aunque también puede ser construido a partir del ODS datos en el momento de la consulta.
Los parámetros de búsqueda para estos tipos son específicos al tipo que se está buscando.
-
View Layer Ejemplos
| Tipo | Ejemplo de URL |
|---|---|
Buscar Resúmenes de Pagos |
|
Obtenga el Resumen de Pago por unitOfWorkId |
|
Obtener Unit Of Work Details |
|
Obtener Unit Of Work Graphs |
|
API Casos de Uso
Encontrar un Pago
La forma más rápida de buscar un pago es a través del punto final de resumen de pagos, 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"Encuentre un Pago por un Identificador Personalizado
Esto se puede lograr utilizando el Alternative Identifiers que han sido asociadas con una unidad de trabajo.
curl " http://localhost:8080/api/v2/views/summaries/payments?alternativeIdentifierName=SomeClientIdentifier&alternativeIdentifierValue=some-clients-custom-identifier-value"El identificador alternativo debe estar asociado con la unidad de trabajo de antemano, ya sea a través de IPF Processing Data, o enviado por separado a través del ODS Ingestion API attachments endpoint.
Consulte el Resumen y Detalles de Pago
Si el pago es unitOfWorkId se conoce, esto puede ser utilizado 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"Encuentre un ISO 20022 MDS Objeto
Puede encontrar MDS objetos utilizando la búsqueda de nivel inferior API. Este API no admite parámetros de búsqueda para tipos específicos de ISO 20022. Puede proporcionar el unitOfWorkId si se conoce.
curl " http://localhost:8080/api/v2/all/mds-objects?unitOfWorkId=some-unit-of-work-id"Si usted conoce el tipo de la MDS objeto que está buscando, utilice el MDS catálogo de objetos API, que acepta parámetros de búsqueda específicos de tipo, por ejemplo,creditorName para un pain.001 transacción.
curl " http://localhost:8080/api/v2/catalogue/mds-objects/PAIN_001_CREDIT_TRANSFER_TRANSACTION? creditorName=Emma"Encuentre una Solicitud Enviada a Otro Sistema
Si usted conoce el unitOfWorkId,clientRequestId, o primaryAssociation Puede encontrar todos los mensajes enviados/recibidos como parte de la unidad de trabajo asociada con ese id, utilizando el catálogo del objeto de proceso de registros de mensajes. API.
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 ods-inquiry El módulo está compuesto por varios submódulos.
ods-inquiry-api
Contiene el OpenAPI especificaciones, generadas Java tipos de modelo, tipos de campo de búsqueda (agrupando campos de búsqueda en un único POJO), validación (por ejemplo, campo de búsqueda de fecha de resumen y campo de búsqueda de monto de resumen), y construcción de URI.
ods-inquiry-spring
Genera andamiaje de controlador de Spring a partir de cada especificación, incluye implementaciones de controlador de Spring y configuración de Spring.
El mínimo requerido para una aplicación spring webflux, que aloje el ODS Inquiry API.
Las implementaciones del controlador 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 ser implementadas por la aplicación para soportar los controladores en ods-inquiry-spring.
ods-inquiry-client
Un conector basado en Java cliente, para uso por proyectos posteriores, tales como implementaciones de clientes que requieren ODS Inquiry conectividad, y el back-end de la GUI, que actúa como intermediario para las solicitudes de la interfaz de usuario basada en el navegador, a ODS.
ods-inquiry-test-client
ODS InquiryPruebe los clientes para cada versión de la API de Consulta, destinados para su uso dentro de las suites de pruebas e2e. Carece de muchas características importantes que ofrece el cliente basado en conectores.
Este cliente probablemente será desaprobado para su eliminación, o envolverá el cliente basado en conectores y proporcionará una interfaz más simple para las pruebas.
generadores-de-datos-de-prueba-ods-inquiry
Genera instancias aleatorias, pero válidas de ODS Inquiry tipos de modelo para utilizar en las pruebas. A veces necesita algunos datos válidos, pero en realidad no le importa cuáles son 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.
Code Generation
Cada versión de especificación en ods-inquiry-api es procesado por openapi-generator, utilizando el openapi generador de back-end, configurado para producir una única especificación json para cada especificación yaml de entrada.
Java code generation 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 es procesado por openapi-generator, utilizando el spring generador de back-end, configurado para generar modelos únicamente, bajo el paquete com.iconsolutions.ipf.ods.inquiry.model.
El resultado de construir este módulo es un archivo jar que contiene json. OpenAPI especificaciones para cada versión de la API de Consulta y todos los tipos de modelo de Consulta generados. También incluye algún código no generado para API validaciones de tipo, construcción de URI y agrupaciones de campos de búsqueda.
Este jar puede ser utilizado a continuación, proporcionando acceso a los tipos generados y/o para generar código adicional a partir de cada especificación. Este frasco se utiliza en el siguiente paso, generando el Spring andamiaje del controlador.
Spring Controladores
El ods-inquiry-spring el módulo depende de ods-inquiry-api, y utiliza las especificaciones json contenidas dentro de su archivo jar de salida.
Cada especificación es procesada por openapi-generator, utilizando el spring generador de back-end, configurado para generar interfaces únicamente, bajo el paquete com.iconsolutions.ipf.ods.inquiry.api.{api-version}.
El resultado de construir este módulo es un archivo jar que contiene la estructura generada del controlador de Spring, incluyendo las implementaciones del controlador y la configuración de Spring necesaria para habilitar estos controladores de Spring en un Spring Boot aplicación.
ODS Inquiry API Los controladores de la versión 1 y las interfaces generadas se encuentran bajo el paquete com.iconsolutions.ipf.ods.inquiry.api. Las versiones posteriores se generan bajo sus propios paquetes, por ejemplo.com.iconsolutions.ipf.ods.inquiry.api.v2.
|
Vea el Spring Servidor sección para más información.
Spring Servidor
El ods-inquiry-spring el módulo está destinado a ser un punto de partida, que puede ser incluido en cualquier Spring Boot aplicación que busca servir al ODS Inquiry API.
Genera el Spring interfaces de controlador y implementa esos controladores.
Los controladores delegan en las interfaces de búsqueda, definidas en ods-inquiry-port.
Cuando la aplicación que sirve al ODS Inquiry API al iniciar, registrará el ODS Inquiry API versión de lanzamiento.
2023-04-12 13:34:03.295 INFO 1 --- [ main] c.i.i.o.inquiry.api.OdsInquiryApiConfig : ODS Inquiry API Version 2.2.34Manejo de Errores
ODS Inquiry APIs define una API Tipo de error.
Cualquier controlador generado que produzca un jakarta.validation. ConstraintViolationException, resulta en una respuesta http 400, con una carga útil que contiene información sobre los errores de validación.
Gráficas
Los gráficos se construyen utilizando detalles de la unidad de trabajo y definiciones del flujo de proceso. La aplicación que sirve al ODS Inquiry API no necesita saber cómo construir gráficos, solo cómo devolver detalles de la unidad de trabajo y definiciones del flujo de proceso.
Puertos
La aplicación que sirve al ODS Inquiry API utilizando el andamiaje de controlador generado y las implementaciones de controlador 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 implementadas en el ODS Inquiry Aplicación.
Stublas implementaciones pueden sustituir estas interfaces si es necesario, para construir un "lite" ODS Inquiry aplicación. Así es como se prueba la funcionalidad del controlador.
Spring Boot Actuador
The ODS Inquiry API la versión de lanzamiento se añade a la Spring Boot Endpoint de información del actuador.
{
"ODS Inquiry API": {
"version": "2.2.34"
}
}Seguridad y Configuración
Se espera que los controladores sean alimentados desde un Spring Boot WebFlux aplicación. Vea el Spring documentación para más información.
La seguridad queda a cargo de la aplicación que la implementa, en este caso, el ODS Inquiry aplicación. Como ejemplo, el ODS Inquiry La aplicación puede ser configurada para requerir un servidor de autenticación OAuth2, y todas las solicitudes (con algunas excepciones en la lista blanca) deben ser autenticadas.
Cliente
El cliente se divide en varios clientes diferentes. APIs, cada uno está deshabilitado por defecto y debe ser habilitado explícitamente. Por defecto, el cliente habilitado APIs utilice la Consulta API Especificación V2. Configuración de una Consulta diferente API la versión permitirá al cliente APIs para la versión especificada y desactive todas las demás versiones. Ver [ods-inquiry-client-configure-apis] para el APIs que se puede habilitar.
Si su aplicación ya habilita el Cliente V1 APIs, y usted desea continuar utilizando el Cliente V1 APIs, la versión DEBE ser configurada como ods.inquiry.client.version=1. Para más información sobre el Cliente V1 APIs y versionado, consulte el visión general de versionado.
|
Inicio Rápido
Si conoce al cliente API usted requiere, por ejemplo, usted necesita encontrar resúmenes de lotes utilizando Consulta 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
}
}A Spring bean de tipo com.iconsolutions.ipf.ods.inquiry. Summaries se pone a disposición, y puede ser autoconectado dentro de su Spring aplicación.
Para más opciones de configuración, consulte el Configuración documentación.
Patrones de Uso
Todos los clientes API Los métodos toman un objeto de solicitud y devuelven un objeto de respuesta. Los objetos de solicitud y respuesta difieren según el tipo de solicitud. Existen dos tipos, búsqueda y obtención por id.
Buscar
Las solicitudes de búsqueda aceptan un parámetro opcional/nulo.PageableParameters.
Si no se proporcionan, se utilizan valores predeterminados configurados, con la propiedad ods.inquiry.client.pagination.default-page-size.
El tamaño de página predeterminado es 50.
Las solicitudes de búsqueda aceptan un objeto de campos de búsqueda opcional, y su tipo depende del cliente. API siendo utilizado. El objeto de los campos de búsqueda no debe ser nulo y se establece por defecto en 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 ya sea Found, o NotFound.
Para una solicitud de obtención por ID con respuesta HTTP con estado 404,NotFound es devuelto al llamador 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());
}
}Procesamiento y Contextos de Soporte
Todos los objetos de solicitud aceptan un contexto de procesamiento opcional y un contexto de soporte opcional. No pueden ser nulos y se establecen en sus instancias vacías si no se proporcionan en la solicitud.
El contexto de procesamiento, y el contexto de apoyo, estarán presentes en las entradas del registro de mensajes, si se registran.
Los campos del contexto de procesamiento se enviarán como encabezados http.
Message Logger
El registro de mensajes es condicional a 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 anteriormente significa que las entradas del registro de mensajes tienen nombres significativos, por ejemplo, una solicitud/respuesta para un resumen de lote podría ver dos entradas del registro de mensajes con los nombres GetSummaryByUnitOfWorkIdRequest, y SummaryFound.
Las entradas del registro de mensajes pueden ser customized, incluyendo sus nombres, con una instancia de com.iconsolutions.ipf.core.connector. MessageLogEntryEnricher.
Si un bean de este tipo está presente, entonces se aplicará a todas las entradas del registro de mensajes de solicitud/respuesta.
Resiliencia
Por defecto, el cliente volverá a intentar 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 considera un error, y la solicitud no se volverá a intentar. Se intentan reintentos un número configurado de veces, y cuando estos se agotan, se lanza una excepción.
Obtenga solicitudes por id recibiendo un 404 la respuesta no se volverá a intentar, y un NotFound se devuelve al cliente.
Si necesita reintentar en este caso, por ejemplo, si espera que el resumen eventualmente exista, entonces deberá manejar esto usted mismo.
Ver [ods-inquiry-client-configure-resiliency] para opciones de configuración.
Autenticación
OAuth2
Cuando la autenticación OAuth está habilitada, con ods.inquiry.client.security.oauth2.enabled = true, solicitudes realizadas utilizando el cliente API se enriquecerá con un token portador, que se obtiene de un servidor de autenticación.
Ver [ods-inquiry-client-configure-oauth2] para opciones de configuración.
Configuración
El cliente API necesita ser configurado para seleccionar qué Consulta API versión a utilizar, y qué cliente APIs para habilitar.
-
Configurar Cliente APIs
| Propiedad | Predeterminado | Notas |
|---|---|---|
|
|
Seleccione qué Consulta API versión para crear cliente APIs para. Opciones disponibles:`1` y |
Las siguientes propiedades de configuración son específicas para el Cliente V2.APIs. Si desea utilizar el Cliente V1 APIs, la versión DEBE ser configurada como ods.inquiry.client.version=1. Para más información sobre el Cliente V1 APIs y versionado, consulte el visión general de versionado.
|
Todos los clientes API la configuración se encuentra bajo ods.inquiry.client, y todas las propiedades enumeradas a continuación deben estar precedidas por esto.
-
Configurar Cliente APIs
| Propiedad | Predeterminado | Notas |
|---|---|---|
|
|
Habilite el |
|
|
Habilite el |
|
|
Habilite el |
|
|
Habilite el |
|
|
Habilite el |
|
|
Habilite el |
|
|
Habilite el |
-
Configurando el HTTP Cliente
| Propiedad | Predeterminado | Notas |
|---|---|---|
|
|
El ODS Inquiry anfitrión |
|
|
El ODS Inquiry puerto |
-
Configuración de la Resiliencia
| Propiedad | Predeterminado | Notas |
|---|---|---|
|
|
An ISO8601 duración. El tiempo máximo de espera para una respuesta del servidor, momento en el cual se lanza una excepción. |
|
|
El número mínimo de llamadas fallidas que se deben realizar antes de abrir el interruptor de circuito. |
|
|
Las solicitudes solo se volverán a intentar si el código de estado http de la respuesta es uno de estos valores. |
|
|
El número máximo de solicitudes que se pueden realizar antes de rendirse y lanzar una excepción. |
-
Configuración de la Paginación
| Propiedad | Predeterminado | Notas |
|---|---|---|
|
|
El tamaño de página a utilizar en las búsquedas cuando no se proporciona programáticamente. |
-
Configuración de la autenticación OAuth2
| Propiedad | Predeterminado | Notas |
|---|---|---|
|
|
Habilite la autenticación Oauth2 |
|
|
La URL desde la cual se debe solicitar un token |
|
|
El host del servidor de autenticación |
|
|
El puerto del servidor de autenticación |
|
|
Con qué frecuencia debe obtener un token de autenticación |
|
|
¿Con cuánta antelación antes de que el token expire debe ser refrescado el token? |
|
|
Forma parte de las credenciales requeridas para obtener un token. |
|
|
Forma parte de las credenciales requeridas para obtener un token. |
|
|
Forma parte de las credenciales requeridas para obtener un token. |
|
|
Forma parte de las credenciales requeridas para obtener un token. |