<html><font color=#990000 size="+2"><b>REST API Users Guide</b></font> </html>

<sub>Copyright 2014 StreamScape Technologies.  The trade name StreamScape and the product names Service Application Engine™ and Service Event Fabric™ are trademarks of StreamScape Technologies. This document may not be reproduced in any medium without the express permission of StreamScape Technologies LLC. For problems and issues with this documentation please contact us at [[support@streamscape.com]]</sub>

======Overview======

The Service Application Engine™ supports //RESTFul//  access to nearly all of the resources managed by the engine.  Services, Event Datagrams, Messaging API, Repository Metadata and data in Application Dataspace™ Collections are all accessible via the REST interface and may be queried from web browsers using frameworks such as jQuery or tools such as //curl//.  This section covers the history and basics of a REST style data exchange between software components.

=====REST Definition=====

Representational State Transfer (REST) is a style of data exchange between two software components within a distributed system, such as the World Wide Web.  Although technically it is just a data exchange pattern, REST has emerged over the past few years as a predominant [[http://en.wikipedia.org/wiki/Web_service | Web Service]] architecture model.  As of this writing, thousands of applications, Cloud System developers, Web and mobile application designers have used the REST design model to offer full service platforms, [[http://en.wikipedia.org/wiki/Mashup_(web_application_hybrid) | mash-up]] and [[http://en.wikipedia.org/wiki/Software_widget | widget]] capabilities to their users; resulting the emergence of a so-called API Economy.

By strict definition of REST constraints, a [[http://en.wikipedia.org/wiki/Client_(computing) | client]] application makes a synchronous request to a [[http://en.wikipedia.org/wiki/Resource_(Web) | resource]] provider and receives back some data.  This information now represents the new state of the client application.  For example an application may request authentication with a back-end system by passing a security credential to the resource provider.  The result of such a request may be an authenticated session identifier.  This allows the client to transition into a trusted (authenticated) mode, ready to transmit secure work requests.  A subsequent request may return a list of available resource providers or services that a client application may make use of. 

While this concept is not new (mainframe systems used to call such exchanges conversational programs), its application to distributed system design is a relatively recent development.  Whereas legacy systems focused on conversational interactions between a single client and a [[http://en.wikipedia.org/wiki/Server_(computing) | server]], REST –based systems allow the same client application to access a broad range of resource providers.  This model offers developers the ability to compose applications from a variety of resources and capabilities, leading to new synergies and innovation.

The term representational state transfer was introduced in 2000 by Roy Fielding, one of the principal authors of the Hypertext Transfer Protocol (HTTP) specification. REST as an architectural style was developed in parallel with HTTP/1.1.  The largest implementation of a system conforming to the REST architectural style is the World Wide Web itself.  REST exemplifies how the Web's architecture and application design evolved based on the interactions of four key components of the Web: origin servers, gateways, proxies and clients, without imposing limitations on individual participants. 

As an architectural approach REST –based applications are complementary to Collaborative Computing systems because they promote self-governance and proper behavior of participants.  From a technology perspective, REST constraints limit the communication model, thereby simplifying implementation and ultimately, reducing cost.  Conforming to the REST Constraints outlined below is generally referred to as being "RESTful".

REST has increasingly displaced other interface design models such Messaging, SOAP and WSDL due to its simpler style and flexibility of format and protocol.  Most REST –based implementations conform to some of the constraints but do not enforce the strict definition of application state transitions described above.  As such, RESTful applications make use of the concepts to facilitate a simpler and more flexible RPC mechanism.  The Service Application Engine™ supports all REST constraints including Layering and On-Demand Code facilities.

=====REST Architecture=====

REST-style architectures consist of clients and servers. Clients initiate requests to servers; servers process requests and return appropriate responses. Requests and responses are built around the transfer of resource representations. A resource is any structured and meaningful concept that may be located by a discrete resource address, a so-called Uniform Resource Identifier (URI).  The representation of a resource is typically a document or similar structured data unit that captures the current or intended state of a resource.  

What is particularly interesting about the REST architecture is that resource state may represent conversational sessions, application services or transactions, or a combination of such elements without restrictions.  Consider the example of a well-known Shopping Cart application when re-implemented as a REST –based system:  A consumer must enter the Store by providing a security credential and identify themselves.  As a result of this operation the REST resource provider validates a consumer and puts the consumer application into a ready state by returning a session token and the address of the next resource manager. An application communicates its readiness by accessing the consumer’s Profile and Preference information from a resource at the specified location (URI).  

The profile document returned to a consumer may be (and frequently is) augmented by promotional advertising targeted at the individual.  If this is a returning customer the system may offer additional incentives by including links to other store resources. Adding items to a Shopping Cart begins an actual purchasing session and may potentially result in reservation of funds on behalf of the consumer, for example by contacting PayPal or a similar online payment system.

If a Shopping Session is interrupted for some reason and the consumer application remains functioning it may potentially cache session information and credentials.  When communication is re-established the application can request to be re-directed to the same resource provide it was using and complete the transaction without the need to re-enter information. REST facilitates transactions between resources by allowing loose coupling of services and their consumers, potentially without sacrificing control over session state.

This approach to application state management allows server-side implementations to be essentially Stateless and provides for a high degree of fault tolerance and scalability without the need for developing complex back-end systems to manage session state.  REST resource managers are abstracted, resulting in a Layered architecture that easily facilitates load balancing and caching of critical data. 

The Service Application Engine™ is purpose-built to support REST application and provides session control, load balancing and data caching as well as Asynchronous HTTP Communication extensions in addition to transaction access to in-memory resources making it an ideal intermediary (proxy) for RESTful client applications.

REST is weak-typed when compared to its SOAP counterpart.  There is no schema enforcement and no standard for data exchange beyond Standard General Markup Language (SGML).  REST commands are based on the use of nouns and verbs typically found in the HTTP protocol (such as GET, PUT, POST and DELETE) with emphasis on readability and data access.  This makes the REST operation set closer the CRUD Matrix operations of a database engine.  Unlike SOAP, REST is not completely dependent on XML parsing or rendering technologies and does not have a protocol specification or a formal interface definition language, thus making more compact and versatile.  

The REST model describes the following six constraints applied to an architecture model that make it RESTful: 

====Client–Server====

A uniform interface separates clients from servers. This separation of function means clients have no dependency on data storage, language or the specifics of a resource server implementation; thus improving client the portability and making it server-agnostic.  Resource servers are not concerned with the applications overall interface or state, making server implementations simples and more scalable.  Format of the client-server interaction is user defined allowing system components to be developed in a decoupled fashion, replaced or developed independently.

====Stateless====

Client context does not have to be stored or represented on the server between requests.  While this capability may be provided as a combination of client-side caching and intermediate proxy technologies a resource server is not aware of client application state in contrast to traditional database and application server technologies.

Each request from a REST client contains all of the information necessary to service the request, and any session state is maintained by a client or intermediary as necessary.  Although a resource server may be stateful this constraint merely implies that the client request (URL) provide enough information to address a server-side state manager (for example by providing a session id).  This option makes servers more visible for monitoring, and also makes them more reliable and scalable in the face of partial network failures.

====Cacheable====

Clients or REST intermediaries may cache responses. Therefore responses must implicitly or explicitly, define themselves as cacheable, or not, to prevent clients from using stale or inappropriate data as the basis for further requests. Well-managed caching partially or completely eliminates some client–server interactions, further improving scalability and performance.

====Layered System====

A client is abstracted from the resource server and cannot typically determine if it is connected directly to the end server, or to an intermediary along the way.  REST intermediaries may improve system scalability by enabling load-balancing, providing shared caches, session management or enforcing security policies.

====Code on Demand (optional)====

Servers are able to extend or customize the functionality of a client by the transfer (download) of executable code into the client application’s runtime environment. Examples of this may include compiled components such as Java Applets, Semantic Type objects, Event Prototype definitions used by the Service Application Engine™ or client-side scripts such as Java Script.

====Uniform Interface====

A uniform interface between clients and servers simplifies and decouples the architecture, enabling each component to evolve independently. The guiding principles of a REST interface are detailed below.  While the there is no format specification for an interface definition in REST –based systems it is expected that data exchange between participants occurs using structured data elements that are self-describing over the HTTP protocol or one of its secure variants.  Complying with the so-called REST Principles and architectural style, enables a variety of distributed hypermedia systems with desirable emergent properties, such as performance, scalability, simplicity, modifiability, visibility, portability and reliability.

=====REST Interface Principles=====

A key concept in RESTful systems is the existence of resources (sources of specific information), each of which is referenced with a global identifier (such as a URI in HTTP).  To manipulate these resources, components of the REST system communicate via a standardized protocol (such as HTTP) and exchange representations of resources (potentially documents or objects conveying information).  For example, a resource that represents a Purchase Order may accept a representation that specifies a list of items to purchase and billing information, and return a Purchase Conformation or Receipt formatted as a PDF document or a URL pointing to the resource. 

As such, a REST client application can interact with a resource by knowing only two things: the identifier of the resource and the action required—it does not need to know whether there are caches, proxies, gateways, firewalls, tunnels, or other intermediaries between it and the resource server delivering the information.  However, the application does need to understand the format of the information (representation) returned, which is typically an HTML, XML or JSON document, although it may be image, plain text, or any other content.  The uniform interface that any REST resource provides is considered fundamental to design of any REST service.

====Identification of Resources====

Resources are identified in requests, for example using URIs in web-based REST systems. The resources and their location are conceptually separate from the representations that are returned to the client.  For example, a data server may return HTML, XML or JSON that represents a set of information requested by the user application and may return such results in different formats or languages based on request URL. 

====Representation-Driven Data Modifications====

A client holding a representation of a resource, including any metadata attached, should have enough information to modify or delete the resource on the server, provided it has permission to do so.  Depending on the type of data being modified, resource representation may vary.  For example a Key-Value data collection such as a MAP may simply require a Key in order to modify or delete the resource.  

The <color green>Service Application Engine™</color> provides a variety of representational state objects including a Query object for working with SQL Queries, Row and Row Set objects.




======Using the REST API======

The Service Application Engine™ provides full support for REST –based Web Services and allows users to expose all application fabric components using a RESTful Web API.   Web Service developers have access to the following resources that may be invoked thru a REST API:

   * Java classes deployed as <color green>Application Fabric Services</color> 
   * Event Fabric™ facilities for raising an consuming Events 
   * Application Data Spaces™ for query and modification of Data Collections
   * Back-end (pass-thru) resources such as Databases, FTP and legacy systems
   * Files and Unstructured Data resources accessible via Fabric Services
   * Micro-flows for automating Business Processes composed from Fabric Services
   * User Profiles and Identity information

=====Accessing Service Engine Resources=====

By default an application engine disables HTTP access to it’s resources.  This is done to limit the number of initial Access Points into an application fabric SYSPLEX and simplify configuration.  Core topology of the overlay network formed by service engine nodes is configured thru the Directory Table that is managed by an Exchange Discovery Manager.  The SYSPLEX establishes connections between nodes using the TruLink Protocol, potentially allowing all fabric participants to see every resource within the application domain.  

Specific resource visibility is dependent on the resource component’s event scope, providing a way to secure and limit access to application fabric resources.  However the inherent nature of service engine communications means that any resource may be accessed from an HTTP client on any node.  In the diagram below participants labeled N are fabric nodes that do not host resources, C represents client components such as HTTP clients.  Participants labeled R represent resources such as service methods that may be invoked, data collections that may be queried or modified and events that may be raised or consumed.   All topology combinations described below are possible: 

{{:rest_api_ug:sae-proxy-view.png?300 |}}

1  Access by Proxy allowing a client to connect to a proxy node and access remote resources.

2  Embedded Client access allows clients to access resources by opening an Accessor to a Service or Data Space, or to raise Events.

3  Direct Access allowing a client to connect to a fabric node and access its Services and Data Spaces or to raise Events.
 
4  Access by Service Proxy allows users to create Service resources that are themselves proxy clients to other resources, accessible from    other client participants.

\\ 

=====Configuring HTTP Acceptors=====

An acceptor is a socket listener that supports a specific network protocol.  Protocol acceptors are configured by editing their XML Data Object (XDO) files located in the fabric cache directory (.tfcache).  The object type of the data object is always HTTPAcceptor and the acceptor’s name must be the instance name. In the example below the name of the acceptor file resolves to HTTPAceptor.Default.xdo

Acceptors may be auto-started by the engine or they may be controlled manually thru the SLANG language environment.  Like any other repository artifact an acceptor configuration object is locked by the runtime to prevent unauthorized editing.  An acceptor that is defined with a host name of localhost will not be accessible by remote clients.  Also note that on certain platforms such as Windows, new port allocations may be automatically blocked by Firewall software.

In addition to standard set of information regarding host and port names the HTTP acceptor supports the anonymousRegistration parameter that indicates whether or not the acceptor supports ability of users to self-register with the fabric; a setting that is potentially unsecure. 

The XML snippet below shows a typical HTTP acceptor configuration.  It is incomplete and does not include security information, REALM definitions or URL path mappings.  It is provided for sample purposes and should not be used as an actual acceptor configuration object:

<code xml>
<?xml version="1.0"?>
<HTTPAcceptor>
  <configuration>
    <name>Default</name>
    <description>Default HTTP acceptor</description>
    <isAutoStart>true</isAutoStart>
    <host>localhost</host>
    <port>8099</port>    
    <anonymousRegistration>true</anonymousRegistration>
    <logEachRequest>false</logEachRequest>
    <logUserAgent>false</logUserAgent>
    <logReferer>false</logReferer>
    <compressResponse>false</compressResponse>
    <storeSessions>false</storeSessions>
    <keepAlive>true</keepAlive>
    <requestLogFormat>{0}:{9} {1} {2} &quot;{4} {5} {6}&quot; {7,number,#} 
                      {8,number} {10} {11}</requestLogFormat>
    <webApplicationDir>webapps/</webApplicationDir>
    <webArchiveDir>war/</webArchiveDir>
    <backlogSize>50</backlogSize>
    <keepAliveTimeout>15</keepAliveTimeout>
    <sessionTimeout>5</sessionTimeout>
    <checkDeployPeriod>-1</checkDeployPeriod>
    <maxActiveSessionsNumber>-1</maxActiveSessionsNumber>
    <maxRequestsPerConnection>100</maxRequestsPerConnection>
    <maxThreadsInPool>100</maxThreadsInPool>
    <authenticationType>BASIC</authenticationType>
    <sessionAuthentication>false</sessionAuthentication>
  ..
</code>

The table below outlines HTTP Acceptor property settings.  Not all settings are currently in use:

^ Property  Name      ^ Description        ^
|name | Distinguished name of an HTTP acceptor |
|description | Description of the acceptor |
|isAutoStart | When TRUE the acceptor is automatically started and bound by the runtime |
|host | Name of the network interface (localhost by default) |
|port | Port number of HTTP listener |
|anonymousRegistration | When TRUE allows new users to dynamically register their ID and Password |
|logEachRequest | When TRUE the acceptor trace file logs all HTTP request |
|logUserAgent | When TRUE the acceptor trace file logs all User Agent requests |
|logReferer | When TRUE the acceptor trace file logs all Domain Referrals |
|compressResponse | When TRUE replies are compressed using GZIP compassion |
|storeSessions | When TRUE the acceptor stores HTTP Session information |
|keepAlive | When TRUE then Keepalive checks are performed |
|requestLogFormat | Specifies the request log format using positional notation |
|webApplicationDir | Specifies application directory for this acceptor in .htcache |
|webArchiveDir | Specifies WAR file pickup directory for this acceptor in .htcache |
|backlogSize | Specified connection back-log size (currently unused) |
|keepAliveTimeout | When Keepalive is used specifies the length of check timeout |
|sessionTimeout | Specifies in minutes how long an inactive Session may remain |
|checkDeployPeriod | Specifies how often to check the WAR deployment directory for new content |
|maxActiveSessionsNumber | Specifies how many HTTP Sessions may be active concurrently |
|maxRequestsPerConnection | Specifies maximum concurrent requests per user Connection |
|maxThreadsInPool | Sets the maximum number of HTTP acceptor threads in pool |
|authenticationType | Indicates BASIC or DIGEST authentication type (see Digest Authentication) |
|sessionAuthentication | Enables or disables x-session-token support (see Delegated Authorization) |



**Java Example**

<code java>
import com.streamscape.lib.http.*;
..
public static final int    DEFAULT_TIMEOUT = 30000;
public static final String SERVICE_REALM   = "Service";
..
HTTPConnection connection = null;
HTTPResponse   response   = null;
String         requestURL = null;
..
// Build a request URL here
..
connection = new HTTPConnection("localhost", 8099);
connection.setTimeout(DEFAULT_TIMEOUT);
connection.setAllowUserInteraction(false);
connection.addBasicAuthorization(SERVICE_REALM, "Admin", "admin");
..          
response = httpConnection.Get(requestURL);
</code>

In the sample code above a StreamScape –supplied HTTP client is used to construct the URL for issuing an HTTP request.  Base64 encoding occurs implicitly.  Note the use of a REALM identifier to specify the security domain.
