import java.text.MessageFormat;

import javax.ws.rs.WebApplicationException;
import javax.ws.rs.client.*;
import javax.ws.rs.core.MediaType;

import com.starteam.rest.Resource; // this class is available from the REST .war

public class SampleClient {

public SampleClient() {
}

static String address = "http://localhost:8080/MicroFocusHubRESTService/rest";
static String logon = "/users/logon?username={0}&password={1}";
static String users = "/users;sessionid={0}";
static String projects = "/projects;sessionid={0}";
static String views = "/views/projectid={0};sessionid={1}";
static String user = "/users/userid={0};sessionid={1}";
static String logoff = "/users/logoff;sessionid={0}";
static String viewmembers = "/viewmembers/projectid={0}/viewid={1}/typeid={2};sessionid={3}";
static String types = "/types;sessionid={0}";
static String create = "/viewmembers/projectid={0}/viewid={1}/typeid={2}/folderid={3};sessionid={4}";
static String read = "/viewmembers/projectid={0}/viewid={1}/typeid={2}/viewmemberid={3};sessionid={4}";
static String update = "/viewmembers/projectid={0}/viewid={1}/typeid={2};sessionid={3}";
static String delete = "/viewmembers/projectid={0}/viewid={1}/typeid={2}/viewmemberid={3};sessionid={4}";

static String sessionid = "";

public static void main(String[] args) throws Exception {
Client c = ClientBuilder.newClient();
try {
String url = address MessageFormat.format(logon, "Administrator", "Administrator");
sessionid = c.target(url).request(MediaType.TEXT_PLAIN).get(String.class); // returns a unique sessionID GUID describing this user session

url = address MessageFormat.format(types, sessionid);
Resource[] tt = c.target(url).request(MediaType.APPLICATION_XML).get(Resource[].class); // query the set of all types with their metadata
int foldertypeid = -1;
int changerequesttypeid = -1;
for (int i = 0; i < tt.length; i ) {
if (tt.get("Name").equals("Folder"))
foldertypeid = Integer.valueOf(tt.get("ResourceID"));
else if (tt.get("Name").equals("ChangeRequest"))
changerequesttypeid = Integer.valueOf(tt.get("ResourceID"));
}
url = address MessageFormat.format(projects, sessionid);
Resource[] pp = c.target(url).request(MediaType.APPLICATION_XML).get(Resource[].class); // query the set of projects on the server (returns each project id/name
url = address MessageFormat.format(views, pp[0].get("ResourceID"), sessionid); // query the views of the first project found
Resource[] vv = c.target(url).request(MediaType.APPLICATION_XML).get(Resource[].class);
url = address MessageFormat.format(viewmembers, pp[0].get("ResourceID"), vv[0].get("ResourceID"), foldertypeid, sessionid)
Resource[] ff = c.target(url).request(MediaType.APPLICATION_XML).get(Resource[].class); // query the folders of the root view

Resource cr = new Resource(); // create a new ChangeRequest
cr.put("Description", "a new enhancement"); // assign a value to the description property
cr.put("Synopsis", "the synopsis of this enhancement"); // assign a value to the synopsis property

url = address MessageFormat.format(create, pp[0].get("ResourceID"), vv[0].get("ResourceID"), changerequesttypeid, ff[0].get("ResourceID"), sessionid);
c.target(url).request(MediaType.APPLICATION_XML).accept(MediaType.APPLICATION_XML).post(Entity.xml(cr)); // create/save a ChangeRequest

url = address MessageFormat.format(viewmembers, pp[0].get("ResourceID"), vv[0].get("ResourceID"), changerequesttypeid, sessionid);
Resource[] cc = c.target(url).request(MediaType.APPLICATION_XML).get(Resource[].class);
Integer crid = Integer.valueOf(cc[0].get("ResourceID"));

url = address MessageFormat.format(read, pp[0].get("ResourceID"), vv[0].get("ResourceID"), changerequesttypeid, crid, sessionid);
cr = c.target(url).request(MediaType.APPLICATION_XML).get(Resource.class); // verify that we can query the changerequest by ResourceID

cr.put("Description", "update the description");
cr.put("Synopsis", "update the synopsis");
url = address MessageFormat.format(update, pp[0].get("ResourceID"), vv[0].get("ResourceID"), changerequesttypeid, sessionid);
c.target(url).request(MediaType.APPLICATION_XML).accept(MediaType.APPLICATION_XML).put(Entity.xml(cr)); // update/save the ChangeRequest

url = address MessageFormat.format(delete, pp[0].get("ResourceID"), vv[0].get("ResourceID"), changerequesttypeid, crid, sessionid);
c.target(url).request().delete(); // remove the ChangeRequest

url = address MessageFormat.format(logoff, sessionid); // logoff from this session
c.target(url).request().get();
} catch (WebApplicationException ex) {
System.out.println(ex.getMessage());
System.out.println(ex.getResponse().readEntity(String.class));
}
}

}

Notes...

Each Resource object returned is described as a Map of string key's to string values.

The keys are property names of the corresponding type schema on the StarTeam platform, their values are String representations of their matching underlying metadata types.

Note that every map contains a generic key value pair called a "ResourceID".

ResourceIDs are unique server wide descriptors of the underlying artifacts they represent.

So, a User ResourceID is the StarTeam UserID, a Project ResourceID is a projectID, a ChangeRequest ResourceID is a ViewMemberID, etc...

The combination tuple {ResourceID, TypeID} can pretty much locate any starteam artifact in the system.

For the sake of completeness, here is the source code for the Resource class

package com.starteam.rest;

import java.io.Serializable;
import java.util.HashMap;
import java.util.Map;

import javax.xml.bind.annotation.XmlElementWrapper;
import javax.xml.bind.annotation.XmlRootElement;

@XmlRootElement(namespace="")
public class Resource extends HashMap<String, String> implements Serializable {

/**
* Every resource has a unique "ResourceID" which is equivalent to the StarTeam id of the resource
* for example, project "ResourceID" is equal to project id.
* changerequest "ResourceID" is equal to viewmemberid
* client applications must send the resource id as part of the message
* for the artifact to be successfully recognized
*/
private static final long serialVersionUID = -2384489572937175702L;

public Resource() {
}

@XmlElementWrapper(name="structure")
public Map<String, String> getStructure() {
return this;
}

public String put(String key, String value) {
if (key == null || value == null ||
value.equals("{}") || value.contentEquals(Transformers.nullObject)
|| (value.startsWith("[Lcom.starteam.rest.Resource;@")))
return null;
return super.put(key, value);
}

}

I wrote the test example by leveraging the .class directly in my eclipse project.

However, any client side developer can leverage this class source definition (above) to achieve the same results.

The important takeaway is that the streaming 'signature' of STarTeam resources, embodied by this REST api

is a reasonably flat XML or JSON structure of key-value pairs.

The keys are property names, the values are String representations of the property values.

However,  if the values are themselves complex  data structural StarTeam types, then they are represented as Resource objects (i.e. a map of key-value pairs) 

a good example would be a StarTeam Enumerated Value or a StarTeam Link Value.

In this case, a higher level type (e.g. a Trace) maps a String key (e.g. SourceLinkValue) to a Resource, i.e a set of key value pairs themselves.