ODS Inquiry API

Descripción general

El ODS Inquiry API expone datos capturados por ODS, y se divide en varias capas de abstracción.

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.

Esto API devuelve objetos que generalmente se corresponden uno a uno con los tipos almacenados.

  1. Object Layer Ejemplos

Buscando URL

Todo process objects

/all/process-objects

Todo custom objetos

/all/custom-objects

Todo MDS objetos

/all/mds-objects

Todo PDS objetos

/all/pds-objects

Todos los objetos de pago (Obsoleto)

/all/payment-objects

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.

  1. Catalogue Layer Ejemplos

Tipo Ejemplo de URL

ISO 20022 MDS Objetos

/catalogue/mds-objects/PAIN_001_CREDIT_TRANSFER_TRANSACTION? creditorAgentBIC=SOMEBIC01

Message Logs

/catalogue/process-objects/message-logs?direction=SENT&unitOfWork=some-unit-of-work-id

System Events

/catalogue/process-objects/system-events?type-FUNCTIONAL&level=INFO&source=some-application

Process Flow Events

/catalogue/process-objects/process-flow-events?unitOfWorkId=some-unit-of-work-id

Process Flow Definitions

/catalogue/process-objects/process-flow-definitions?name=SomeFlowName

Objetos de Pago ISO 20022 (Obsoleto)

/catalogue/payment-objects/PAIN_001_CREDIT_TRANSFER_TRANSACTION? creditorAgentBIC=SOMEBIC01

View Layer

El view layer es un enfoque empresarial de alto nivel API. Los datos se construyen típicamente a partir de la información bruta. 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 para el tipo que se está buscando.

  1. View Layer Ejemplos

Tipo Ejemplo de URL

Buscar Resúmenes de Pagos

/views/summaries/payment

Obtenga el Resumen de Pago por unitOfWorkId

/views/summaries/payment/some-unit-of-work-id

Obtener Unit Of Work Details

/views/details/some-unit-of-work-id

Obtener Unit Of Work Graphs

/views/process-flow-graphs/some-unit-of-work-id

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, el cual admite un gran número de parámetros de búsqueda.

curl " http://localhost:8080/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 asociadas con un unit of work.

curl " http://localhost:8080/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/views/summaries/payments/some-unit-of-work-id"
curl " http://localhost:8080/views/details/some-unit-of-work-id"

Encuentre un ISO 20022 MDS Objeto

Puede encontrar MDS objetos utilizando la búsqueda de bajo nivel 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/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, p. ej. creditorName para un pain. 001 transacción.

curl " http://localhost:8080/catalogue/mds-objects/PAIN_001_CREDIT_TRANSFER_TRANSACTION? creditorName=Emma"

Encuentre un Objeto de Pago ISO 20022 (Obsoleto)

Puede encontrar objetos de pago 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/all/payment-objects?unitOfWorkId=some-unit-of-work-id"

Si conoce el tipo de objeto de pago que está buscando, utilice el objeto de pago.catalogue API, que acepta parámetros de búsqueda específicos del tipo, p. ej. creditorName para un pain. 001 transacción.

curl " http://localhost:8080/catalogue/payment-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/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 especificación, generada 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 la especificación, incluye implementaciones de controlador de Spring y configuración de Spring.

Lo 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

El original ODS Inquiry cliente, pero utilizado solo dentro del ODS end-to-end test-suite, y más tarde, dentro de las pruebas del ops-gui-service. 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

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 de la entrada yaml especificación. Si esto yaml la especificación se dividiría en archivos más pequeños, el resultado sigue siendo un único json especificación.

Java code generation se realiza en dos partes, primero los modelos y luego el andamiaje del controlador de primavera.

Modelos

La 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 un único json OpenAPI especificació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 la 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 especificación contenida dentro de su archivo jar de salida. La 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.

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.

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 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.

2023-04-12 13:34:03. 295  INFO 1 --- [           main] c.i.i.o.inquiry.api. OdsInquiryApiConfig: ODS Inquiry API Version 2. 2. 34

Manejo de Errores

El ODS Inquiry API define una API Tipo de error. Cualquier controlador generado que produzca un javax.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 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 se añade la versión 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. Ver [ods-inquiry-client-configure-apis] para el APIs que se puede habilitar.

Inicio Rápido

Si conoce al cliente API usted requiere, por ejemplo, usted necesita encontrar resúmenes de lotes, la configuración mínima requerida, sin autenticación, es la siguiente:

ods.inquiry.client {
  batch-summaries.enabled = true
  http.client {
    host = "ods-inquiry-host"
    port = 80
  }
}

A Spring bean de tipo com.iconsolutions.ipf.ods.inquiry. BatchSummaries está entonces disponible y puede ser inyectado automáticamente dentro de su aplicación Spring.

Para más opciones de configuración, consulte el [ods-inquiry-client-configure-apis] lista, y el Configuración secció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 valor 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 obtener 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 GetBatchSummaryByUnitOfWorkIdRequest, y BatchSummaryFound.

 Message log 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 se devuelve 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

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.

  1. Configurar Cliente APIs

Propiedad Predeterminado Notas

payment-summaries.enabled

false

Habilite el PaymentSummaries bean cuando se establece en true

recall-summaries.enabled

false

Habilite el RecallSummaries bean cuando se establece en true

batch-summaries.enabled

false

Habilite el BatchSummaries bean cuando se establece en true

bulk-summaries.enabled

false

Habilite el BulkSummaries bean cuando se establece en true

details.enabled

false

Habilite el Details bean cuando se establece en true

process-flow-graphs.enabled

false

Habilite el ProcessFlowGraphs bean cuando se establece en true

process-objects.enabled

false

Habilite el ProcessObjects bean cuando se establece en true

custom-objects.enabled

false

Habilite el CustomObjects bean cuando se establece en true

payment-objects.enabled

false

Habilite el PaymentObjects bean cuando se establece en true

mds-objects.enabled

false

Habilite el MdsObjects bean cuando se establece en true

pds-objects.enabled

false

Habilite el PdsObjects bean cuando se establece en true

  1. Configurando el HTTP Cliente

Propiedad Predeterminado Notas

http.client.host

localhost

El ODS Inquiry anfitrión

http.client.port

8080

El ODS Inquiry puerto

  1. Configuración de la Resiliencia

Propiedad Predeterminado Notas

call-timeout

5s

An ISO8601 duración. El tiempo máximo de espera para una respuesta del servidor, momento en el cual se lanza una excepción.

resiliency-settings.minimum-number-of-calls

100

El número mínimo de failed llamadas a realizar antes de abrir el interruptor de circuito

resiliency-settings.max-attempts

[500, 502, 503, 504]

Las solicitudes solo se volverán a intentar si la respuesta http el código de estado es uno de estos valores

resiliency-settings.retryable-status-codes

5

El número máximo de solicitudes que se pueden realizar antes de rendirse y lanzar una excepción.

  1. Configuración de la Paginación

Propiedad Predeterminado Notas

pagination.default-page-size

50

El tamaño de página a utilizar en las búsquedas cuando no se proporciona programáticamente.

  1. Configuración de la autenticación OAuth2

Propiedad Predeterminado Notas

security.oauth2.enabled

false

Habilite la autenticación Oauth2

security.oauth2.http.client.endpoint-url

/auth/realms/demo/protocol/openid-connect/token

La URL desde la cual debe solicitar un token

security.oauth2.http.client.host

localhost

El host del servidor de autenticación

security.oauth2.http.client.host

8080

El puerto del servidor de autenticación

security.oauth2.refresh-interval-duration

7h

Con qué frecuencia debe obtener un token de autenticación

security.oauth2.ttl-before-refresh-duration

5m

¿Con cuánta antelación antes de que el token expire debe ser refrescado el token?

security.oauth2.grant-type

grant type

Forma parte de las credenciales requeridas para obtener un token.

security.oauth2.client-id

client id

Forma parte de las credenciales requeridas para obtener un token.

security.oauth2.client-secret

client secret

Forma parte de las credenciales requeridas para obtener un token.

security.oauth2.scope

scope

Forma parte de las credenciales requeridas para obtener un token.