REST Web Services Overview

REST web services provide HTTP access to Jive SBS features. Through REST, or Representational State Transfer, these APIs expose application features to clients ranging from your browser to other Jive SBS instances.

Reading This Reference

As with other REST-style web services, methods here are each in one of four forms, similar to database operations.

GET -- Like a select statement, GET retrieves information, returning XML. The method's parameters are typically appended to the request URI as shown in the syntax examples.
POST -- You can use a POST method to create, update, or delete data. When calling POST, you pass in XML that contains your methods parameters.
PUT -- With a PUT, you can create or update data. As with POST, you pass in XML with your method's parameters.
DELETE -- Use a DELETE method to delete data. The method's parameters are typically appended to the request URI as shown in the syntax examples.

The method descriptions here give the method type (also known as the HTTP "verb,"), such as GET, PUT, POST, or DELETE. They also give the resource endpoint. The endpoint is merely the end of the resource URI, which begins with the URL of your Jive SBS instance and includes the general address of REST web services in Jive SBS. Taken together, the complete URI's form is what you should use when requesting resources. That form looks like this:

http://<host_name>:<port_number>/<context>/rpc/rest/<endpoint>

So if your domain was at example.com and you had code to find out if avatars were enabled, you might end up with a resource URI like the following:

http://example.com:8080/ourspace/rpc/rest/avatarService/isAvatarsEnabled

Example

Here's a brief client example in Java for getting a REST resource. REST services use basic authentication, so you'll need to pass in user credentials that have sufficient permission to get the resource you're requesting.

This example uses DOM4J and Apache's HttpClient, but there aren't any implementation restrictions on how you request the resource and manipulate XML parameter or return values.

import java.io.InputStream;

import org.apache.commons.httpclient.Credentials;
import org.apache.commons.httpclient.HttpClient;
import org.apache.commons.httpclient.UsernamePasswordCredentials;
import org.apache.commons.httpclient.auth.AuthScope;
import org.apache.commons.httpclient.methods.GetMethod;
import org.dom4j.Document;
import org.dom4j.io.OutputFormat;
import org.dom4j.io.SAXReader;
import org.dom4j.io.XMLWriter;

// Code omitted.

// Use apache commons-httpclient to create the request/response
HttpClient client = new HttpClient();
Credentials defaultcreds = new UsernamePasswordCredentials("joe_admin",
    "mypassword");
client.getState().setCredentials(AuthScope.ANY, defaultcreds);

// GET a community by its ID number, which is "1".
GetMethod method = new GetMethod(
    "http://example.com:8080/rpc/rest/communityService/communities/1");
client.executeMethod(method);
InputStream in = method.getResponseBodyAsStream();

// Use dom4j to parse the response and print nicely to the output stream
SAXReader reader = new SAXReader();
Document document = reader.read(in);
XMLWriter writer = new XMLWriter(System.out, OutputFormat
    .createPrettyPrint());
writer.write(document);

Note: To use any of the web services, you'll need to first enable web services for your Jive SBS instance. You can do that in the admin console at System > Settings > Web Services. On the Web Services page, enable the type of web services you want exposed, then click Save Settings.