What Are REST and JSON?

REST

Starting in SAS 9.3, SAS BI Web Services also exposes all structured Web services as RESTful resources that can be invoked using either JSON or plain XML inputs and outputs. REST stands for Representational State Transfer and describes a pattern for interacting with content on remote systems, typically using HTTP. REST describes a way that you can access and modify existing content and also how to add content to a system. RESTful HTTP Web services use the standard set of HTTP verbs to indicate the action the user wants to perform. For example, if you wanted to retrieve a value from a RESTful HTTP Web service, you would use the HTTP verb GET. If you wanted to send some data to a RESTful HTTP Web service, you would use the HTTP verb POST. Because REST is an architectural concept and not a standard, there are no set rules for how a client and service should use the set of HTTP verbs, so it is ultimately up to each service to decide how to implement a RESTful architecture. SAS BI Web Services expects clients to use GET when invoking stored processes that require no input and POST when invoking stored processes that require prompt or stream input. Conceptually, you can think of stored processes that require no input as a resource that you simply want to retrieve, and that is why you use GET. Conversely, stored processes that need input require that you POST that input to the resource.
In addition to using standard HTTP verbs, RESTful HTTP Web services emphasize the representation of resources in the form of URLs. Therefore, instead of exposing multiple operations and resources through a single endpoint as SOAP services typically do, RESTful Web services delineate resources by making them available at different URLs. This means that you can access all the results of a stored process invocation at a URL with a suffix such as/rest/storedProcesses/path/to/stored/process, but you can also access specific output resources at URLs with a suffix such as/rest/storedProcesses/path/to/stored/process/parameters/myOutputParameter and /rest/storedProcesses/path/to/stored/process/streams/myOutputStream. SAS BI Web Services treat output parameters, output streams (also known as data targets), and packages as distinct resources that can be retrieved individually and separately from any other output. Note that even though you can request a distinct output resource, every time you do so the stored process is executed and all results are retrieved by SAS BI Web Services. This means that requesting specific resources will not make execution any quicker or more efficient in this version of the release (but it makes the client code simpler). When you request a distinct output resource using a RESTful URL, only that specific resource is returned to your client. For example, if your stored process writes a PDF to a data target and you request that specific output stream resource using a RESTful URL, then the data returned to the client is the actual PDF binary contents and the HTTP response includes the proper HTTP content type headers. For more information about the output resources available from RESTful Web services and information about how to access RESTful Web services, see Accessing RESTful JSON and XML Web Service Endpoints.
REST does not prescribe a specific message format to use during HTTP resource exchanges. It is up to the RESTful Web service to choose which formats are supported. XML and JavaScript Object Notation (JSON) are two of the most popular formats used by RESTful Web services. SAS BI Web Services supports both of these message formats.

RESTful Message Formats

XML

The format of input and output XML messages when using RESTful SAS BI Web Service endpoints mimics the SOAP format for a given stored process or generated Web service. The only differences are:
  • None of the SOAP XML elements should be present in requests or responses.
  • Namespaces are optional in requests. If they are used in the request, then they are used in the response. If they are used with the REST endpoint for a generated Web service, then they must match the namespace of the generated Web service. Generally, it is advisable to avoid using namespaces for the plain XML message format.
  • Binary content is Base64 encoded and inlined.
The similarities between the plain XML format and the SOAP message format make it easier to write client code if there are no tools that can automatically generate client stubs.

JSON

JSON is a simple text-based message format that is often used with RESTful Web services. Like XML, it is designed to be readable, and this can help when debugging and testing. JSON is derived from JavaScript, and therefore is very popular as a data format in Web applications. Because JSON has extensive support in JavaScript, it is often used in AJAX Web applications for creating rich, dynamic user experiences that incorporate remote data and service execution. However, JSON can be read and written by many programming languages.
JSON has only a limited set of basic, built-in data types. Therefore, SAS BI Web Services supports only simple prompt types and output parameters when using JSON.