Skip to main content

Integration modelling: Implement Rest Integration

Entity Builders​

If Integration modelling is enabled, the SDK provides Builders for entities. These builders can be easily used to construct entities using the builder pattern which allow to write readable, understandable code to set up complex objects.

Namespace entity builders​

  • Each namespace has its own entity builder grouping usually prefixed with the namespace acronym.

  • Namespace with prefix cards would get a CardsEntityBuilder class that can be injected and groups all the entity builders in that domain.

For example:


// Import Entity Builder of namespace prefixed by cc
import de.cards.sdk.domain.cc.facade;

// Declaring Entity Builder for namespace cards
@Autowired
protected CardsEntityBuilder cardsEntityBuilder;

// Using Entity Builder
AmexCard amexCard = cardsEntityBuilder.getAmexCard().build();

Integration entity builder​

Besides Namespace entity builders, the SDK also provides an IntegrationEntityBuilder which groups all namespace entity builders of integration namespaces.

💡tip

You can inject the IntegrationEntityBuilder into your implementation code as shown below. Additionally, in the implementation of integration services, it is available automatically as entityBuilder, derived from the base class.


// Import IntegrationEntityBuilder
import de.cards.sdk.integration.facade.IntegrationEntityBuilder;

// Declare & Inject Integration Entity Builder
@Autowired
private IntegrationEntityBuilder integrationEntityBuilder;
      
// Use Integrationn Entity Builder to create an entity that was modelled in 
// integration namespace with prefix: cards
AmexCard amexCard = this.integrationEntityBuilder.getCards().getAmexCard().build();

// use default entityBuilder derived from the base class
// Create a visa card entity that exists in an integration namespace prefixed by cards.
VisaCard visaCard = entityBuilder.getCards().getVisaCard().build();
💡tip

Please also see Domain entity builder.

Implement REST Integration Services​

Service Base​

  • For each REST integration service there will be an abstract class Service Base generated in the SDK.

  • The Service Base provides access to the integration entity builder and the event producer.

  • The Service Base contains one abstract method named execute.

  • This execute method needs to be implemented in the generated implementation file for the service.

Input & output entity​

  • Service execute method will take a modelled Input Entity as a parameter.

  • Service execute method will return a modelled Output Entity as a return type.

Business errors​

  • If service is modelled with Business Errors, it will be added as throws declaration to service execute method.

Injecting an API provider​

  • It's very common to inject generated API Providers for an API Dependency and use them to integrate with external / internal APIs.
    //... other imports

    // Import CreditIscoreApiIScore API provider from *iscore* integration namespace
    import de.knowis.cards.operations.sdk.integration.iscore.iscorecheck.provider.CreditIscoreApiIScore;

    // Declare integration API provider
    private final CreditIscoreApiIScore iscoreApi;
        
    // Adjust your generated integration service implementation constructor 
    // to inject Iscore integration namespace API provider
    public CheckIscoreService(IntegrationEntityBuilder entityBuilder, EventProducerService eventProducer CreditIscoreApiIScore iscoreApi) {
        super(entityBuilder, eventProducer);

        this.iscoreApi = iscoreApi;
    }

Implementation example​

Example of CheckIscore service implementation file.

    //... imports

    // Import CreditIscoreApiIScore api provider from *iscore* integration namespace
    import de.knowis.cards.operations.sdk.integration.iscore.iscorecheck.provider.CreditIscoreApiIScore;

    // Import IscoreResult from Iscore integration namespace API provider
    import de.knowis.cards.operations.sdk.integration.iscore.iscorecheck.model.IscoreResult;

    @Service
    public class CheckIscoreService extends CheckIscoreServiceBase {

        private static Logger log = LoggerFactory.getLogger(CheckIscoreService.class);

        private final CreditIscoreApiIScore iscoreApi;
        
        // Adjust your generated integration service constructor to inject Iscore API provider
        public CheckIscoreService(IntegrationEntityBuilder entityBuilder,
                                  EventProducerService eventProducer, 
                                  CreditIscoreApiIScore iscoreApi) {
            super(entityBuilder, eventProducer);

            this.iscoreApi = iscoreApi;
        }

        // Example of a service implementation logic
        @NewSpan
        @Override
        public IscoreCheck execute(Account accountDetails) throws IscoreCheckError {

        log.info("CheckIscoreService.execute()");

        try {
            ResponseEntity<IscoreResult> iscoreResult = 
            iscoreApi.checkIscore(accountDetails.getAccountNumer);

        } catch(Exception e) {
            String errorMessage = String.format("Iscore check failed %s" ,e.getMessage());
            throw new IscoreCheckError(errorMessage);
        }
    
        IscoreCheck iscoreCheck = this.entityBuilder.getIscore().getIscoreCheck().build();
        iscoreCheck.setScore(iscoreResult.getScore());
        iscoreCheck.setScoreComment(iscoreResult.getScoreComment());

        return iscoreCheck;
        }

Trigger REST Integration Services​

The generated SDK provides various classes, which allow to easily trigger integration services from other places in the service.

Directly use service class​

The simplest way of triggering another service is to directly inject and use the generated service class.

In the example below, it is shown how to inject the service class and execute it using an input entity.

// Importing the service class from namespace cards
import de.cards.integration.cards.service.LoadCardDetails;

// Declare and Inject class of service LoadCardDetails
@Autowired
private LoadCardDetails loadCardDetails;

// Calling LoadCardDetails and passing cardDetailsInputEntiy as service input entity
CardDetails cardDetailsEntity = loadCardDetails.execute(cardDetailsInputEntiy);

Namespace service facade​

For each integration namespace, a facade is generated where all the services defined in the namespace are grouped together. The facades can be injected and used as shown in the example below.

In the below example, CardsService is a namespace facade that group all the services of the namespaces where card is the namespace acronym.

// Importing cc namespace service facade that provides access to all of its services.
import de.cards.sdk.integration.cards.facade.CardsService;

// Declare and Inject Service Facades
@Autowired
private CardsService cardsService;

// Use namespace service facade to call LoadCardDetails service within that namespace

// Calling LoadCardDetails and passing cardDetailsInputEntiy as service input entity
CardDetails cardDetailsEntity = cardsService.loadCardDetails(cardDetailsInputEntiy);

General integration service facade​

Besides Namespace Service facades, the SDK also provides a Service facade which holds all services in integration namespaces.


// Import IntegrationService
import de.cards.sdk.integration.facade.IntegrationService;

// Declare & Inject Integration Service Facade
@Autowired
private IntegrationService integrationService;

// Calling LoadCardDetails service that belongs to namespace prefixed by cards.
CardDetails cardDetailsEntity = integrationService.getCards().loadCardDetails(cardDetailsInputEntiy);

Course Integration Namespaces