Currently, WebServius supports REST services, but there is also limited support for other service types as described below. More service types will be added in the future. If there is a particular type of service you would like to see supported, please submit feedback in the WebServius feedback box.

What is REST

REST stands for Representational State Transfer, and refers to a style of services which have multiple “resources” (usually represented by URLs) that can be accessed using one of four actions: retrieving data, adding new data, replacing existing data, or deleting data. Retrieving data is usually accomplished using the HTTP GET verb. For example, suppose you are creating a service that returns the current weather in different cities. One example of a “resource” would be the temperature in each city, and the resources could be represented, for example, as http://weather.example.com/getWeather.php/{CityName}/temperature. To retrieve the temperature in Miami, you would retrieve the appropriate resource by issuing HTTP GET to http://weather.example.com/getWeather.php/Miami/temperature. The service could then return something like <temperature>89</temperature>. Normally, either XML or JSON data formats should be used, and the service should return a Content-Type header indicating the format. HTTP GET is convenient for debugging, because you can issue this request by simply typing the URL into the browser. Another useful property of HTTP GET is that the service may return optional cache control headers that indicate to the client whether (and for how long) the data may be cached – for example, the weather service may indicate that the temperature data is valid for 1 hour.

Adding new data is usually accomplished using the HTTP POST verb. This can be used for services that perform external actions (rather than just return data), where caching is undesirable. For example, suppose you are creating a service that can send SMS messages to mobile phones. Your “resources” would then be the target mobile phones, represented, for example, by http://sms.example.com/SendSms.php?phone={PhoneNumber}. To send an SMS, a client application would issue an HTTP POST to such a resource – for example, http://sms.example.com/SendSms.php?phone=800-555-1212. In the body of the HTTP POST, it would send something like <Message>Hello</Message>, and the service would respond with something like <Result>SentSuccessfully</Result>. Again, XML and JSON are common formats (both for the HTTP POST body and for the server response), and Content-Type is typically used to indicate the format (especially if multiple formats are supported).

How WebServius Supports REST

In the current version, WebServius acts simply as an HTTP gateway. It relays HTTP requests from the subscriber to your service, trying to change them as little as possible. It then takes your service’s reply, and relays it back to the subscriber, again trying to change as little as possible. WebServius does not currently cache any data, and does not read the contents of the message bodies.

Here is an example: Suppose a subscriber issues an HTTP request to http://svc.webservius.com/v1/acme/weather/getWeather.php/Miami/temperature?wsvKey=abc123. WebServius gets this request, and first validates the secret key (it makes sure that a subscriber with the key abc123 in fact has the right to call the weather service from the acme provider). WebServius then forwards the request to the provider – e.g. to http://weather.example.com/getWeather.php/Miami/temperature. The forwarded request has the same HTTP verb (GET, POST, etc.), the same message body, and the same HTTP headers as the original request.

When the provider responds with <temperature>89</temperature>, WebServius forwards this response to the subscriber. The forwarded response has the same message body, same status code, and same HTTP headers as the original response. WebServius does not care what format the message body is in (it does not have to be valid XML or JSON or any other format), and it ignores caching headers (just passes them along as-is to the subscriber).

Once you add a REST service to WebServius, you may define several “operations”, defined by URL patterns. For example, suppose you add a service with the base address http://weather.example.com/, and define two operations: getWeather.php/*/temperature for getting the temperature, and getWeather.php/*/windSpeed for getting the wind speed. You can then set different pricing and metering for each operation (for example, make the wind seed operation twice as expensive as the temperature operation). You can also use the “Access Policies” feature to limit access to certain operations for certain subscribers.

Due to the nature of the HTTP protocol, some modification of request and response messages is inevitable. Also, some of the more advanced HTTP features are not supported by WebServius and may result in messages being rejected. None of this should impact most REST services, but full documentation will be made available in the main WebServius help section.

Support for Other Service Types (XML-RPC, SOAP, etc.)

As mentioned above, WebServius simply acts as an HTTP gateway. It does not actually do anything “REST”ful with the messages it relays between the subscribers and your service, other than (1) extracting the “wsvKey” URL parameter, and (2) figuring out the service operation based on a URL pattern. So, WebServius can support any service type using its REST support, as long as the client can pass in the secret key as a “wsvKey” URL parameter, and as long as the operation can be determined from the URL (or if you don’t need to separate your service into multiple operations). In particular, XML-RPC services can be supported very well (in fact, to some developers the line between REST and XML-RPC is blurry or non-existent). SOAP services can also be supported in this limited fashion, as long as multiple operation support is not needed. However, WebServius is planning on adding much more extensive SOAP support in the future, with fully automated WSDL generation for subscribers, SOAP header authentication, and multiple operation support based on operations described in the WSDL. If you are planning to do a significant amount of work with SOAP services through WebServius, please contact us directly.