Generieke REST-connector

Inleiding

Via de generieke REST-connector is het mogelijk om te communiceren met eender welke webapplicatie of omgeving die gedefinieerd zit binnen je applicatie eigenschappen. Opgelet: gezien het om een generieke connector gaat, is er geen enkele ingebouwde business logica. Deze logica moet je volledig zelf op maat ontwikkelen, hetzij als expressie of script binnen een BPMN-proces, hetzij als extensie binnen je applicatie.

Setup

Maven dependency

Voeg de Generic REST connector maven dependency toe aan de juiste pom.xml files.

<dependency>
    <groupId>com.skryv.connectors</groupId>
    <artifactId>rest-connector</artifactId>
</dependency>

Voeg onderstaande instellingen toe aan de applicatie eigenschappen. Elk van deze eigenschappen moet je specifiek per omgeving gaan instellen.

Applicatie eigenschappen

Je stelt de generieke REST-connector in via skryv.connectors.rest.api.environments.{omgeving}, waarbij {omgeving} de naam is die je zelf kiest voor die specifieke omgeving (bijvoorbeeld BRUGGE of PUBLIC_API). Je herhaalt onderstaande eigenschappen voor elke omgeving die je wil aanspreken.

Eigenschap	Default	Beschrijving
RestConnector
skryv.connectors.rest.api.environments.{omgeving}.base-url		De basis-URL van de externe webapplicatie of -omgeving.
skryv.connectors.rest.api.environments.{omgeving}.timeout	30s	De timeout voor calls naar deze omgeving. Ondersteunt Duration-syntax, bijvoorbeeld 10s of 1m.
skryv.connectors.rest.api.environments.{omgeving}.client-id		De client-ID voor OAuth2 client-credentials authenticatie. Laat samen met client-secret en token-url leeg als deze omgeving geen authenticatie vereist.
skryv.connectors.rest.api.environments.{omgeving}.client-secret		Het client-secret voor OAuth2 client-credentials authenticatie.
skryv.connectors.rest.api.environments.{omgeving}.token-url		De URL waar de connector het OAuth2-token ophaalt.
skryv.connectors.rest.api.environments.{omgeving}.audience		De audience die meegestuurd wordt in de tokenaanvraag. Vereist bij sommige identity providers, bijvoorbeeld Auth0.
skryv.connectors.rest.api.environments.{omgeving}.scope		De scope die meegestuurd wordt in de tokenaanvraag. Vereist bij sommige identity providers, bijvoorbeeld Azure AD/Entra ID.

Resilience4J

De connector gebruikt één Resilience4j-instantie met de naam `rest-connector`. Je configureert die eveneens in je applicatie eigenschappen.

Architectuur

RestConnector (@Service, Camunda-resolvable)
  +-- RestTechnicalConnector (Resilience4j-decorated)
        +-- RestTemplate (one per environment, built at startup)
              +-- ClientHttpRequestInterceptor (injects Bearer token when credentials configured)
              |     +-- RestConnectorTokenFetcher -> ClientCredentialsService (cached tokens)
              +-- FallbackTextHttpMessageConverter (text-based non-JSON responses: plain text, XML, YAML, CSV)

Services en functies

De connector is een generieke service die je zowel vanuit een BPMN-proces als vanuit Java-code kan aanspreken.

Get-functie

Workflow expressie

${restConnector.get(env, path)}

Input parameters

Output

resultVariable bevat het object dat de call teruggeeft. JSON-antwoorden worden gedeserialiseerd naar een Map of List; niet-JSON-antwoorden (text/plain, XML, YAML, ...) komen terug als ruwe String. Camunda slaat het resultaat op als procesvariabele.

Post-functie

Workflow expressie

${restConnector.post(env, path, body)}

Input parameters

Output

resultVariable bevat het object dat de call teruggeeft, op dezelfde manier als bij de Get-functie.

Gebruik vanuit Java-code

Bouw je een eigen connector op maat, dan spreek je de RestConnector ook typed aan vanuit Java:

@RequiredArgsConstructor
@Service
public class MyCustomConnector {

    private final RestConnector restConnector;

    public DossierResponse getDossier(String id) {
        return restConnector.get("lapp", "/api/v1/dossiers/" + id, DossierResponse.class);
    }

    public DossierResponse createDossier(CreateDossierRequest request) {
        return restConnector.post("lapp", "/api/v1/dossiers", request, DossierResponse.class);
    }
}

Beschikbare methodes: