Supported Types of Input and Output for XML and JSON Messages

When using the JSON and XML message formats with RESTful Web service endpoints, the type and format of inputs and outputs you can use is limited compared to the features of SOAP endpoints. Stored processes can accept two types of input: prompts and data sources. They can produce three types of output: output parameters, data targets, and packages. Prompts enable you to supply simple parameters for stored process execution. The SAS prompting framework enables you to create prompt definitions that describe the type and format of your stored process's input parameters. When you invoke a Web service, the prompting framework validates the values that you supplied for the stored process prompts. The prompting framework translates these values into a macro variable that can be used in your stored process. Data sources enable you to supply arbitrary streams of data to your stored process to be processed. These data streams can be text such as XML or raw binary content. The data that you supply in a data source is streamed to a fileref in your stored process. Output parameters contain the values from macro variables from your stored process after it is finished running. This enables you to return simple values from your stored process. Data targets are like data sources in that they are streams of arbitrary data. However, data targets are produced by the stored process. Stored processes can use the SAS Publishing Framework to create a package during stored process execution. A package is a collection of assets that can be returned to the stored process client (in the case of SAS BI Web Services, the client is the Web service client). Packages can contain binary and textual data and are a convenient way to package complex reports that contain multiple images and text or HTML content produced by SAS. If a stored process returns a package, that package can be returned to the Web service client as a list of entries and the contents of those entries.

Supported Input and Output for XML Messages

When using RESTful XML SAS BI Web Services endpoints, all types of input and output are supported. You should send XML requests using the same format as for SOAP messages. Always omit SOAP elements from requests to the RESTful XML endpoints, and you can also omit namespaces.
SOAP Message Versus Plain XML Message
SOAP Message
Plain XML Message
<soapenv:Envelope
 xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
 xmlns:biw="http://www.sas.com/xml/namespace/biwebservices">
   <soapenv:Header/>
   <soapenv:Body>
      <biw:addfloats>
         <biw:parameters>
            <biw:num1>2.3</biw:num1>
            <biw:num2>4.2</biw:num2>
         </biw:parameters>
      </biw:addfloats>
   </soapenv:Body>
</soapenv:Envelope>
<addfloats>
   <parameters>
      <num1>2.3</num1>
      <num2>4.2</num2>
   </parameters>
</addfloats>
The other difference between SOAP and plain XML messages is how binary content is handled. Data sources, data targets, and packages can all contain binary data. SOAP endpoints use WS-* standards to handle binary content. Specifically, SOAP can use attachments to include the binary content out-of-band of the SOAP envelope (but still within the same HTTP request or response) using multi-part responses. Plain XML messages contain Base64-encoded data inline in the XML request or response. This is less efficient than SOAP attachments because serializing the binary content to Base64 takes extra processing time and also bloats the size of the binary data compared to its original size. Therefore, avoid using plain XML messages when using multiple large binary resources.
If you need to retrieve only a single output resource (binary or otherwise), you can access the specific output resource that you need by using the appropriate resource suffix on your Web service endpoint URL. When accessing a single binary output resource with resource suffixes, the binary data is not transcoded to Base64 data. See Accessing RESTful JSON and XML Web Service Endpoints for more information about how to access these resources using suffixes.

Supported Input and Output for JSON Messages

Because JSON supports only a limited number of native data types, JSON SAS BI Web Service endpoints accept only simple values for stored process prompts and can return only results from output parameters (not data targets or packages). The JSON SAS BI Web Service endpoints support prompt values that are supplied using application/x-www-form-urlencoded encoding in the HTTP request body. You must use HTTP POST when supplying values to JSON endpoints. You can use HTTP GET when your stored process does not require any input. For example, a JSON invocation of a stored process that adds two numbers, num1 and num2, might look like the following:
JSON Invocation of a Stored Process
Request
Response
num1=2.0&num2=3.5

{
  "outputParameters":
  {
    "Sum": "5.5"
  }
}

Be sure to specify the Content-type HTTP header as application/x-www-form-urlencoded when you use POST. The following table lists supported prompt types for JSON messages (note that no multi-value prompt types, including ranges and selections, are supported when using JSON):
Supported Prompt Types for JSON Messages
Prompt Type
Supported
Notes
Text
yes
Numeric
yes
Color
yes
Supports hexadecimal values only.
Date
yes
Supply a text value that matches the date type in the prompt definition.
Time
yes
File
yes
Data source
yes
Data library
yes
Supply this in the form libraryPath :: libref. For example, /Products/SAS Intelligence Platform/Samples/STP Samples(Library) :: stpsamp is a valid data library value.
Data source item
yes
Supply this in the form dataSourceLocation :: dataSourceType :: columnName :: columnLabel :: columnType.
OLAP member
yes
Ranges
no
Multi-value prompts
no