Quick Start Guide

The purpose of this guide is to get you started on creating and invoking a data service using WSO2 Data Services Server (WSO2 DSS) as quickly as possible. See the following topics for details:

Introduction and key concepts

WSO2 Data Services Server provides a convenient web service interface for data stored in various datasources. That is, data that is stored in various datasources can be decoupled from the infrastructure where it is stored and exposed to external clients as a data service. Datasources such as relational databases, CSV files, Microsoft Excel files and google spread sheets can be easily service enabled using WSO2 DSS.

Creating a sample database with data

Let us now create a sample MySQL database and add some data. For the purpose of this demonstration, we will create a simple database with one table. 

1. Download and install MySQL using Homebrew. 

2. Open a terminal and execute the following command to start your MySQL database:

   mysql.server start

3. Access the MySQL prompt by giving the user name and password. By default the user name is 'root' and the password is blank.

   mysql -u root -p

4. Create the sample database named employeedb using the following command: 

   create database employeedb;

5. Open the employeedb database you just created using the following command:

   use employeedb;

6.  Create one table in the database using the following command:

   create table employee(id VARCHAR(10) NOT NULL PRIMARY KEY, name VARCHAR(100), address VARCHAR(100));

   This command will create the following table in the database:
   

7. Insert employee data into the employee table as follows:

   1. The first employee:

      insert into employee values('01','john','Boston');

   2. The second employee:

      insert into employee values('02','Micheal','Dallas');

   3. The third employee:

      insert into employee values('03','richard','Chicago');

8. You can see the data that you have added to the employee table of the employeedb database by executing the following command:

   SELECT * FROM employee

   The result will be as follow:
   

You now have a MySQL database with employee data. 

Installing and setting up WSO2 DSS

Follow the steps given below to download WSO2 DSS.

1. Download WSO2 DSS from here.
2. Extract the ZIP file to a location in your computer. This location will be referred to as <DSS_HOME> from hereon.
3. Download the JDBC driver for MySQL from here and copy it to your <DSS_HOME>/repository/components/lib directory.

Before you start the server, the following prerequisites should be in place:

1. Ensure that you have JDK 7/8 installed in your computer.
2. You must set your JAVA_HOME environment variable to point to the directory where the Java Development Kit (JDK) is installed on the computer.

WSO2 DSS is now installed with the required settings.

Creating your first data service

We are now ready to start creating the first data service. We will be using the employeedb database that we created previously and we will expose the data through our data service. Follow the steps given below.

1. Open a terminal and navigate to the <DSS_HOME>/bin directory and execute the DSS startup script using one of the following commands:

   • On Windows: wso2server.bat
   • On Linux: sh wso2server.sh

2. When the product is started, the URL of the Management Console will be shown in the terminal as follows:

    

   INFO {org.wso2.carbon.ui.internal.CarbonUIServiceComponent} -  Mgt Console URL  : https://10.100.5.65:9443/carbon/

3. Copy this URL to your browser to open the Management Console.

4. Log in to the management console using the default administrator credentials: admin/admin.

Step 1: Creating the data service

1. In the left navigator, go to the Main tab and click Services -> Add -> Data Service -> Create. This will open the Create Data Service wizard.

2. In the Data Service Name field, enter 'MyFirstDS' as the name. Leave the default settings of all other options.
   

3. Click Next. This will take you to the page for adding datasources.

Step 2: Adding new datasources

1. Click Add New Datasource. You can now specify the datasource details. 
   1. In the Datasource ID field, enter 'MyDS'.
   2. In the Datasource Type field, select RDBMS from the list of values. 
2. You will now be prompted to enter details of your RDBMS:
   
3. Enter the following details of your MySQL database in the relevant fields as shown above:
   
   • Database Engine: MySql
   • Driver Class: com.mysql.jdbc.Driver
   • URL: jdbc:mysql://localhost:3306/employeedb
   • User Name: root
   • Password: (Leave this blank)
4. Click Save to save the datasource.
5. Click Next. This will take you to a new page for adding queries to your service. 

Step 3: Creating a query for your datasource

1. Now we will create a query to obtain all the employee details saved in the database.
   1. Enter a name for the query in the Query ID field. We will use 'QueryAll'.
   2. All datasources created for the data service will be listed for the Datasource field. Select MyDS from this list.
   3. Specify the SQL statement in the SQL field. We will use a SELECT statement to query for all the employee details in the database as shown below.
      
   4. We must now specify output mappings to determine how the information in the database should be displayed in the query output. We will be needing three columns (ID, Name and Address) to display the employee details. Therefore, we need to create three output mapping entries as explained below.
      1. Click Add New Output Mapping and the following screen will open. You can now enter the first output mapping for employee ID as shown below.
         
      2. Click Add to create the output mapping.
      3. Repeat the steps using the following information to create the remaining two output mappings:
         
         • Mapping Type: Element

           Output field name: Name
           Data source column Name: name
           Schema Type: xs:string

         • Mapping Type: Attribute

           Output field name: address
           Data source column Name: address
           Schema Type: xs:string

      4. When you have created all the columns as output mappings, they will be listed as follows:
         
2. Click Main Configuration to return to the main page.
3. Click Next. This will take you to a new page for connecting operations to each of your queries.

Step 4: Creating an operation to invoke a query

1. Enter a name for the operation in the Operation Name field. We will use 'getEmployees'. 
2. All the queries defined for the data service will be listed for the Query ID field. Select 'QueryAll'.
   
3. Save the operation.
4. Click Finish to complete the data service creation. The 'MyFirstDS' data service is now listed as a deployed data service.
   

Invoking the data service

In this section, we will look at two different ways of invoking our data service without writing a single line of code. First we will invoke our data service using the Tryit utility, which is integrated with the Management Console of WSO2 DSS. We will then invoke the service using a simple HTTP GET request.

Using the TryIt tool

1. In the Deployed Services page, you will now see 'MyFirstDS' listed as a data service. You can access the Deployed Services page by clicking Services -> List in the Main tab.
2. Click the Try this service link for the data service. The service will be opened from the TryIt tool as shown below.
   
   All the operations defined for the data service will be listed in the left navigator. As shown above, the 'MyFirstDS' data service has one operation (getEmployees). 
3. Click getEmployees to invoke the operation.

4. Click Send to execute the getEmployees operation and the result will be printed as shown below. 
   

   Note that the employee ID and name will be returned as XML elements and the address will be wrapped as an attribute. This is due to the output mapping that was defined for each column: We have configured ID and Name as element type mappings and the address as an attribute type mapping. You can edit these mappings and observe the associated changes in the response very easily using the Tryit tool.

Sending an HTTP GET request

Now we will invoke the same data service using the HTTP GET request. Get the URL of the data service from the service dashboard:

1. Go to Services -> List to open the Deployed Services page.
2. Click the data service (MyFirstDS) to open the service dashboard:
   
   See that the URL of the 'MyFirstDS' data service is listed under Endpoints: https://10.100.5.65:9443/services/MyFirstDS/
3. You can execute the getEmployees operation using the above URL. Simply copy this URL followed by the operation name as shown below.
   https://10.100.5.65:9443/services/MyFirstDS/getEmployees
4. The result will be the same as with the TryIt tool:
   

This concludes the quick start guide for WSO2 DSS 3.5.1. You can find more advanced use cases in the Tutorials.