Using JSON Messages with RESTful Services

The tutorial on exposing data as a REST resource guides you with step-by-step instructions on how to expose data as REST-style resources. 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.

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_PATH". See JSON objects in payloads for more information. The child name/values of the child fields in the payload 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_PATH". See JSON objects in payloads for more information. The child name/values of the child fields in the payload 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". See JSON objects in payloads for more information related to the object name.

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

If you are sending request payloads to a REST resource defined in the data service, the object name specified in the payload must be in the following format: "_<HTTP_METHOD><RESOURCE_PATH>", where RESOURCE_PATH represents the path value specified in the data service resource. However, if the RESOURCE_PATH specified in the data service contains the "/" symbol, be sure to replace the "/" symbol with the underscore symbol ("_") in the payload object name. See the following examples.

If the RESOURCE_PATH is "wso2employee", the payload object name should be as follows:

• For HTTP POST requests: _postwso2employee
• For HTTP PUT requests: _putwso2employee

If the RESOURCE_PATH is "wso2/employee", the payload object name should be as follows:

• For HTTP POST requests: _postwso2_employee
• For HTTP PUT requests: _putwso2_employee

If you are sending a batch request, and if the resource path is "wso2/employee",  the payload object should be as follows:

• For HTTP POST requests: 

  {
      "_postwso2_employee_batch_req": {
          "_postwso2_employee": [
              .........
          ]
      }
  }

• For HTTP PUT requests:

  {
      "_putwso2_employee_batch_req": {
          "_putwso2_employee": [
              .........
          ]
      }
  }