PilotFish Interface Exchange (PIE)

RESTful Web Services

According to Wikipedia, Representational state transfer (REST) is a style of software architecture for distributed hypermedia systems such as the World Wide Web. The idea is that, rather than using complex mechanisms such as CORBA, RPC or SOAP to connect between machines, simple HTTP is used to make calls between machines.

RESTful applications use HTTP requests to post data (create and/or update), read data (e.g., make queries), and delete data. Thus, REST uses HTTP for all four CRUD (Create/Read/Update/Delete) operations. Below you can see the table that associates specific HTTP method with one of the CRUD operations:

The RESTful web service approach allows accept input data in any machine-readable format, such as JSON, XML, binnary data etc.. The same for the output data.

The URL style for the RESTful web services should be resource-oriented. It means that it should both indentify and locate the resource. The sample RESTful URL may look like this:

http://example.com/MyApplication/cars/123

This simple URL specifies the:

• Host with the web service - 'http://example.com'
• Application path - 'MyApplication'
• Type of the resource that should be processed - 'cars'
• Unique ID of the resource to be processed - '123'

RESTful Web Service Listener

This implementation of the RESTful Web Service Listener allows end user to accept RESTful web service calls to any resource in the system in any possible machine-readable format. The listener is very flexible and configurable. The following parameters can be configured:

• Allowed HTTP methods. User may want to let this web service to accept only GET and DELETE methods. In this case PUT and POST requests will be ignored and appropriate result returned to requestor.
• Allowed resources. As we described above, listener can accept calls to any resources, specified in the body of the URL. But this list may be restricted in the listener configuration.
• Listener request path.
• HTTP basic authentication credentials.

The workflow of the RESTful Web Service Listener is described below:

1. Listener waits for request to the specified listener request path
2. Request Received...
3. Check the requestor credentials if authentication required.
4. Check if URL of the request is appropriate for RESTful web service. URL should look like this: 'http://example.com/MyApplication/ListenerPath/ResourcesName/ResourceIdentifier'.
   'ResourceIdentified' may be left blank for POST method call.
5. Check if the HTTP method is in the list of the allowed HTTP methods.
6. Check if the ResourceName is in the list of the allowed resource names.
7. Create XML from the incoming resource data and from the request details.
8. Send XML to the route for further processing.
9. Wait for response from XCS eiPlatform execution and send it back to requester.

The sample listener's output XML for the PUT HTTP request, executed against 'http://example.com/MyApplication/ListenerPath/cars/123' URL with XML data inside it, would look like this:

<?xml version="1.0" encoding="UTF-8"?>
<XCSData>
	<ResourceName>cars</ResourceName>
	<ResourceIdentifier>123</ResourceIdentifier>
	<HTTPRequestMetadata>
		<RequestPath>http://example.com/MyApplication/ListenerPath/cars/123</RequestPath>
		<Method>PUT</Method>
		<Header>
			<Name>Content-Type</Name>
			<Value>text/xml; charset=utf-8</Value>
		</Header>
		<Header>
			<Name>Content-Length</Name>
			<Value>100</Value>
		</Header>
	</HTTPRequestMetadata>
	<HTTPRequestBody>
		<car>
			<MakeOfCar>Toyota</MakeOfCar>
			<model>Corolla</model>
			<color>Red</color>
		</car>
	</HTTPRequestBody>
</XCSData>

Web Application Description Language support

The RESTful Web Service Listener allows you to specify WADL file, that would describe your service in details for RESTful web service clients. To get this WADL file, web service client needs to performr request to the 'http://example.com/MyApplication/ListenerPath?wald' URL. You can read more about what is WADL and how to create it here.

Release Details

This is the initial release of the RESTful Web Service Listener.