REST Service Tutorial
The REST Bookstore sample lets you explore the REST tooling in TIBCO Business Studio. You can import the REST Basic sample into TIBCO Business Studio 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:
Create a new Application
- Click the Create a new BusinessWorks Application icon () in the tool bar.
- Enter books in the Project name text box.
Make sure that the
Create Application Module check box is selected and click
This creates an application called "books" and a module, books.module.
- 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
The REST Basic sample is a pre-created sample application that you can use to familiarize yourself with the various features in the TIBCO Business Studio. In this tutorial, we will use the schema that is bundled with the REST Basic sample for ease of use. Alternatively, you can create a schema and name it Books.xsd.
- In the File Explorer view, open folder.
This opens the REST Basic application in the Project Explorer.
- In the Project Explorer, expand the tibco_bw_sample_binding_rest_basic folder, then expand the Schemas folder under it.
- Copy the Books.xsd schema and paste it into the folder.
Create a REST Service
Now that you have a schema containing some data definition in your project, you can create a REST service. We start by creating a resource definition, in this tutorial, a book. The REST service created in this tutorial will have a POST and a GET operation. The POST operation will create a book and the GET operation will retrieve the book that was created.
Project Explorer, right-click
The REST Service Wizard opens.
- Enter Book in the Resource Name text box.
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.
Browse button next to the
Resource Definition text box to navigate and select a resource from the
This opens the Select Schema Element Declaration dialog with the books.module expanded to expose the Book element in the Books.xsd schema.
- Click the Book element to select it and click OK.
POST check box next to the
Operations field in the REST Service Wizard and click
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.
- 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.
- Click Finish.
postOut icon in the
Process Editor to configure the reply for the POST operation.
The postOut properties display in the Properties view.
- Click the Input tab in the Properties view and expand $post in the Data Source tab completely.
- Click the XPath Expression column next to item to enter the response string that you want the POST operation to return on its success.
- Enter concat('Created ', <drag_name?_from DataSource_tab_here > ). This concatenates the name of the book to your reply string.
Module Descriptors folder in the
Project Explorer and double-click
This opens the Shared Variables configuration view. The shared variable allows you to pick a schema element and create a variable for it.
Click the button that allows you to pick a schema element ().
The Select Schema Element Declaration dialog opens.
- Select Book within the Books.xsd schema and click OK. A shared variable gets created with the default name, moduleSharedVariable.
moduleSharedVariable under the
Name column to rename it to a meaningful name.
The Properties view opens with the General tab displayed.
- Overwrite the Variable Name value in its text box with book.
- Click the Book.bwp tab in the Process Editor to bring it forward.
- Click the Module explorer tab and expand the Module Shared Variables folder.
Drag and drop the book variable to the
Book.bwp process in the
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.
- Click the SetSharedVariable activity icon to open its properties in the Properties view
- 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.
- Click the down arrow next to the book service and then click Create REST Operation.
- Click Browse next to the Resource Definition text box and select the Book element under Books.xsd and click OK.
- 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.
getOut reply to configure it.
The getOut properties opens in the Properties view.
- 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.
Testing the REST Service
Now that you have built a REST service, you must test it before you use it.
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.
- 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.
- Enter lrestdoc in the Console and press Enter. The command returns a URL for the book resource.
- Copy the Discovery URL from the lrestdoc command output, open a browser and paste the URL in its address box.
- You can start by testing the POST operation. Click POST () to expose its details.
Click anywhere in the data description for the book (contained in a light yellow background box) under
The schema opens for editing in the Book text box.
- Set values for the fields, for example, enter an ISBN number, name of the book, and maybe a brief description.
- Click the Try it out! button.
- Test the GET operation. Click the GET () to view its details.
- Click the Try it out! button under GET.