RFM Web Services: A RESTful API

The RFM Web Services API is implemented in accordance with the REST interface architecture. REST stands for Representational State Transfer and is a refinement of the ideas behind Service Oriented Architectures (SOA) and Web Services. "Classic" Web Services are based on SOAP (Simple Object Access Protocol), which itself was conceptually based on RPC (Remote Procedure Call), and sought to create a universal RPC protocol whose metadata was discoverable. This has received strong support in almost all modern application development languages which provide powerful automation features that make calling SOAP interfaces as easy as calling native methods within the language.

However, without such automation or language support, SOAP is quite cumbersome to use, as calling a SOAP service and parsing the response it returns requires the precise manipulation of a specific XML schema. In environments that don't do this automatically, the overhead required to use "classic", SOAP-based web services makes using them impractical. Most notable among these is the use of AJAX (Asynchronous Javascript with XML) in web applications. While it is technically possible to make AJAX calls to SOAP services, the complexity of doing so in raw Javascript, without a helper library that handles the SOAP details, makes using SOAP in Javascript impractical (note that to prevent cross-domain scripting, browsers will usually only allow AJAX calls to URIs that are on the domain containing the document from which the call was made. Despite this, being able to directly call services from that domain using AJAX embedded in a web page is still often very useful).

REST offers a more AJAX-friendly approach to consuming services than SOAP. It uses a protocol that has the same format as standard URIs and omits the XML-based protocol for RPC altogether. This is the founding principle of REST, namely, that remote access be treated not as a remote procedure call (the SOAP way), but as a resource request (just like a web URI). For example, compare the SOAP call to a service method that returns informationabout a customer (e.g. GetCustomerID with ID=1 set in the body of RPC XML signature) to the equivalent resource request in REST (that is, the URI to retrieve the Customer resource with ID=1)

SOAP HTTP: POST http://hostaddress/ServiceName/   Body: <?xml version="1.0" encoding="utf-8" ?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <soap:Body> <GetCustomerInfo xmlns="http://tempUri.org/"> <CustomerID>1</CustomerID> <OutputParam /> </GetCustomerInfo> </soap:Body> </soap:Envelope>

REST HTTP: GET http://hostaddress/ServiceName/Customer?ID=1   Body:

To sum up, a RESTful service is one that:

• Follows the stateless disposition of web requests.
• Can be called using a standard HTTP URI.
• Uses HTTP methods* (GET, POST, PUT, DELETE, etc.) to specify the verb in the action to be performed and complies with the implied semantics** of each method.

*

Note that some corporate firewalls block all methods except GET and POST. As a result, many RESTful interfaces, including RFM, use only these methods.

**

It is assumed that GET calls do not make changes to any data on the server, and so can be re-sent without any negative results. PUT and DELETE do make changes, but it is expected that if they are resent (for example, a request is made to delete an item that has already been deleted), the server handling the reqest will handle the request appropriately. It cannot be assumed that POSTs can be safely re-sent as repeating the request may have undesirable results (for example, re-sending a request to create a new record may create an unwanted second copy of the record).

A note about metadata
As mentioned above, one of the attractive features of "classic" web services was the discoverability of a service's metadata by querying its WSDL (Web Services Description Language). While metadata protocols for RESTful services have been deveoped, none has become the accepted standard in the universal way that WSDL works alongside SOAP. As a result, the RFM REST interface does not expose metadata as of this release, but may do so in future releases if a standard for this emerges, or if specific use-cases demand it.

As described above, a REST API is based on a resource model. The resources referenced by the RFM Web Services API, along with the relations between them and the URI patterns the API uses when retrieving a given resource type with the HTTP GET mehtod are shown in the diagram below.
A complete list of the resource requests available in the RFM Web Services API, including reference documentation, is provided in the RFM Web Services API Reference.

Format of data returned by RFM Web Service API requests
All RFM Web Services API requests, without exception, return data as a Response JSON string, formatted as follows: Further information about the Response data type and error codes is available in the RFM Web Services API Reference. ◂ Prev Next ▸