Generating Claritys REST Builder Project

REST Builder provides Liferay-centric code generation for efficient and controlled custom API development. To begin exploring how to create alternate versions of default object APIs, Clarity would like to construct a REST builder project exposing select details from distributor applications. This enables implementing headless APIs with restricted data scopes, enhancing security and expanding integration options.

In these exercises, you’ll create and deploy a proxy object with REST Builder, limiting the Distributor Application’s default object APIs.

Exercise: Populating Claritys KYC Proxy Project

Here, you’ll use blade and REST Builder to populate the module’s scaffolding and definitions.

Open a terminal and navigate to the /liferay-course-producing-headless-apis/modules/ course workspace folder.
Run this command:
```
blade create -t rest-builder -p com.clarityvisionsolutions.headless.kyc clarity-kyc-proxy
```
This creates a clarity-kyc-proxy REST Builder project including separate api, client, impl, and test folders and configuration files.
Open the /modules/clarity-kyc-proxy/clarity-kyc-proxy-impl/gradle.properties file with a text editor or IDE.
Change the REST Builder plugin version to 1.0.407 and save the file.

NOTE
Updating this plugin version allows REST Builder to generate the right code for later versions of Liferay.
Open the clarity-kyc-proxy-impl/rest-config.yaml file with a text editor or IDE.
Add this code snippet at the bottom:
```
compatibilityVersion: 7
forcePredictableOperationId: true
```
The compatibilityVersion property determines the version of your REST Builder project, while forcePredictableOperationId disables the automatic generation of operationId values.
Save the file.
Open the exercises/rest-exercises/01-rest-openapi.txt file and copy its contents.
Open the /modules/clarity-kyc-proxy/clarity-kyc-proxy-impl/rest-openapi.yaml file with a text editor or IDE.
Add the copied code snippet above the existing text.
REST Builder uses the schema in the components block to create a corresponding Java bean.
In a separate window, open the exercises/rest-exercises/02-kyc-proxy-paths.txt file within your course workspace.
Copy the 02-kyc-proxy-paths.txt file’s contents.

Paste the contents at the bottom of the /modules/clarity-kyc-proxy/clarity-kyc-proxy-impl/rest-openapi.yaml file. Your file should now resemble this structure:

components:
    schemas:
        AbbreviatedDistributorApp:
            properties:
                businessName:
                    type: string
                erc:
                    type: string
                id:
                    format: int64
                    type: integer
                kycStatus:
                    type: string
                taxId:
                    type: string
            type: object
info:
    description: "ClarityKycProxy REST API"
    license:
        name: "Apache 2.0"
        url: "http://www.apache.org/licenses/LICENSE-2.0.html"
    title: "ClarityKycProxy"
    version: v1.0
openapi: 3.0.1
paths:
    /abbreviated-distributor-app/erc/{erc}:
        get:
            parameters:
                - in: path
                  name: erc
...

Save the file.
In a terminal, navigate to the modules/clarity-kyc-proxy/clarity-kyc-proxy-impl folder.
Run this command
```
blade gw buildRest
```

Verify that the process completes successfully:

BUILD SUCCESSFUL in 12s
1 actionable task: 1 executed

Great! You’ve now generated the initial files and structure to add Clarity’s implementation code.

Exercise: Adding Business Logic to Claritys Proxy Object

Here, you’ll add business logic defining Clarity’s project, then build and deploy it to Liferay.

In your course workspace, navigate to the modules/clarity-kyc-proxy/clarity-kyc-proxy-impl/src/main/java/com/clarityvisionsolutions/headless/kyc/internal/resource/v1_0/ folder.
Examine the contents of the BaseAbbreviatedDistributorAppResourceImpl.java file.

The file’s auto-generated content contains the REST endpoints available for the API. This includes the methods, paths, parameter names, and other context details necessary to expose the endpoints.
Examine the contents of the AbbreviatedDistributorAppResourceImpl.java file. This contains the initial scaffolding for your Java class.

NOTE
To expedite this exercise, you'll finalize a pre-configured AbbreviatedDistributorAppResourceImpl.java file containing most of Clarity’s business logic.
Delete the auto-generated AbbreviatedDistributorAppResourceImpl.java file.
In your course workspace, open the /exercises/rest-exercises/03-distributor-kyc-verification.txt and copy its contents.
Open the /exercises/rest-exercises/AbbreviatedDistributorAppResourceImpl.java file with a text editor or IDE.
Paste the copied code snippet into the gap at line 150.
This file's methods implement how the API fetches data, in this case retrieving KYC verification entries associated with specific distributor applications (by leveraging the r_applicationToKYC_c_distributorApplicationId relationship API).
Save the file.
Move the file into the modules/clarity-kyc-proxy/clarity-kyc-proxy-impl/src/main/java/com/clarityvisionsolutions/headless/kyc/internal/resource/v1_0/ folder.

You are now ready to build and deploy your REST Builder module.
In a terminal, navigate to modules/clarity-kyc-proxy/clarity-kyc-proxy-api.
Run this command:
```
blade gw build deploy
```

Verify that the module deploys successfully:

INFO [fileinstall-directory-watcher][BundleStartStopLogger:68] STARTED com.clarityvisionsolutions.headless.kyc.api_1.0.0 [1468]

In your terminal, navigate to modules/clarity-kyc-proxy/clarity-kyc-proxy-impl.
Run this command:
```
blade gw build deploy
```

Verify that the module deploys successfully:

INFO [fileinstall-directory-watcher][BundleStartStopLogger:68] STARTED com.clarityvisionsolutions.headless.kyc.impl_1.0.0 [1470]

Great! You’ve deployed your REST Builder api and impl modules and are ready to explore their included resources.

Exercise: Leveraging Claritys KYC Proxy Object

Sign in as the Clarity Admin user.
- Username: admin@clarityvisionsolutions.com
- Password: learn
Open the Global Menu ([INSERT ICON]), go to the Applications tab, and click Distributor Applications.
Copy the ID for Robert Green for use in later steps.
Navigate to the API Explorer at http://localhost:8080/o/api.
In the upper right, click on the REST Applications drop-down and select c/distributorapplications.
Under the DistributorApplication section, expand the getDistributorApplication endpoint.
Paste Robert’s application ID into the distributorApplicationId parameter and ‘applicationToKYC’ into the nestedFields parameter and click Execute.

Examine the returned information to verify that a 200 was received with a response body containing the full application details.
At the bottom you should have something like:

...
      "kYCVerificationState": {
        "key": "underReview",
        "name": "Under Review"
      },
      "kYCResponse": "",
      "validatedBusinessEIN": ""
    }
  ],
  "annualPurchaseVolume": {
    "key": ""
  },
  "applicantEmailAddress": "robert@eyespyltd.demo",
  "businessName": "Eye Spy Ltd.",
  "businessTaxIDNumber": "32-4953459",
  "applicantName": "Robert Green",
  "businessWebsiteURL": "https://www.eyespyltd.demo",
  "distributionRegions": [],
  "distributionChannels": [],
  "productsOfInterest": [],
  "businessPhoneNumber": "(773) 938-3432"
}

In the upper right, click on the REST Applications drop-down and select clarity-kyc-proxy/v1.0.

This contains the endpoints added with REST Builder for the KYC Proxy object.

NOTE
You may need to refresh the page to view the newly deployed clarity-kyc-proxy/v1.0 REST application.
Under the default section, expand the getAbbreviatedDistributorAppId endpoint.
Paste Robert’s application ID into the id parameter and click Execute.

Examine the returned information to verify that a 200 was received with a response body containing a subset of the application details:

{
  "businessName": "Eye Spy Ltd.",
  "erc": "APPLICATION_EYE_SPY",
  "id": 63261,
  "kycStatus": "Submitted",
  "taxId": "32-4953459"
}

Conclusion

Great! Leveraging REST Builder’s automated population of interfaces, resource classes, and other essential scaffolding, you’ve created a proxy API for an existing object. By defining a simplified data schema with REST endpoints, the produced API exposes only a specific subset of information in distributor applications. With REST Builder, Clarity can accelerate development of producing their custom APIs.

Next, you’ll learn about implementing bridging APIs through microservices.