User-defined web services can be exposed as a REST web service and
configured to have a POST method that accepts JSON input.
Spectrum OnDemand REST web services have a POST method that accepts JSON
input. Specify Content-Type:application/json
and use the following
format for JSON POST requests.
Flat Data
Use this format in the body request to send flat data to a web service using POST.
{
"InputStageName":
{
"InputDataType": [
{
"FieldName1": "FieldValue1",
"FieldName2": "FieldValue2"
}
]
}
}
Where:
- InputStageName
- The name of the input stage as shown on the canvas in Spectrum Enterprise Designer. The default name of the stage is Input.
- InputDataType
- The name given to the record-level entity. This value is specified in the dataflow's Input stage, in the Data type name field on the Input Fields tab. The default name of the record-level entity is Row.
- FieldName1 and FieldName2
- The names of the input fields defined in the service's Input stage.
- FieldValue1 and FieldValue2
- Input data that you want to send to the web service in the corresponding field.
List Data
Use the following format to send list data to a web service using POST.
{
"InputStageName":
{
"InputDataType": [
{
"ListField1":[
{"SubfieldName1": "SubfieldValue1"},
{"SubfieldName2": "SubfieldValue2"}
]
}
]
}
}
Where:
- InputStageName
- The name of the input stage as shown on the canvas in Spectrum Enterprise Designer. The default name of the stage is Input.
- ListField1
- The name of the hierarchical field defined in the service's Input stage.
- SubfieldName1 and SubfieldName2
- The names of child fields that comprise the list field.
- SubfieldValue1 and SubfieldValue2
- Input data that you want to send to the web service.
User Fields
You can pass extra fields through the web service even if the web service does not use
them. These fields are returned, unmodified, in the user_fields
section of
the response. The user fields you supply in the request do not need to be defined in the
service dataflow's Input stage.
{
"InputStageName":
{
"InputDataType": [
{
"user_fields": [
{
"name": "FieldName1",
"value": "FieldValue1"
},
{
"name": "FieldName2",
"value": "FieldValue2"
}]
}
]
}
}
Where:
- InputStageName
- The name of the input stage as shown on the canvas in Spectrum Enterprise Designer. The default name of the stage is Input.
- FieldName1 and FieldName2
- The name of the pass-through field.
- FieldValue1 and FieldValue2
- The data you want to include in the passthrough field.
Options
You can specify options in the request, overriding the default options specified in the service dataflow. For user-defined web services, you can only specify options in the request if the dataflow has been configured to accept options. To configure a service to accept options in the request, open the service in Spectrum Enterprise Designer and select
.To specify processing options in a request, use this format:
"options" : {
"OptionName1" : "Value1"
},
Where:
- OptionName1
- The name of the option. For a list of valid options for the service see the service's WADL or open the service in Spectrum Enterprise Designer and select .
- OptionValue1
- A legal value for the option. For a list of legal values, open the service in Spectrum Enterprise Designer and select .
Example JSON Request using POST
The following example demonstrates how to include options, flat fields, a list field, and user-defined fields in a JSON request to a web service using POST.
{
"options" : {
"OutputCasing" : "U"
},
"Input":
{
"Address": [
{
"AddressLine1": "1825 Kramer Ln",
"City": "Austin",
"StateProvince": "TX",
"Accounts": [
{
"AccountNumber": "120993",
"ExpirationDate": "10-3-2017"
},
{
"AccountNumber": "898732",
"ExpirationDate": "8-13-2016"
}
],
"user_fields": [
{
"name": "Note1",
"value": "Prefers decaffeinated coffee"
},
{
"name": "Note2",
"value": "Requests east facing window"
}]
}
]
}
}
- OutputCasing is an option exposed by the web service that controls whether the output is returned in upper case or lower case. In this request, it is set to U for upper case.
- Input is the label of the Input stage in the dataflow as displayed on the canvas in Spectrum Enterprise Designer.
- Address is the name of the record-level entity as specified in the dataflow's Input stage, in the Data type name field on the Input Fields tab.
- AddressLine1, City, and StateProvince are flat fields.
- Accounts is a hierarchical ("list") field containing subfields name AccountNumber and ExpirationDate. There are two accounts included in this example.
- user_fields contains user-defined fields that are passed through and returned in the output unmodified by the web service.