Skip to main content

API modeling: Implement REST API

API package​

  • For each API Namespace there will be a package generated for example de.knowis.cards.api.credit where:

    1. de.knowis.cards is the base package for the service project.
    2. api is the namespace type.
    3. credit is the namespace prefix.

Provider class & delegate interface​

  • For each path in your API Namespace a provider class will be generated, for example CreditApiCardsProvider where:
  1. credit is the namespace prefix,
  2. cards is the path name "/cards" that this class implements its operations
  3. provider is a postfix for the type of that class.

  • For each modelled operation there will be a method in the provider class where operation logic needs to be implemented.

  • The provider class implements a delegate interface provided by the SDK. For example, below provider implements CreditApiCardsDelegate.

  • This delegate interface contains the default implementation for the operations e.g., returns an example response with "501 - No implementation" HTTP status code.

Schemas & parameters​

  • The Request and Response schemas are provided by the SDK as classes.

  • The operation parameters (path parameters & query parameters) as well as request & response body schemas are typed within the method signature (parameters & return type).

Implementation Example​

  • Below is an example implementation of "/cards/createcard" POST operation.

  • Notice the auto wiring injection of different SDK components such as DomainEntityBuilder , Repository and CardCreateCommand

	package de.knowis.cards.api.credit;

	// Java imports
	import java.math.BigDecimal;
	import java.time.OffsetDateTime;
	import java.util.ArrayList;
	import java.util.Currency;
	import java.util.List;
	import java.util.Optional;
	import org.slf4j.Logger;
	import org.slf4j.LoggerFactory;
	import org.springframework.beans.factory.annotation.Autowired;
	import org.springframework.context.annotation.ComponentScan;
	import org.springframework.http.HttpStatus;
	import org.springframework.http.ResponseEntity;
	import org.springframework.stereotype.Service;

	// Importing from SDK API package
	import de.knowis.cards.sdk.api.credit.api.CreditApiCardsDelegate;
	import de.knowis.cards.sdk.api.credit.model.CardSchema;
	import de.knowis.cards.sdk.api.credit.model.CardSchema.CardTypeEnum;
	import de.knowis.cards.sdk.api.credit.model.SuccessResponseSchema;

	// Importing from SDK domain package
	import de.knowis.cards.domain.cc.command.CardCreateCommand;
	import de.knowis.cards.sdk.domain.cc.entity.Address;
	import de.knowis.cards.sdk.domain.cc.entity.BaseCard;
	import de.knowis.cards.sdk.domain.cc.entity.CardRootEntity;
	import de.knowis.cards.sdk.domain.cc.entity.CreditCard;
	import de.knowis.cards.sdk.domain.cc.entity.Owner;
	import de.knowis.cards.sdk.domain.cc.entity.VisaCard;
	import de.knowis.cards.sdk.domain.cc.error.CreditCardCreationError;
	import de.knowis.cards.sdk.domain.type.Money;

	// importing facades from SDK domain package
	import de.knowis.cards.sdk.domain.facade.DomainEntityBuilder;
	import de.knowis.cards.sdk.domain.facade.Repository;

	@Service
	@ComponentScan(basePackages = "de.knowis.cards.sdk.api.credit.api")
	public class CreditApiCardsProvider implements CreditApiCardsDelegate {

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

		@Autowired
		private CardCreateCommand cardFactoryCommand;

		@Autowired
		private DomainEntityBuilder entityBuilder;

		@Autowired
		private Repository repo;

		@Override
		public ResponseEntity<SuccessResponseSchema> createCard(String cardId, 
		                                                        CardSchema cardSchema) {

			VisaCard visa = this.entityBuilder.getCc().getVisaCard().build();
			visa.setVisaType("American Express");
			visa.setCardNumber(String.valueOf(Math.random()));

			Owner owner = this.entityBuilder.getCc().getOwner().build();
			owner.setAge(20);
			owner.setName("John Doe");
			owner.setId(cardSchema.getCustomerId());

			Address address = this.entityBuilder.getCc().getAddress().build();
			address.setCity("Regensburg");
			address.setPostcode(93047);

			Money currency = new Money();
			currency.setAmount(new BigDecimal(2000));
			currency.setCurrency(Currency.getInstance("EUR"));

			// Creating an input entity that is needed as input to the factory command
			CreditCard ccEntity = this.entityBuilder.getCc().getCreditCard().build();
			ccEntity.setIsActive(true);
			ccEntity.setLimit(cardSchema.getLimit());
			ccEntity.setExpiryDate(OffsetDateTime.now());
			ccEntity.setCreationTimestamp(OffsetDateTime.now());
			ccEntity.setOwner(owner);
			ccEntity.setAddress(address);
			ccEntity.setCardType(visa);
			ccEntity.setCurrency(currency);

			try {
				CardRootEntity rootEntity = cardFactoryCommand.createCreditCard(ccEntity);

				// Prepare and return response
				SuccessResponseSchema body = new SuccessResponseSchema();
				body.setMessage("Successfully created Credit Card Root Entity with id " 
				+ rootEntity.getId());
				return ResponseEntity.status(HttpStatus.OK).body(body);

			} catch (CreditCardCreationError e) {
				// TODO Auto-generated catch block
				log.error("An error occurred while creating a new credit card", e);
				return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).build();
			}
		}

		//.... More methods for oeprations under the same path

Course Implement API Operations