Deep Dive : TIBCO BusinessWorks REST features – Part 1

In this series of blog posts I will be covering some of the well known (as well as unknown) features of REST Support for TIBCO ActiveMatrix BusinessWorks 6.x as well as TIBCO BusinessWorks Container Edition. Most of these features are common for both products and if there are any subtle differences are called out for each feature. I will be introducing each feature in batches of 3.

Auto Generating Swagger (OAS)

So one of the first ones is probably the most well known feature. If you run an application BW6 (and BWCE) with a REST binding, the product will automatically generate Swagger 2.0 compliant api definition. When you run the project in Studio you can easily get this via the OSGI command lrestdoc

If you run the application in an AppNode it will follow the same URL scheme:
http://<hostname>:7777/<applicationName>
If you run this application in BWCE the swagger documentation is available at :
http://<hostname>:<httpConnectorSharedResourcePort>/swagger

The following properties can be configured for Swagger support

• bw.rest.docApi.reverseProxy.hostName – Typically used if you would like API Docs to be generated using a loadbalancer host or IP address instead of the machine IP where the application is running
• bw.rest.docApi.reverseProxy.port – Typically used if you would like API Docs to be generated using a loadbalancer Port number instead of the machine port where the application is running
• bw.rest.docApi.hostName – Can be used to specify the hostname where the ‘Swagger Server’ runs. E.g. You could use 0.0.0.0 if you want the server to bind to hostname as well as localhost
• bw.rest.docApi.port – The port number used by the Swagger Server. Default value is 7777
• BW_DISABLE_SWAGGER_UI – To be set if you do not want the Swagger server to start up on a particular appnode or container.

Support for Partial Responses

BW supports what we call partial responses i.e. ability for users to dictate which fields they would like in a response. This is done by adding a query parameter named ‘fields’. For example, In the Bookstore example lets add a query parameter on the /books endpoint called fields like in the screenshot below:

In Swagger we can now suggest which output parameters we would like to see. For example, the default JSON Response is :

{
   "Book" : [
      {
         "authorName" : "Vivek Ranadive",
         "description" : "How Real Time Businesses Anticipate Customer Needs, Create Opportunities, and Beat the Competition",
         "price" : 50,
         "vintage" : false,
         "isbn" : "0071450149",
         "signed" : true,
         "name" : "The Power to Predict",
         "releaseDate" : "2006-01-26+05:30"
      },
      {
         "authorName" : "Paul Coelho",
         "description" : "Every few decades a book is published that changes the lives of its readers forever. The Alchemist is such a book",
         "price" : 50,
         "vintage" : true,
         "signed" : true,
         "isbn" : "0061122416",
         "releaseDate" : "2006-04-25+05:30",
         "name" : "The Alchemist"
      }

Now let’s use the query parameter to define what response fields we need. In this case let’s ask for name, description and authorName. Check the screenshot to see the magic happen:

Why is this important? This gives the creator of the service to easily host just a single endpoint which returns all the fields and the consumer of the service to only ask for fields which they need.

Ignore Additional Fields

This one is relatively new and might still be unknown. Let’s say you write a process which invokes a REST service using the REST Reference Binding. Everything is working fine, but after some time the service invocations start failing. The reason – The service is now sending back additional fields in the response and validation errors start popping up. Now in the olden times you would need to open your project up, add the new elements in the schema, mark them optional and then regenerate the EAR. Quite tedious!
The solution- A new checkbox which allows the user to ignore any additional fields that are not part of the schema that the user has defined. This means that if you select this checkbox, you are good for life as long as you don’t need to use the new fields. Using it with the partial response feature, you could easily define a smaller schema and only parse and use a subset of the actual output. That is definitely a time (and bandwidth saver)

So those are the three features in Part 1. In Part 2 we’ll cover 3 other features:

• Creating Schemas from SQL and JSON Payloads
• Exception Handling and Status Codes
• Importing a Swagger definition which is split into multiple files