Wombat provides a simple RESTful API to access heaps of funktions and services. As always, there is an article about REST at Wikipedia: http://en.wikipedia.org/wiki/REST
Yes, Wombat's REST interface acts like any other RESTful application. Still, there are a few bits and pieces worth to mention.
There are four protocoll primitives: GET, PUT, POST and DELETE. This is a subset of HTTP and they are used with resouces in order to fetch a resouce (GET), create one (PUT), change an existing one (POST) or remove (DELETE) it.
Resouces can be anything like files and folders or user sessions. In case of foldes, the meaning if GET, PUT, POST and DELETE is obvious: PUT creates a new folder. GET receives a list of the items in the folder, POST renames or moves the folder and DELETE wipes it out. In case of user sessions, the meaning is kind of abstract. GET means to fetch information about the current user's session. POST can be used to login and DELETE to logout. While PUT has not meaning at all.
Besides protocoll primitives, Wombat's REST-interface makes use of common HTTP-headers. All used headers are utillized the same way as defined in HTTP version 1.1. Please refer RFC 2616.
Wombat loves XML. Hence it's REST interface speaks XML both for in and output. In other words, asking for current login information results in XML as well as anything else. The XML response is unified and always consists of the root tag response and three children named status, data and error.
The status contains one of the words: ok, error or failed. This tag tells, whether the request was processes successfully. If it is ok, everything went fine and the server did what you asked for - e.g. delete a file. failed and error means that the the request could not processed as expected. error stands for technical issues - e.g. the request was send to the wrong URL or POST body was missing or not well formated. Hence errors always point to an issue in the programme itself (client or server). On the other hand there is the status failed. Failed means, thing did not come out as the user might have expected. For example: the user wants to change the email address in her profile. So she sends something like "POST /profile" with the new email address in post data. Accidently, she forgot the @-sign which renders the address invalid. Hence data falidation failes, the servers response status will be failed and the email address stays unchanged.
The REST interface reads XML input and writes XML output. Besides it also supports JSON for both input and output. In order to change response and request data type, HTTP-headers can be used.
Using the HTTP-header Accept allows to select response content-type. Use either text/xml for XML, or text/json for JSON
PUT and POST request usually also send data in request body. Again, the REST server supports XML and JSON. In this case, the HTTP-header Content-Type text/xml for XML, or text/json for JSON tells what it is.
In many cases, Wombat REST server answer is a list of things. List items are always in tag <item>. Please note, that children of the errors are always list items. The content in data may be a list of items, as well
Most of data send through XML tags are native string values. Therefore no special transformation applies. Strings are just UTF-8 encoded - as stated in XML and HTTP header.
Boolean values as such don't exists. They are represented by the integer values 0 and 1.
Of course, XML tags can be nested.
Wombat's REST-server sends an error in case the client don't send the HTTP-header User-Agent. It is strongly recommend to send something useful, like the programm's name, it's homepage URL and version number. The idea is to detect clients with known bugs and offer server-side workarounds.
Besides the REST-interface /auth, Wombat also supports HTTP-basic authentication. Hence, all GET requests can be done using a regular browser. Also, most HTTP-client libraries provide support for HTTP authentication, this features makes it realy simple to implement your own REST client.
Cookies are required! Actually, Wombat uses cookies to store user's session ids. Make sure your REST client handles cookies correctly or be prepared to funny results.
Also the REST-Server is capable to translate form validation errors and other messages. To set a proper language, please use HTTP-Header: Accept-Language Example: Accept-Language: de-de
The REST-Server also provides some debugging information. To aktivate it, simply sent the HTTP-Header X-Debug with the value 1 or 0 to switch it off.
There is a simple HTTP testing client in Wombat's test folder test/trial/rest/clientXml.php. This client allows you to send XML-requests and view responses. Therfore this client is pretty usefull during REST-service development and to see how Wombat's REST-server works.
By the way, there are more REST related testing tools in test/trial/rest/.
GET /
Wombat comes with a couple of REST services for general purpose. Use a simple HTTP GET / to get a list of available services.