Configuring REST Web Services for AJAX

CICS REST web services can be invoked from a web page using Javascript. This is usually known as AJAX (Asynchronous Javascript and XML), though in the case of CICS web services it does not actually involve XML, and the Javascript can invoke the service synchronously or asynchronously. (Usually asynchronous invocation is preferred, so the page does not "hang" if the server doesn't respond quickly.) Some additional configuration is required for a REST web service that will be invoked with AJAX.

See To Configure a REST Web Service for more information.

The Access-Control-Allow-Origin header

When a web page script tries to invoke a service, the Same Origin Policy (SOP) is applied. If the service is hosted by a server other than the one the script was downloaded from, the script is not allowed to process the response unless the response message from the server indicates that it trusts the client. This is a security feature implemented in all of the major browsers, to prevent malicious scripts from performing actions on other servers that the user has access to. The SOP will block scripts from using the results of CICS REST web services, since Enterprise Server for .NET is not the server the script was loaded from.

CICS can tell the browser that the script is allowed to use the results of the service by setting the Access-Control-Allow-Origin HTTP response header. The value of the header can be the origin of the web page making the request, or the wildcard *, which lets any script invoke the service. The origin of a web page is typically the first part of the URL used to fetch it, such as "http://example.com"; it should match the value of the Origin header in the request made by the script. It may be easier to simply set the * value, though this can be a security risk if the service can be accessed by untrusted clients.

Commarea size and encoding

A Javascript client will generally want to exchange data with the CICS transaction program in string form, since Javascript is not suited to defining COBOL group items. That means the server's response may be longer than the client's request. To ensure the commarea is large enough for the server's response, the service configuration should set the optional commarea minimum size attribute, to the size of the largest response the transaction program may generate.

Similarly, it is generally useful to set the commarea response encoding attribute to "text", to indicate that the transaction program's response should always be treated as a text string.