WEBSERVICES TUTORIAL

Basic Examples of Web Services

DataTypes: Echo

Often a web service requires using data other than a simple string. This data could be something simple like an integer or a real. Often the data is more complex and is a combination of simple data types. This example demonstrates how to use different data types.

In[1]:=
Click for copyable input
In[2]:=
Click for copyable input
Out[2]=

For each of the examples, the usage message may be used to determine the data types used by a web service.

Simple Data Types

Simple data types are the easiest data types to use in Web Services Link. Wolfram Language users should be familiar with the symbols String, Integer, Real, True, and False. Each of these may be used with a web service function.

Here is an example of using True with a web service.

In[4]:=
Click for copyable input
Out[4]=

Here is an example of using String with a web service.

In[6]:=
Click for copyable input
Out[6]=

Here is an example of using Integer with a web service.

In[8]:=
Click for copyable input
Out[8]=

Here is an example of using Real with a web service.

In[10]:=
Click for copyable input
Out[10]=

Nonstandard Simple Data Types

Web Services Link provides some data types that may be mapped to the XML Schema of a web service. , , , , , and are each simple data types that may be used with a web service.

Here is an example of using with a web service.

In[13]:=
Click for copyable input
Out[13]=

Here is an example of using with a web service.

In[16]:=
Click for copyable input
Out[16]=

Here is an example of using with a web service.

In[19]:=
Click for copyable input
Out[19]=

Examples of , , and follow in the next section.

Compound Data Types

Web Services Link generates symbols that are used to build compound data types. Compound data types are Wolfram Language expressions that contain instances of simple data types and/or compound data types. Compound data types are created in the Wolfram Language using a symbol representing the data type as the head of a Wolfram Language expression. The members of the data type are represented using rules in the body of the expression. The left-hand side of the rule specifies the name of a member of the data type. The right-hand side specifies the value of the member. The value may be a simple or compound value.

Here is an example of a web service that uses a compound data type.

may be used to generate an instance of .

In[22]:=
Click for copyable input
Out[22]=
In[23]:=
Click for copyable input
Out[23]=

Here is an example of how to retrieve data from a compound data type.

In[24]:=
Click for copyable input
Out[24]=

may be used to set a value for a compound data type.

In[25]:=
Click for copyable input
Out[25]=

Arrays

Web Services Link supports arrays using List. To use an array, you need only to use a Wolfram Language List consisting entirely of the data type defined by the array.

Here is an example of a web service that uses an array of simple data types.

In[27]:=
Click for copyable input
Out[27]=

Here is an example of a web service that uses an array of compound data types.

In[29]:=
Click for copyable input
Out[29]=
In[30]:=
Click for copyable input
Out[30]=

Images: Plot

Strings are a natural way to transmit graphics within web services. In order to ensure its integrity, binary data is encoded in base64. This example demonstrates how to use binary data types.

In[1]:=
Click for copyable input
In[2]:=
Click for copyable input
Out[2]=

In the Plot example, PlotString takes a string and an integer as parameters and returns a base64 binary string. The function converts the string into a Wolfram Language expression and then plots this as a function of from 0 to a limit specified by the integer. The service returns a list of base64 binary bytes wrapped in a head of . This head is used to identify this data as base64 binary. FromCharacterCode can be used to decode the base64 binary data into a string consisting of GIF data. This string may be imported to a GIF with ImportString.

In[4]:=
Click for copyable input
Out[4]=

Mathematical Data: Integrate

Web Services Link supports mathematical data using strings, typeset images, MathML, or Wolfram Language expressions. This example demonstrates using mathematical data.

In[1]:=
Click for copyable input
In[2]:=
Click for copyable input
Out[2]=

Strings

Mathematical data can be used with a web service by using Wolfram Language expressions within a string. The string data type has some limitations for communicating mathematical data. For one, it is one-dimensional. If you use InputForm or FullForm to represent the data, information about its presentation may be left out. It is also worth noting that while all web services support strings, they may not all support parsing Wolfram Language expressions from a string. However, sending a string to web service is probably the simplest way to communicate mathematical data, if not the most advanced.

This example demonstrates using strings to communicate mathematical data.

In[4]:=
Click for copyable input
Out[4]=

Web Services Link does not take a string and automatically convert it into a Wolfram Language expression. This is because all strings are not necessarily Wolfram Language expressions.

In[5]:=
Click for copyable input
Out[5]//InputForm=

But because this is the Wolfram Language, the result can easily be turned into an expression.

In[6]:=
Click for copyable input
Out[6]=

Typeset Images

Mathematical data can be presented with a web service by using images. An image has one major limitation for communicating mathematical data. An image cannot be easily manipulated or processed. This means data cannot be easily taken from it except visually and it cannot be changed and updated easily. Images are often useful, however, because typeset equations are not supported on nearly as many systems as images. So generating an image of a typeset equation is a nice way to present typeset equations on systems that do not support them.

The following example demonstrates using images to communicate mathematical data. The service returns a list of base64 binary bytes wrapped in a head of . This head is used to identify this data as base64 binary. FromCharacterCode can be used to decode the base64 binary data into a string consisting of GIF data. This string may be imported to a GIF with ImportString.

In[8]:=
Click for copyable input
Out[8]=

Wolfram Language Expression

Mathematical data can be presented with a web service by using Wolfram Language expressions. Expressions are how data is represented in the Wolfram Language. Expressions address some of the limitations of strings and images. However, expressions do have a few limitations of their own, the biggest being that they are not supported on all systems. However, since expressions are the standard for using mathematical data with the Wolfram Language, they can be very useful for interfacing with other Wolfram Language systems.

The following example demonstrates using Wolfram Language expressions to communicate mathematical data. The service returns an expression wrapped in a head of . This head is used to identify the following data as an expression.

In[10]:=
Click for copyable input
Out[10]=

Web Services Link encodes Wolfram Language expressions as ExpressionML within web services messages. The ExpressionML is automatically converted into an expression.

MathML

Mathematical data can be presented with a web service by using MathML. MathML is the standard for representing mathematical data across systems. MathML addresses some of the limitations that strings and images have. However, MathML does have a few limitations of its own, the biggest being that it is not supported on all systems. Another limitation is its complexity. MathML is more difficult to look at than something like InputForm. However, since it is the standard for using mathematical data outside of the Wolfram Language, it can be very useful for interfacing with other systems that do not use the Wolfram Language.

This example demonstrates using MathML to communicate mathematical data. The service returns symbolic MathML wrapped in a head of , which is used to identify the data as MathML.

In[12]:=
Click for copyable input
Out[12]=

Web Services Link does not take a MathML expression and automatically convert it into a Wolfram Language expression, because not all MathML instances are necessarily supported by Wolfram Language expressions. But because this is the Wolfram Language, the result can easily be turned into an expression.

In[13]:=
Click for copyable input
Out[13]=

SOAP Headers

SOAP headers are an important component to web services because they allow web services to process metadata separate from the body of a SOAP message. The body will contain information directly related to the web service operation being invoked. However, a header may contain more general content that is used across any number of the web service operations. For example, a header may contain a username and password. It is useful to include the username and password as a header, because a separate component can be used to process the username and password without needing to know anything about the body.

Web Services Link supports headers by including the header as part of the function signature of an operation. So it will look like any other parameter of the operation. If an operation requires two strings defining the username and password as headers, then these two strings will be expected when calling this function.

In[1]:=
Click for copyable input
In[2]:=
Click for copyable input
Out[2]=
In[4]:=
Click for copyable input
Out[4]=

Sessions

Sessions are used by web services to persist user data over multiple calls to a web service. For example, they can be used to save a user's settings, data, or other things. Sessions are supported by Web Services Link. However, there are no special functions or options. If a web service provides operations that use sessions, then sessions should be used by the Java client.

Here is an example that uses sessions. This example returns how many times a user has accessed the operation.

In[1]:=
Click for copyable input
In[2]:=
Click for copyable input
Out[2]=
In[4]:=
Click for copyable input
Out[4]=

Additional calls to increments the counter.

In[5]:=
Click for copyable input
Out[5]=

Authentication

Authentication is used by some web services to validate a user. This is based on functionality provided by HTTP. Digest and basic authentication are supported. A user can set the username and password by using the Username and Password options. These can be passed into any web service function and used for authentication.

In[59]:=
Click for copyable input
In[36]:=
Click for copyable input
Out[36]=

HTTP authentication is reused for supplemental calls to a URL. The username and password are stored in memory and will be required every time the Java Virtual Machine (JVM) is shut down.

In[37]:=
Click for copyable input
Out[37]=

Timeouts

A timeout may be required when calling a web service operation. A user can set the timeout by using the option. This can be passed into any web service function. The value of the option must be a positive integer specifying the timeout in milliseconds.

In[1]:=
Click for copyable input
In[2]:=
Click for copyable input
Out[2]=

Here is an example setting the timeout to 10 milliseconds.

In[3]:=
Click for copyable input
Out[3]=

Here is an example setting the timeout to 1 second.

In[4]:=
Click for copyable input
Out[4]=