REST Service Tutorial

The REST Bookstore sample lets you explore the REST tooling in TIBCO Business Studio for BusinessWorks. You can import the REST Basic sample into TIBCO Business Studio for BusinessWorks through File Explorer and examine the project and the solution implemented by it.

The REST Bookstore sample uses the RESTful service to add, and retrieve books from a Bookstore. This sample uses two REST methods: POST and GET.

Here's an overview of the steps involved to create and test a REST service:

    Procedure
  1. Create a new Application
  2. Obtain a Schema for the REST Service.
  3. Create a REST Service.
  4. Testing the REST Service

Create a new Application

You start by creating a new application in TIBCO Business Studio for BusinessWorks that will contain the service.

    Procedure
  1. Click the Create a new BusinessWorks Application icon () in the tool bar.
  2. Enter books in the Project name text box.
  3. Make sure that the Create Application Module check box is selected and click Finish.
    This creates an application called "books" and a module, books.module.
  4. Expand the books.module folder completely and delete the Process.bwp process, the default process, which got created along with the books module. You will create a new module later in this tutorial.

Obtain a Schema for the REST Service

    Procedure
  1. In the File Explorer view, open binding > rest > Basic folder.
  2. Double-click tibco_bw_sample_binding_rest_basic.zip.
    This opens the REST Basic application in the Project Explorer.
  3. In the Project Explorer, expand the tibco_bw_sample_binding_rest_basic folder, then expand the Schemas folder under it.
  4. Copy the Books.xsd schema and paste it into the books.module > Schemas folder.

Create a REST Service

    Procedure
  1. In the Project Explorer, right-click books.module > Processes and select New > BusinessWorks REST Resource.
    The REST Service Wizard window is displayed.

  2. Enter a resource name in the Resource Name text box.
  3. Select the Single radio button for Type of Resource, since you are creating one book.
    If you were creating multiple books, you would need to select the Collection radio button.
  4. Click the Browse button next to the Resource Definition text box to navigate and select a resource from the Books.xsd schema.
    This opens the Select Schema Element Declaration dialog with the books.module expanded to expose the Book element in the Books.xsd schema.
  5. Click the Book element to select it and click OK.

    Next, you create a POST operation for the service.

  6. Select the POST check box next to the Operations field in the REST Service Wizard and click Next.
    By default, the POST operation is configured with a request to add a book and output a response with the book details.

    We will configure the response to output a message instead of the book details.

  7. Click the drop-down menu for Response and select String to replace Book. You will configure this response string later in this tutorial. This string will be output as a response to the POST request if the request is successful in creating the book.

  8. Click Finish.
    This creates a process called Book.bwp which contains a POST operation and a reply which the user will receive when he/she executes the POST operation. You will configure this reply in the next step.

  9. Click the postOut icon in the Process Editor to configure the reply for the POST operation.
    The postOut properties display in the Properties view.
  10. Click the Input tab in the Properties view and expand $post in the Data Source tab completely.
  11. Click the XPath Expression column next to item to enter the response string that you want the POST operation to return on its success.
  12. Enter concat('Created ', <drag_name?_from DataSource_tab_here > ). This concatenates the name of the book to your reply string.

    On success, the POST operation will return a response, Created <name_of_the_book>.

    Now you must save the book that you created, so that it can be reused at a later time. Create a shared variable for it and save it in a shared variable.

  13. Expand the Module Descriptors folder in the Project Explorer and double-click Shared Variable.
    This opens the Shared Variables configuration view. The shared variable allows you to pick a schema element and create a variable for it.
  14. Click the button that allows you to pick a schema element ().
    The Select Schema Element Declaration dialog opens.
  15. Select Book within the Books.xsd schema and click OK. A shared variable gets created with the default name, moduleSharedVariable.

  16. Click moduleSharedVariable under the Name column to rename it to a meaningful name.
    The Properties view opens with the General tab displayed.
  17. Overwrite the Variable Name value in its text box with book.

  18. Click the Book.bwp tab in the Process Editor to bring it forward.

  19. Click the Module explorer tab and expand the Module Shared Variables folder.

  20. Drag and drop the book variable to the Book.bwp process in the Process Editor.
    When prompted, select Create a SetSharedVariable activity to associate the book with the shared variable you created. This shared variable will be stored in the module. Connect the SetSharedVariable activity to the postOut activity, which allows the reply from the POST operation to read the shared variable.

  21. Click the SetSharedVariable activity icon to open its properties in the Properties view
  22. Expand the $post node and drag the Book item on to the Book variable under the SetSharedVariable-input and select Make a copy of "Book" when prompted and click Finish.
    This allows a copy of the book that you post to reside in the shared variable.

    Now that you have created a book and stored it in a shared variable, you can create another REST operation, GET, to access the book.

  23. Click the down arrow next to the book service and then click Create REST Operation.

    This opens the REST Service Wizard and with the GET operation selected by default.

  24. Click Browse next to the Resource Definition text box and select the Book element under Books.xsd and click OK.
    Click Finish in the wizard to create the get operation and a reply (getOut) for the operation.

  25. Create a GetSharedVariable activity by dragging the book variable from the Module Shared Variables in the Module explorer to the get operation in the Process Editor. Connect the GetSharedVariable activity to the getOut reply.
    This allows the book that is stored in the Shared Variables to be returned by the getOut reply.

  26. Click the getOut reply to configure it.
    The getOut properties opens in the Properties view.
  27. Drag and drop $GetSharedVariable from the DataSource tab on to Book under the getResponse item. Select Make a copy of "Book" when prompted and click Finish.

    You have now configured the response to the GET operation which will return the book created by the POST operation.

Testing the REST Service

    Procedure
  1. In the Project Explorer, expand the Resources folder fully and double-click Book.httpConnResource to configure the HTTP Connector resource that was created when you created the application.
    The HTTP Connector properties page opens in the Project Editor. By default, the HTTP Connector resource is set to run on your localhost and port 8080. You can configure a different port here if the 8080 port is already in use.
  2. Run the application by right-clicking anywhere in the Book.bwp tab in the Process Editor and selecting Run BusinessWorks Applications. By default, it will run locally and create a REST service that has two operations, POST and GET. You can see the progress of the Run command in the Console view.

    When the command completes you will see a message such as Started BW Application [books:1.0]

  3. Enter lrestdoc in the Console and press Enter. The command returns a URL for the book resource.

  4. Copy the Discovery URL from the lrestdoc command output, open a browser and paste the URL in its address box.
    The Swagger page for the books resource opens. Click the Book link to expose the operations it supports.

  5. You can start by testing the POST operation. Click POST () to expose its details.
  6. Click anywhere in the data description for the book (contained in a light yellow background box) under Model Schema.
    The schema opens for editing in the Book text box.
  7. Set values for the fields, for example, enter an ISBN number, name of the book, and maybe a brief description.

  8. Click the Try it out! button.
    You will see a reply saying Created Great Expectations.

  9. Test the GET operation. Click the GET () to view its details.
  10. Click the Try it out! button under GET.
    It returns the book that you just posted.