Exposing Data as REST Resources

The WSO2 Data Services feature supports exposing data as a set of REST style resources in addition to the SOAP services.

Defining a REST resource

Follow the steps given below to define REST resources.

1. Log in to the product's management console and select Data Services > Create under the Main menu.  
2. The Create Data Service page appears. Fill in the data service details as explained here and click Next.
3. Similarly, navigate through the configurations for  data sources, queries and operations until the Resources window opens.
   
   Using this window, you can define REST resources that are accessed as RESTful Web services. For example,
   
   • Resource Path: The resource name that is appended to the end of the resource URI. There are two ways of giving the resource path:
     • Use a query path with the following format: <resource_path_name>/{Input_Parameter}
     • Use a query parameter by giving a name for the resource path. For example, enter Product, if you are querying for products.
   • Resource Method: The HTTP operation (GET, POST, PUT or DELETE).

   • Query ID: The corresponding query for the resource invocation. See the section on writing data service queries for more information.

For a demonstration of the usage of REST support, see the sample on Exposing Data as REST-Style Resources. 

Sending and receiving JSON messages

By default, the REST resources or data services defined in WSO2 DSS receives messages and responds to messages in XML format. However, you have the option of specifying the response format when you define your data service/resource. See the topic on output mapping for instructions.

Given below are some guidelines that you need to follow when working with REST resources and JSON messages in WSO2 DSS.

Receiving a JSON response from a REST resource

From WSO2 DSS 3.2.0 onwards, the possibility of receiving messages in JSON format is enabled by default. Therefore, you can simply send requests by adding “Accept:Application/json” to the request header, and you will receive the response in JSON. For example, shown below is how you can send a GET request to a resource using CURL:

curl -X GET -H "Accept:application/json" http://localhost:9763/services/samples/ResourcesSample.HTTPEndpoint/product/S10_1678

Additionally, if you have the output mapping set to JSON in your resource query as explained here, the JSON response you receive will be according to the JSON template you have defined in the output mapping.

<parameter name="httpContentNegotiation">true</parameter>

Sending JSON payloads to a REST resource

If you are sending JSON request payloads for data services REST resources, the JSON payload must be in a specific format for different types of HTTP methods as explained below.

HTTP POST

When you send an HTTP POST request, the format of the JSON object name should be "_post$RESOURCE_NAME", and the child name/values of the child fields should be the names and values of the input parameters in the target query. Given below is an example of a JSON request that sends an HTTP POST request to the "employee" resource path. 

{
  "_postemployee": {
    "employeeNumber" : 1,
    "lastName": "Doe",
    "firstName": "John",
    "email": "jdoe@wso2.com",
    "salary": 13500.0
  }
}

HTTP PUT

When you send an HTTP PUT request, the format of the JSON object name should be "_put$RESOURCE_NAME", and the child name/values of the child fields should be the names and values of the input parameters in the target query. Given below is an example of a JSON request that sends an HTTP PUT request to the "employee" resource path. 

{
  "_putemployee": {
    "employeeNumber" : 1002,
    "lastName": "Smith",
    "firstName": "Will",
    "email": "will@smith.com",
    "salary": 86500.0
  }
}

JSON-based resource batch requests

When batch requests are enabled for data services resources, resource paths are created with the "_batch_req" suffix. In the payload content, the single request JSON object becomes one of the many possible objects in a parent JSON array object. This will have a name with a single request wrapper object + the "_batch_req". Shown below is a sample batch request for the HTTP POST request shown earlier.

{
    "_postemployee_batch_req": {
        "_postemployee": [
            {
                "employeeNumber": 5012,
                "lastName": "Smith",
                "firstName": "Will",
                "email": "will@smith.com",
                "salary": 13500.0
            },
            {
                "employeeNumber": 5013,
                "lastName": "Peter",
                "firstName": "Parker",
                "email": "peter@parker.com",
                "salary": 15500.0
            }
        ]
    }
}

JSON objects in payloads

When sending payloads (JSON or XML) to a REST resource, the format of the object name should be as shown below. Note that the RESOURCE_PATH is optional. However, if the RESOURCE_PATH is specified in the payload, be sure that the slash used in the resource path is replaced by the underscore (_) sign in the payload. See the instructions on setting the resource path.

• HTTP POST: _post<RESOURCE_PATH>_<RESOURCE_NAME> (E.g. _postwso2_employee)
• HTTP PUT: _put<RESOURCE_PATH><RESOURCE_NAME> (E.g. _putwso2_employee)
• JSON-based resource batch requests: _post<RESOURCE_PATH>_<RESOURCE_NAME>_batch_req (E.g. _postemployee_batch_req)