ODS Inquiry API
| Este documento describe la Versión 2 de la ODS Inquiry API. Para más información sobre la Consulta API versioning, 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
El object layer permite buscar datos en bruto de bajo nivel ODS data type s. 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 |
|---|---|
Todo process objects |
|
Todo custom objetos |
|
Todo MDS objetos |
|
Todo PDS objetos |
|
Catalogue Layer
El catalogue layer es un tipo fuertemente tipado 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 system event process object, 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
El view layer es un enfoque empresarial de alto nivel API. Los datos se construyen típicamente a partir de los crudos. ODS data type s en el momento de la ingestión, aunque también puede ser construido a partir de la 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 del 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 Custom Identificador
Esto se puede lograr utilizando el Alternative Identifiers que han sido asociados con un unit of work.
curl " http://localhost:8080/api/v2/views/summaries/payments?alternativeIdentifierName=SomeClientIdentifier&alternativeIdentifierValue=some-clients-custom-identifier-value"El alternative identifier debe estar asociado con el unit of work 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 un unit of work.
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. Esto 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 objeto catalogue API, que acepta parámetros de búsqueda específicos del 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 unit of work asociado con ese id, utilizando el message logs process object catalogue 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-consulta-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-consulta-primavera
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-consulta-puerto
Contiene interfaces que deben ser implementadas por la aplicación para soportar los controladores en ods-inquiry-spring.
ods-consulta-cliente
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-consulta-prueba-cliente
ODS Inquiry pruebe clientes para cada Consulta Api versión, destinada para su uso dentro de e2e test suites. Carece de muchas características importantes que ofrece el cliente basado en conectores.
Este cliente probablemente será descontinuado para su eliminación, o se envolverá el cliente basado en conectores y se proporcionará una interfaz más simple para las pruebas.
ods-generadores-de-datos-de-consulta
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 qué datos son.
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 la especificación en ods-inquiry-api es procesado por openapi-generator, utilizando el openapi generador de back-end, configurado para producir un único json especificación para cada entrada yaml especificación.
Java code generation se realiza en dos partes, primero los modelos y luego el andamiaje del controlador de primavera.
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 Consulta Api versión, 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 jar se utiliza en el siguiente paso, generando el andamiaje del controlador de Spring.
Controladores de Spring
El ods-inquiry-spring el módulo depende de ods-inquiry-api, y utiliza el json especificaciones 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 Servidor Spring sección para más información.
Servidor Spring
El ods-inquiry-spring el módulo está destinado como un inicio, que puede ser incluido en cualquier Spring Boot aplicación que busca servir al ODS Inquiry API.
Genera las interfaces de controladores de Spring 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 un 400 http respuesta, con una carga útil que contiene información sobre los errores de validación.
Gráficas
Los gráficos se construyen utilizando unit of work details, y process flow definitions. La aplicación que sirve al ODS Inquiry API no necesita saber cómo construir gráficos, solo cómo devolver unit of work details, y process flow definitions.
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 están implementadas en el ODS Inquiry Aplicación.
Stub las 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
El 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 Aplicación WebFlux. Vea el docs.spring.io/spring-boot/docs/2. 7. 7/reference/html/[Primavera] 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 deshabilitar 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 versioning, vea 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 está entonces disponible y puede ser inyectado automáticamente dentro de su aplicación Spring.
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. Hay 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 http respuesta 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 el message log entradas, si se registran.
Los campos del contexto de procesamiento se enviarán como http encabezados.
Message Logger
Message log ging es condicional a un bean de tipo `com.iconsolutions.ipf.core.messagelogger. MessageLogger`. Si no existe, entonces message log ging se omite.
El patrón de solicitud/respuesta descrito anteriormente significa que el message log las entradas tienen nombres significativos, por ejemplo, una solicitud/respuesta para un resumen de lote podría ver dos message log entradas con los nombres GetSummaryByUnitOfWorkIdRequest, y SummaryFound.
Message log las entradas 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 solicitudes/respuestas message log entradas.
Resiliencia
Por defecto, el cliente volverá a intentar http solicitudes que reciben 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 es devuelto al cliente.
Si necesita reintentar en este caso, por ejemplo, espera que el resumen a eventually existe, 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 versioning, vea 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 failed llamadas a realizar antes de abrir el interruptor de circuito |
|
|
Las solicitudes solo se volverán a intentar si la respuesta http el código de estado es uno de estos valores |
|
|
El número máximo de solicitudes que se pueden realizar antes de rendirse y lanzar una excepción. |
-
Configurando 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 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. |