ODS Inquiry API V1

Descripción general

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

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.

  1. Object Layer Ejemplos

Buscando Por URL

Todos los objetos de proceso

/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

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.

  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

La capa de vista es una capa de negocio centrada en un 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 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.

  1. View Layer Ejemplos

Tipo Ejemplo de URL

Buscar Resúmenes de Pago

/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, que 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 identificador personalizado

Esto se puede lograr utilizando el Alternative Identifiers que han sido asociadas con una unidad de trabajo.

curl " http://localhost:8080/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/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 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/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/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 catálogo de objetos de pago. 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/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 unidad de trabajo asociada con ese id, utilizando el catálogo del objeto de proceso de registros de mensajes. API.

curl " http://localhost:8080/catalogue/process-objects/message-logs?clientRequestId=998436be-4815-4dfd-9c96-77d6d888a365&direction=SENT&messageType=SanctionsRequest"

Estructura del Módulo

The ods-inquiry El módulo está compuesto por varios submódulos.

ods-inquiry-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-inquiry-spring

Genera andamiaje de controlador de Spring a partir de la especificación, incluye implementaciones de controlador de Spring y configuración de Spring.

El mínimo requerido para una aplicación spring webflux, que aloja 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

El original ODS Inquiry cliente, pero utilizado solo dentro del ODS suite de pruebas de extremo a extremo, y más tarde, dentro de las pruebas del servicio ops-gui. 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-inquiry-test-data-generators

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 una única especificación json a partir de la especificación yaml de entrada. Si esta especificación yaml se dividiera en archivos más pequeños, el resultado seguiría siendo una única especificación json.

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

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 en la parte posterior, proporcionando acceso a los tipos generados y/o para generar código adicional a partir de la 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 la especificación json 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 Spring Servidor sección para más información.

Spring Servidor

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

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

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 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. 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 se pone a disposición, y puede ser inyectado automáticamente dentro de su Spring aplicación.

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 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 en el registro de mensajes con los nombres GetBatchSummaryByUnitOfWorkIdRequest, y BatchSummaryFound.

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

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 llamadas fallidas que debe 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 el código de estado http de la respuesta 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. Configurando 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 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.