Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Generate Project Stub
This page provides detailed steps for generating projects using the given API specifications.
Prepare Swagger contracts that detail all the APIs that the service is going to expose for external consumption. eGov uses a customised Swagger Codegen tool.
Download the jar file and make sure it is available in the classpath. Use the Swagger Codegen tool to generate client SDKs using these Swagger contracts.
Refer to the following tutorials to understand the creation of Swagger contracts -
OpenAPI 3.0 Tutorial| Swagger Tutorial For Beginners | Design REST API Using Swagger Editor
Use the generic command below to create an API skeleton for any Swagger contract:
The following sequence is used to generate the API skeleton using codegen jar:
Navigate to the folder where you have downloaded the codegen jar.
Execute the following command:
OR
Download the contract available here and save it in a file locally. Run the following command to generate the skeleton code from the contract.
Rename the output
folder to birth-registration.
Import it in Eclipse or VS Code.
Update the spring-boot-starter-parent to 2.2.6-RELEASE in pom.xml.
Perform a maven update once the spring boot version is updated.
Make sure the following dependency is present in the pom.xml. If the version is different, make sure to update it to the version given below:
Put a slash in front of server.contextPath and add this property to the application.properties file which helps request handlers to serve requests -
Add the below external dependencies to pom.xml:
The application.properties file is already populated with default values. Read on to learn how to customise and add extra values for your application (if required).
Kafka topics for the module that need to be added are detailed here.
There are three ways to access services:
a. Run the code locally.
b. Access the service in a DIGIT environment.
c. Access the service locally via port forwarding. This bypasses Zuul's authentication and authorization.
Wherever the localhost is in the URL, the Kubernetes port forwarding has been set up from the development environment to the specified port. In your setup, modify the URLs for the various services depending on whether you are using them from an environment or running them locally or accessing them via port-forwarding.
For example, if no port forwarding has been done, you will have to provide the FQDN of your DIGIT install instead of localhost. Also, without port forwarding, you will have to update the auth tokens in your .aws profile file periodically.
Include all the necessary service host URLs and API endpoints in the "application.properties" file.
This guide specifically references the User, Localisation, HRMS, IDGen, MDMS, and Workflow services that are operational within the DIGIT development environment.
Add the following properties to the application.properties
file.
The following properties must be added for configuring the database and Kafka server. Make sure to use the default values to tune in the Kafka server that can be overwritten during deployment.
Include the following properties in the "application.properties" file to configure the database and Kafka for development purposes once you have completed adding the external dependencies to the "pom.xml" file and reloading the Maven changes.
Append Kafka configurations as per the specific requirements of the DIGIT services. Each module may use different configurations to manage its topics.
The service layer performs business logic on the RequestData and prepares the Response to be returned back to the client.
Follow the steps below to create the service layer.
Create a new package called Service.
Create a new class in this folder by the name BirthRegistrationService.
Annotate the class with @Service annotation.
Add the following content to the class -
NOTE: At this point, your IDE must be showing a lot of errors but do not worry we will add all dependent layers as we progress through this guide and the errors will go away.
Methods in the service layer, upon performing all the business logic, call methods in the repository layer to persist or lookup data i.e. it interacts with the configured data store. For executing the queries, JdbcTemplate class is used. JdbcTemplate takes care of the creation and release of resources such as creating and closing the connection etc. All database operations namely insert, update, search and delete can be performed on the database using methods of JdbcTemplate class.
On DIGIT the create and update operations are handled asynchronously.
The persister service listens on the topic to which service applications are pushed for insertion and updation. Persister then takes care of executing insert and update operations on the database without clogging the application’s threads.
The execution of search queries on the database returns applications as per the search parameters provided by the user.
Define POJOs - The Address object is defined in the common contract (refer to the API spec). Link it to the birth registration table via the registrationId as defined in the DB schema.
Update the Address POJO using the below code:
Define a BirthApplicationSearchCriteria POJO to take care of search requests in the DB.
Create packages - Add thequerybuilder
and rowmapper
packages within the repository folder.
Create a class - by the name of BirthApplicationQueryBuilder in querybuilder
folder and annotate it with @Component
annotation.
Insert the following content in BirthApplicationQueryBuilder class -
Create a class - by the name of BirthApplicationRowMapper within the rowmapper package and annotate it with @Component.
Add the following content to the class.
Create a class - by the name of BirthRegistrationRepository within the repository folder and annotate it with @Repository annotation.
Add the following content to the class.
The repository layer is implemented.
Find the steps to create the and on DIGIT.
All business validation logic should be added to this class. For example, verifying the values against the master data, ensuring non-duplication of data etc.
Follow the steps below to create the validation layer.
Create a package called validators. This ensures the validation logic is separate so that the code is easy to navigate through and readable.
Create a class by the name of BirthApplicationValidator
Annotate the class with @Component annotation and insert the following content in the class -
NOTE: For the sake of simplicity the above-mentioned validations are implemented. Required validations will vary on a case-to-case basis.
This layer enriches the request. System-generated values like id, auditDetails etc. are generated and added to the request. In the case of this module, since the applicant is the parent of a baby and a child cannot be a user of the system directly, both the parents' details are captured in the User table. The user ids of the parents are then enriched in the application.
Follow the steps below to create the enrichment layer.
Create a package under DIGIT by the name of enrichment. This ensures the enrichment code is separate from business logic so that the codebase is easy to navigate through and readable.
Create a class by the name of BirthApplicationEnrichment
Annotate the class with @Component and add the following methods to the class -
NOTE: For the sake of simplicity the above-mentioned enrichment methods are implemented. Required enrichment will vary on a case-to-case basis.
Once PostgreSQL (v10) has been installed and the basic setup is done, we use Flyway to create the tables.
Configure the below properties in the application.properties file to enable flyway migration:
Add the Flyway SQL scripts in the following structure under resources/db/migration/main
:
Add the migration files to the main folder. Follow the specified nomenclature while naming the file. The file name should be in the following format:
Example: V20180920110535__tl_tradelicense_ddl.sql
For this sample service, use the following SQL script to create the required tables.
This section showcases how to create a basic Spring Boot project using an API spec and configure the database.
Follow the steps detailed as detailed below:
The pom.xml typically includes most of the dependencies listed below at project generation time. Review and ensure that all of these dependencies are present. Update the pom.xml in case any are missing.
Models/POJOs of the dependent service can be imported from the digit-core-models library (work on creating the library is ongoing). These models are used to integrate with the dependent services.
These are pre-written libraries which contain tracer support, common models like MDMS, Auth and Auth and the capability to raise custom exceptions.
Once these core models are imported, it is safe to delete the RequestInfo, and ResponseInfo classes from the models folder and use the ones present in the common contract that is imported.
Before starting development, create/update the following classes as given below.
Create RequestInfoWrapper POJO within the Models package -
Update the Applicant POJO with the following content -
Create the BTRConfiguration class within the configuration package. The MainConfiguration class should already exist inside the config package.
The core models are imported.
Implementing the controller layer in Spring
The web/controller layer handles all the incoming REST requests to a service.
The @RequestMapping("/v1") annotation is added on top of the controller class. This contains the version of the API (this becomes a part of the API endpoint URL).
Follow the steps below to set up the request handler in the controller layer.
Make a call to the method in the Service Layer and get the response back from it.
Build the responseInfo.
Build the final response to be returned to the client.
The controller class here contains the below content -
NOTE: At this point, your IDE must be showing a lot of errors but do not worry we will add all dependent layers as we progress through this guide and the errors will go away.
Since the Codegen jar creates the search API with search parameters annotated with @RequestParam rather than taking request parameters as a POJO. For this, we will create a POJO by the name of BirthApplicationSearchCriteria within the Models package. Insert the following content in POJO.
The web layer is now setup.