Extending REST API Response Objects

46 Extending REST API Response Objects

Learn how to extend the Oracle Communications Billing Care REST API to return data from BRM storable objects in its response objects.

Topics in this document:

About Enriching REST API Response Objects

You can extend the Billing Care REST API to return complex data, such as all data stored in a BRM storable class, in a JAXB-annotated class. For example, it could return all fields in an /account object or the /profile object linked with an account.

When you extend the BRM REST API to enrich response data, it returns object information in the extension field of response objects in JSON or XML format.

The Billing Care SDK includes a sample response object customization, including a README.txt file explaining the sample, in the SDK_home/samples/ExtensionFields directory where SDK_home is the directory in which you installed the Billing Care SDK. Use this sample when developing your own customizations.

For more information about the Billing Care REST API, see REST API Reference for Billing Care.

Enriching Response Objects

To customize the Billing Care REST API to enrich response objects:

Create an extended Java class to hold your fields in a single object. For example, create a Java class named classNameExtension.java.
Add JAXB annotations that indicate how to translate the fields in your extended Java class.
Create an ObjectFactory Java class that provides the factory method for creating an object of your extended class.
Create a package-info Java class that provides name space information to JAXB.
Create a custom module that extends the default BRM module and overrides its default method.
The custom module should do the following:
- Invoke default methods
- Fetch additional data from the BRM database
- Wrap the additional data in the extended Java class object
- Set the additional data in the extension field
Create a customModule.properties file that specifies the resource group your custom module will override.
For more information, see "About the customModule.properties File".
(Optional) To serialize the data added through your extended Java class in XML format, create JAXBContext with the default package "com.oracle.communications.brm.cc.model" and include the custom package that holds the extended field Java objects. You can do this by using a provider of Jersey that implements the ContextResolver<T> interface.
Package and deploy your SDK as a shared library to SDK_home/libs/BillingCareREST.war using one of the methods described in "Using an Exploded Archive during Customization" or "Packaging and Deploying Customizations".
To support responses in XML format, register your ContextResolver provider with Jersey.

Example: Enriching the Response Object for the Account Module

In the Billing Care REST API, the Get Details for an Account endpoint returns account details such as contact information, billing profiles, registered payment methods, and so on. The following example shows how to enrich the REST API response for the account module so that it returns other fields from the /account database object, such as PIN_FLD_AAC_ACCESS, PIN_FLD_AAC_PACKAGE, and PIN_FLD_AAC_PROMO_CODE.

To extend the response object for the account module so that it retrieves additional fields:

Open the myproject/web/WEB-INF/classes/custom/customModule.properties file in a text editor.
Add the following entry, where company is the company name used in your myproject/src directory.
```
billingcare.rest.account.module=com.company.modules.CustomAccountModule
```
Create a CustomAccountModule.java file in your myproject/src/modules directory, where myproject is your NetBeans IDE project folder containing your Billing Care REST API customizations.

This Java class extends PCMAccountModule and appends all fields from the specified /account object to the extension key in the response object.

For a sample of the override code, see the SDK_home/samples/ExtensionFields/src/java/com/oracle/communications/brm/sdk/modules/CustomAccountModule.java sample class.
Create an AccountExtension.java file that defines the fields to return in the extension object.

For a sample of the code, see the SDK_home/samples/ExtensionFields/src/java/com/oracle/communications/brm/sdk/model/AccountExtension.java sample class.
Create an ObjectFactory Java class that programmatically constructs new instances of the Java representation for XML content. The Java representation of XML content can consist of schema-derived interfaces and classes representing the binding of schema type definitions, element declarations, and model groups.

For a sample of the code, see the SDK_home/samples/ExtensionFields/src/java/com/oracle/communications/brm/sdk/model/ObjectFactory.java sample class.
Create a package-info Java class that provides name space information to the JAXB model class defined in the com.oracle.communications.brm.sdk.model package.

For a sample of the code, see the SDK_home/samples/ExtensionFields/src/java/com/oracle/communications/brm/sdk/model/package-info.java sample class.
If you want the Billing Care REST API to be able to send the response in XML format, create a custom JAXBContextProvider Java class that understands Billing Care-defined default and custom response objects and converts them into XML format.

For a sample of the override code, see the SDK_home/samples/ExtensionFields/src/java/com/oracle/communications/brm/sdk/util/CustomJAXBContextProvider.java sample class.

Package and deploy your customizations using one of the methods described in "Using an Exploded Archive during Customization" or "Packaging and Deploying Customizations".

The following shows a sample deployment plan that links the SDK .war as a shared library to the Billing Care REST API. It also adds a Jersey Provider package to the existing list of packages for identifying resource classes, which is required to support serialization in XML format.

<deployment-plan xmlns="http://xmlns.example.com/weblogic/deployment-plan"
                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                 xsi:schemaLocation="http://xmlns.example.com/weblogic/deployment-plan http://xmlns.example.com/weblogic/deployment-plan/1.0/deployment-plan.xsd"
                 global-variables="false">
    <application-name>BillingCareREST.war</application-name>
    <variable-definition>
        <variable>
            <name>SDKLibraryName</name>
            <value>BillingCareCustomizations</value>
        </variable>
        <variable>
            <name>PROVIDER_PACKAGE</name>
            <value>com.oracle.communications.brm.cc.ws,com.oracle.communications.brm.cc.authentication,com.oracle.communications.brm.sdk.util</value>
        </variable>
    </variable-definition>
    <module-override>
        <module-name>BillingCareREST.war</module-name>
        <module-type>war</module-type>
        <module-descriptor external="true">
            <root-element>weblogic-web-app</root-element>
            <uri>WEB-INF/weblogic.xml</uri>
            <variable-assignment>
                <name>SDKLibraryName</name>
                <xpath>/weblogic-web-app/library-ref/library-name</xpath>
                <operation>add</operation>
            </variable-assignment>
        </module-descriptor>
        <module-descriptor external="true">
            <root-element>web-app</root-element>
            <uri>WEB-INF/web.xml</uri>
            <variable-assignment>
                <name>PROVIDER_PACKAGE</name>
                <xpath>/web-app/servlet[servlet-name='jersey']/init-param[param-name='jersey.config.server.provider.packages']/param-value</xpath>
                <operation>replace</operation>
            </variable-assignment>
        </module-descriptor>
    </module-override>
</deployment-plan>