A REST API module generates the artifacts related to a particular API such Events, Provider interfaces and so on.

api module workflow.drawio
API Module workflow

Follow these steps to build Rhino support for each REST API.

Step 1: Create an API module

The first step is to use the SDK tool sdkadm to create an API module from a module-pack. The REST RA framework provides a set of module-packs for creating API modules.

Tip
Use the sdkadm list-modules command to list available module-packs.
> list-modules +module-pack
Listing modules based on module tags.

Modules matching all of the following tags will be listed: module-pack

opencloud#clientonly-rest-api#rest-api-framework/1.0.0;1.0.0.0 1
opencloud#clientserver-rest-api#rest-api-framework/1.0.0;1.0.0.0 2
opencloud#raname-unified-rest-ra#rest-api-framework/1.0.0;1.0.0.0 3
opencloud#serveronly-rest-api#rest-api-framework/1.0.0;1.0.0.0 4

  1. module-pack: a resource adaptor type that supports the client role of a REST API

  2. module-pack: a resource adaptor type that supports both the client and server roles of a REST API

  3. module-pack: a unified REST resource adaptor that can support one or more REST APIs

  4. module-pack: a resource adaptor type that supports the server role of a REST API

1

Create an API module

Create an API module with the sdkadm create-module command. For example, to create a server API module for the PingPong API:

sdkadm create-module
> create-module pingpong-rest-api opencloud#serveronly-rest-api#rest-api-framework/1.0.0;1.0.0.0
Extracting '.../rest-api-framework/1.0.0/module-packs/serveronly-rest-api-module-pack-1.0.0.0.zip' to '~/work/unified-rest-ra-sdk/pingpong-rest-api'.

Command line invocation did not contain enough rename arguments to rename all modules.
To specify rename arguments on the command line, include <oldvalue>:<newvalue> pairs as additional arguments.
Missing values will now be prompted for interactively.

sdkadm will prompt you for more details related to the new API (explained in the following steps).

2

The name of the top-level module

The top level module is group module, that encapsulates sub-modules for each of the constituent parts for your API.

The suggested value is the directory name passed in the create-module command. Press return to use the recommended value.

sdkadm top level module
Please enter a name for the top level module, usually this will match the name of the directory for the new module
Rename top level module 'serveronly-rest-api' to [pingpong-rest-api]:

Please enter names for the following sub-module(s) in the module-pack

The following questions prompt you for the names to use for each sub-module and for properties related to your new API. Don’t accept the default values; you need to provide suitable values for each of these questions.

3

The name of the resource adaptor type module

The resource adaptor type module generates a Resource Adaptor Type component that can be deployed in Rhino TAS - Telecom Application Server and is used by a REST resource adaptor.

resource adaptor type module
Rename module 'serveronly-api-server' to [serveronly-api-server]: pingpong-api-server

4

The name of the API plugin module

The API plugin module generates a library component that is used by a REST resource adaptor to implement your REST API. The API plugin library gets deployed in Rhino TAS - Telecom Application Server.

plugin module
Rename module 'serveronly-api-server-plugin' to [serveronly-api-server-plugin]: pingpong-api-server-plugin

5

The name of the API module

The API module contains the OpenAPI specification and an associated configuration file that defines your API. The other API modules depend on this API module.

API module
Rename module 'serveronly-api' to [serveronly-api]: pingpong-api

6

The name of the sbbpart module

The sbb-part module generates a Java library that contains an abstract superclass you can use to write an SBB Part component that can be used in a Rhino TAS - Telecom Application Server based application. The generated class includes all the event handlers and slee annotations you need for your own sbb-part.

SBBPart module
Rename module 'serveronly-api-server-sbbpart' to [serveronly-api-server-sbbpart]: pingpong-api-server-sbbpart

7

The short name of the API, and the root java package for all generated java

API properties
Short name for this API. [pingpong_rest_api]: pingpong
Base Java package for generated API classes. [com.exampleco.openapi.pingpong]:

The create-module command will then create your new REST API module.

create-module for the Ping Ping API finishes …​
Renaming ivy modules and updating dependencies.

Renaming symbolic property references in source files.
Checking "deps.properties" for missing values.

Done. New module(s) should now be available at: ~/work/unified-rest-ra-sdk/pingpong-rest-api
>

The generated modules for the PingPong API is:

pingpong API directory structure
~/work/unified-rest-ra-sdk$ ls -la pingpong-rest-api/
total 32
drwxr-xr-x  10 fwuser  staff   320  2 Nov 16:24 .
drwxr-xr-x@ 16 fwuser  staff   512  2 Nov 16:23 ..
-rw-r--r--   1 fwuser  staff    54  2 Nov 16:24 .sdk.root
-rw-r--r--   1 fwuser  staff   432  2 Nov 16:24 build.xml
-rw-r--r--   1 fwuser  staff  1604  2 Nov 16:24 ivy.xml
-rw-r--r--   1 fwuser  staff   183  2 Nov 16:24 module.properties
drwxr-xr-x   7 fwuser  staff   224  2 Nov 16:24 pingpong-api 1
drwxr-xr-x   7 fwuser  staff   224  2 Nov 16:24 pingpong-api-server 2
drwxr-xr-x   8 fwuser  staff   256  2 Nov 16:24 pingpong-api-server-plugin 3
drwxr-xr-x   7 fwuser  staff   224  2 Nov 16:24 pingpong-api-server-sbbpart 4

  1. This sub-module holds the API specification and a properties file. The other sub-modules have an ivy dependency on this module.

  2. Generates a RA type that includes events, provider interfaces and so on for an RA type that can be deployed in Rhino

  3. Generates a library component the Unified REST RA uses to load and drive the API

  4. Generates a Jar that contains a super-class that developers can extend to create an sbb-part for their application. The generated super-class includes all event handlers and slee-annotations required to deploy such an sbb-part in Rhino.

Tip

Learn about SBB Parts. Learn about JAIN SLEE (JSR 240).

Step 2: Configure the API module

You only need to edit the following files in the API submodule.

  • the API specification file

  • the API properties file

All the required Java components and deployment descriptors are generated by the REST RA framework toolchain.

The generated REST API module contain a default (trivial) api.yaml that is a placeholder for your REST API specification. The generated properties file contains suitable default property values. For example the PingPong (server) API properties are:

PingPong api.properties
# properties related to the package structure of the API

api.shortname = pingpong

# optional - a required license function
api.requiredLicenseFunction =

# packages
api.invokerPackage = com.exampleco.openapi.pingpong
api.apiPackage =     com.exampleco.openapi.pingpong.api
api.modelPackage =   com.exampleco.openapi.pingpong.model
api.implPackage =    com.exampleco.openapi.pingpong.impl

# artifact names
api.server.ratype.artifactname  = pingpong-api-server
api.server.plugin.artifactname  = pingpong-api-server-plugin
api.server.sbbpart.artifactname = pingpong-api-server-sbbpart

Copy your own openapi specification into the API Module and customizes the API properties to specify information like package names, or artifact names and versions. The finished API Module can be checked into source control.

Note
Optional License for your API

One of the properties in the api.properties file (api.requiredLicenseFunction) is the name of a required Metaswitch license key for the API. The unified REST resource adaptor will check for the presence of a license with this license key on resource adaptor activation.

Using this property is optional. The default value means the API does not require a license.
Tip Review the PingPong API openapi specification document.

Step 3: Build the API module

When the API Module builds, it generates code using OpenAPI SLEE Generator and publishes artifacts including:

  • A SLEE RA Type deployable unit, which defines the application (SBB) interface to the REST RA.

  • A REST RA Plugin deployable unit, which provides the implementation used by the REST RA when sending or receiving HTTP messages.

  • A superclass jar for SBB Parts that may be used as a starting point for developing services.

At this point the developer can depend on these generated artifacts in their project, and write service code using the classes and methods from the generated RA Types.

To actually deploy the service and interact with real REST API clients or servers, the developer must also create their REST RA using a REST RA Module.

Tip The developer repeats steps one, two and three as they update their API specification.
Previous page Next page