ODS Inquiry API V3
| ODS Inquiry API V3 está en beta y se espera que alcance la disponibilidad general en 2025. 4, donde permanecerá estable. |
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 V3 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 la cruda 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 que admite un gran número de parámetros de búsqueda.
curl " http://localhost:8080/api/v3/views/summaries?journeyType=PAYMENT&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/v3/views/summaries?journeyType=PAYMENT&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/v3/views/summaries/some-unit-of-work-id"
curl " http://localhost:8080/api/v3/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/v3/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 del tipo, por ejemplo, creditorName para un pain. 001 transacción.
curl " http://localhost:8080/api/v3/catalogue/mds-objects/PAIN_001_CREDIT_TRANSFER_TRANSACTION? creditorName=Emma"Encuentre una Solicitud Enviada a Otro Sistema
Si usted conoce el unitOfWorkId or clientRequestId 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/v3/catalogue/process-objects/message-logs?clientRequestId=998436be-4815-4dfd-9c96-77d6d888a365&direction=SENT&messageType=SanctionsRequest"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 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.v3.
|
Vea el Servidor Spring sección para más información.
Servidor Spring
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 las interfaces de controladores de Spring e implementa esos controladores.
Los controladores delegan en las interfaces de búsqueda, definidas en ods-inquiry-port.
Manejo de Errores
ODS Inquiry APIs defina 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 están 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.
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.
Inicio Rápido
Si conoce al cliente API usted requiere, por ejemplo, usted necesita encontrar resúmenes de lotes utilizando Consulta API V3, la configuración mínima requerida, sin autenticación, es la siguiente:
ods.inquiry.client {
summaries.enabled = true
http.client {
host = "ods-inquiry-host"
port = 80
}
}Una primavera bean de tipo com.iconsolutions.ipf.ods.inquiry.v3. 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.v3. 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 en el 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 es devuelto 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
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 |
|---|---|---|
|
|
Un 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 debe 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 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. |