OpenWGA 7.5 - OpenWGA Concepts and Features

An introductory walkthrough

When making the first steps with OpenWGA REST service it is best to use some visual client for HTTP REST services and actually browser the service with it. If you use the Chrome web browser from Google you could use its Dev HTTP Client app for example. RESTClient is a potential counterpart addon for Firefox.

Inside your client of choice (and after Enabling REST support for at least one application) just head to the root page of the OpenWGA REST Service for your server under path /services/rest/v1 and execute a simple GET request on it.

As the REST service defaults to put out JSON formatted data you should see something like the following as response:

Here you can already learn some basics about the "envelope" that is returned by OpenWGA REST service on all occasions:

• It returns a property "status" denoting the success of the operation. You might want to test this first before doing anything with the rest of the content. In case of an error there is also a property "error" containing detail information.
• A property "self" always points back to the regular URL of the resource that served the response. This time it is the same as we called.
• A property "resource" contains the actual data of the resource we requested. This is not too thrilling this time as we only get the "type" of the resource (which is the "root resource" of the service) plus the OpenWGA server version.
• A property "refs" contains references that go from the current resource/collection to other resources/collections. It is itself categorized into references of different names which are properties of the object under "refs". Here we only get one reference named "dbs"  which identifies itself as pointing to a collection.

In REST you always either address resources or collections via URL:

• A resource is a single entity of data that will show this data under property "resource" and put out its outgoing references to dependent resources or collections under property "refs". 
• A collection is a list of references to resources. It will have no "resource" property but put out this collection of references also under property "refs".

Now we can simply take this URL from the object in "dbs" - in the case here "href":"http://localhost:8080/services/rest/v1/dbs" - and make a GET request on it to actually retrieve the collection. The result should be something like this:

We see that this request is quite similar to the one before in its general structure. However there are some differences:

• We now have a property "parentResource"  pointing to the root. This is always the "way up" in the hierarchy of the API to get to the respective parent resource.
• There is no "resource" property any more because we are adressing a collection no resource.
• The "refs" property is still there, but now it contains a "collection" property actually containing the data of the collection "dbs". This is an array containing objects that represent references to the individual database resources that are REST-enabled. The "id" on each contained object equals the database key of one of the apps where you enabled REST APIs.

Here we can again take one of those URLs from the "dbs" collection to fetch one of these resources. Our result here is:

This is now the resource representation of the app "site". We see some data on the "resource" object, mainly the login information of the current user. We also see under property "refs" the references that go from this resource to other resources or collections. In this case the "CMS API" resource.

If you see less data then the cause is most likely that your database is not accessible anonymously. Your "accessLevel" property should have the value 0, meaning "No access". You need to login to the REST service with some valid user account. The OpenWGA REST web service supports basic HTTP authentication, so you should add an "Authorization" HTTP header to your requests having your login. Both REST clients noted above have convenience functions to add username and password to this header in cleartext. Here is a screenshot of this functionality in Chromes HTTP Dev Client, which can be invoked by simply adding the header and clicking on the edit symbol that appears next to it:

Under the "refs" property of the database resource you see references to every REST API that you enabled for this app. As a REST API ist also only a resource published by the REST server it has its own URL by which you can access it. In our example only the CMS API is available under URL "http://localhost:8080/services/rest/v1/dbs/site/cms". Calling this URL will show you the CMS API resource's data and references:

While the "resource" here has no interesting data to offer there are various references where you could go from here. Now you can basically explore what the CMS REST API has to offer continuing to follow those URLs to the resources that the API has to offer. By that you can learn it's structure and how you can reach the data that you want to query.

Rules of HTTP Method usage

The OpenWGA REST web service closely adheres to the guidelines for REST/ROA services about the usage of HTTP methods. What actions are exactly available to which URLs is dependent on the API. However these rules are generally used: