The Microsoft .NET framework offers a flexible and robust stack on which to build rich client-server applications. In many cases, interfacing with a .NET server application would require a matching managed .NET client application, but this is not really necessary. If we create a .NET web service that conforms to well-known REST principles, we can define a combination of HTTP methods and URIs to produce a rich API that any web-enabled client can interface with. In effect, the RESTful API becomes the .NET “configuration” that the client and server shares in order to correctly communicate across the HTTP connection.
In this example, we will show you how easy it is to interface the Translator with a typical Windows Communication Foundation (WCF) stand-alone service that is a) written in C#, and b) configured as an endpoint for a number of URIs and HTTP methods. You could build a similar service in ASP.NET using C# or Visual Basic. Either can be hosted on a dedicated IIS server or run stand-alone.
Note: This example does not demonstrate a full, stateful REST interface, but it could easily be extended to offer this functionality.
Client
The client is a single Translator script that invokes a series of URIs (using net.http functions) to get normalized responses back from the server.
Warning: The code itself is relatively straightforward, but forming the HTTP headers correctly is key to your success. The URI, HTTP method, and headers have to match exactly that which is defined in the service before the non-trivial examples will work. In most cases, a failure to conform to the expected format of a request will result in an HTTP 400 or 415 error from the server.
In the case of HTTP POST operations, we have made the decision to use Lua-friendly JSON as the transport for requests and responses. This makes it easy to construct headers and parse returns. Similarly, HTTP PUT request and responses should be wrapped as either JSON or XML.
This script simply calls a number of URIs with the correct payload, then parses out the responses. Errors are logged by the Translator.
Server
The server is at .NET 3.5-based WCF stand-alone service written in C# (although any version of .NET from 3.0 through to 4.5 should work). The easiest way to deploy this is directly from Microsoft Visual Studio, where it can be run as a self-hosted IIS instance.
The service (see Service.cs) defines the API for various actions that themselves are a combination of HTTP method and URI. Conforming clients should be able to make requests to the service and get well-formed HTTP data back (or an error).
Conclusion
.NET is a rich development stack that offers a lot of power and flexibility (including the ability to service non .NET clients). One way to offer services to unmanaged clients is via a RESTful HTTP interface, where a combination of URIs and HTTP methods allow us to invoke arbitrary functions via a standard, published API. The only configuration that needs to be shared is the definitions of the API. Participating clients (like the Translator) only need to send conforming requests with the correct headers in order to get well-formed HTTP responses, which can then be processed as one would any JSON or XML data.