txtr Reaktor

The RPC API

The RPC API consist of a set of methods, organized into logical blocks called "components" that may be accessed from the web through one of our three remote procedure call protocols. Each protocol has a way of mapping method names, parameters and return values onto an HTTP request.

Choosing the right protocol

First of all, you need to choose a protocol. Here are guidelines to help you choose what's right for you.

Use SOAP if you:

are about to do a Java client (as a JAX-WS client will be up and running in no time)
wish to reap the benefits of dynamic clients or code generation from WSDL
potentially want to access all of the API, even the complex bits
are on a platform that likes SOAP (like .NET) and are not afraid of the complexities and pitfalls of SOAP interoperability.

Use REST if you:

like to keep things simple
have an XML parser and an HTTP client at hand on any platform you happen to like
are aware of the fact that some API methods (i.e. for rights or metadata management) won't be callable through REST as they have complex signatures that simply can't be mapped to HTTP GET parameters

Use JSON if you:

are doing a JavaScript client
or don't like XML
are aware of the fact that some of the elegance of JSON RPC will break down when it comes to passing complex types to the Reaktor.

SOAP

SOAP is a standardized way of accessing web services. It's also a fairly complex one, and not everybody agrees that the standard is any good. Anyway, it's a standard, and it works pretty well for us. What a SOAP client basically does is this: It encodes objects to XML, sends an HTTP POST request to the server, and receives XML-encoded objects with the return values. A good client library will make all of this transparent to you, so all you see is a method that you can call in the language you're using, without knowing anything about all the XML magic going on in the background.

The methods and objects used by a SOAP server are described in a machine-readable format called WSDL. When doing a client, you normally tell your SOAP library the URL of the service's WSDL descriptor, and the client either generates code or a dynamic client for you.

The quality of the client library is very much the key factor here. Poor client libraries will lead to problems. There are very good libraries in the Java and .NET and worlds, PHP5 has a good one, too. We're not sure about other languages. The Python SOAP stuff was rubbish, by the way, last time we checked. Which is a pity, as we quite do like python.

We're using Document/Literal encoding. Make sure your client library does support document/literal. (And no, there's no point trying if it doesn't.)

Here are the URLs for the Reaktor API components:

Component	Methods for...	URL
WSAuth	authentication, de-authentication	http://txtr.com/WSAuthService/WSAuth?wsdl
WSDocMgmt	document handling, metadata	http://txtr.com/WSDocMgmtService/WSDocMgmt?wsdl
WSListMgmt	list handling	http://txtr.com/WSListMgmtService/WSListMgmt?wsdl
WSViewMgmt	txtr.com view management	http://txtr.com/WSViewMgmtService/WSViewMgmt?wsdl
WSSearchDocument	document search	http://txtr.com/WSSearchDocumentService/WSSearchDocument?wsdl

REST

RESTful web services are web services for the lazy man. Instead of POSTing all that complicated SOAP XML data to the server, you just do an HTTP GET that encodes the method call and the parameters in the URL and get back some XML. So whenever you use a client platform that has no (or only broken) support for SOAP, or you just want to do some very simple stuff, you'll probably want to go for REST. You'll have to do the XML parsing, though.

To make a REST call to the Reaktor, you do a GET to a URL like this:

http://txtr.com/rest/rpc?service=$componentName&method=$methodName¶m1=value1¶m2=value2...

A service parameter, specifying where to look for the method, a method parameter with the actual name of the method, and a number of method-specific parameters.

REST doesn't have the concept of interface descriptors (such as WSDL), so you will need to know what you are calling and what parameters are required by the methods you call. We have some methods documented on the starting points page.

You can also use the Expert API documentation - mapping the Components and Methods documented there to REST calls is pretty straightforward: The service parameter holds the name of the component sans the I - for IWSAuth that would be WSAuth, the name of the method is exactly as in the Expert API documentation, and all other parameters are simply HTTP key-value, where the parameter names are to be taken directly from the Expert API documentation.

Note that you cannot pass complex parameters to REST RPC. There are some methods in the API that do use complex type parameters, and you cannot call these via REST.
Lists of Strings work though, just comma-separate the values, like this: entry1,entry2,entry3
Maps of Strings also work, comma-separate the map entries and separate key and value by a colon, like this: key1:value1,key2:value2,key3:value3.
(Entries, keys and values must not contain commas or colons.)

There are special rules to obey when calling a search service (like WSDocumentSearch). You must make sure that only one of your calls is inside the Reaktor at any time. Your session will be disabled if you ever try to have two requests inside the Reaktor in parallel. If you cannot ensure that this condition is met, use http://txtr.com/rest/snycrpc instead of http://txtr.com/rest/rpc for the search calls, so violating requests will be kept back and eventually dropped.

JSON

JSON-RPC is a full-featured way of calling methods on the server. It doesn't use XML as an object transport protocol, but JSON. A JSON-encoded object is, basically, the JavaScript notation of that object, so doing an eval() on the JSONified object would create a living JavaScript object.

So, JSON is probably the way to go if you're doing a client in JavaScript. To call a Reaktor method via JSON-RPC, you might want to use script injection to GET an URL like this one:

http://txtr.com/json/rpc?json={"id":$id,"method":"$methodName","params":[$param1, $param2, ...]}

Where $id is a (random) request ID that will be included in the response (so you can tell concurrent requests apart), $methodName is something like "WSAuth.authenticateUserByName", and the params array contains method-specific parameters, encoded as JSON: Strings are strings, numbers are numbers, booleans are booleans, lists are arrays, hashes are objects, complex types are also objects.

You can add another parameter to the GET request, called callback, that will wrap the result in a JavaScript call. So, http://txtr.com/json/rpc?json={....}&callback=evaluateServerResult will return evaluateServerResult({"result":"some data from server"}), that, when injected into a script tag, will handle the result.

You can also POST the json String to http://txtr.com/json/rpc, but normally, your browser won't let you because of the same origin policy.

Notes on encoding:

There are some constant types in the API (such as ListType). In a JSON encoding, a constant value is passed to the API not as a String ("PRIVATE") but as an object with the property "name" that holds the constant value. (Like this: {"name":"PRIVATE"}).
In some rare circumstances, the Reaktor is not able to infer the type of complex parameters passed via JSON. This happens when a method is to be called that needs maps, or lists, of complex types or constants. When calling these methods, the JSON data structure passed to the Reaktor must contain some additional hints. The documentation of the respective methods in the Expert API documentation contains information on the hints that need to be added to parameters when the method is called via JSON.