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.