All Hackystat 8.x services communicate with each other using an API based upon REST architectural principles. In a nutshell, this means that all Hackystat data can be referenced using URLs, and can be manipulated using the HTTP protocol methods such as PUT, GET, POST, HEAD, and DELETE.

This document provides a specification of the "external" API to the SensorBase, in other words, it should provide everything you need to know in order to send data to this SensorBase and get data from it.

If you are using Java to communicate with the SensorBase, then you will be interested in the SensorBaseClient class, which provides a convenient Java API that encapsulates the HTTP call/response process and performs bidirectional translation between XML and Java class representations.

The REST architectural style begins with the concept of a "resource" which is an entity that can be "named" using an URI, and which has one (or more) "representations". Currently, the only representation supported is XML, although HTML representations for browser-based display of resources is a future possible enhancement.

The following table summarizes the REST API for this service. Note that this table does not specify any payload that must be associated with a request, nor does it include parameters that might be required for authorization or other purposes. For readability, the resource type associated with the operation is boldfaced, and a space is inserted before each URL parameter in order to facilitate line breaks.

Method	URI	Effect
GET	{host}/sensordatatypes	Return an index of all SDT resource names
GET	{host}/sensordatatypes/{sensordatatypename}	Return a representation of the named SDT resource
PUT	{host}/sensordatatypes/{sensordatatypename}	Create a representation of the named SDT resource
DELETE	{host}/sensordatatypes/{sensordatatypename}	Delete the named SDT resource
GET	{host}/projects	Return an index of all Project resource names
GET	{host}/projects/{user}	Return an index of all Project resource names associated with this User
GET	{host}/projects/{owner}/{projectname}	Return a representation of the named Project resource
GET	{host}/projects/{owner}/{projectname}/sensordata	Return an index of all Sensor Data resource names in this Project.
GET	{host}/projects/{owner}/{projectname}/sensordata?startTime={timestamp} &endTime={timestamp}	Return an index of all Sensor Data resource names in this Project between the startTime {timestamp} and the endTime {timestamp}.
GET	{host}/projects/{owner}/{projectname}/sensordata?sdt={sdt} &startTime={timestamp} &endTime={timestamp}	Return an index of all Sensor Data resource names in this Project between the startTime {timestamp} and the endTime {timestamp} with sensor data type {sdt}.
GET	{host}/projects/{owner}/{projectname}/sensordata?sdt={sdt} &startTime={timestamp} &endTime={timestamp} &tool={tool}	Return an index of all Sensor Data resource names in this Project between the startTime {timestamp} and the endTime {timestamp} with sensor data type {sdt} that were generated by {tool}.
GET	{host}/projects/{owner}/{projectname}/sensordata?startTime={timestamp} &endTime={timestamp} &startIndex={startindex} &maxInstances={maxinstances}	Return an index of Sensor Data resource names in this Project between the startTime {timestamp} and the endTime {timestamp}, starting at index {startindex}, with a maximum of {maxinstances} index entries.
GET	{host}/projects/{owner}/{projectname}/summary?startTime={timestamp} &endTime={timestamp}	Return a ProjectSummary for this Project between the startTime {timestamp} and the endTime {timestamp}.
GET	{host}/projects/{owner}/{projectname}/summary?startTime={timestamp} &numDays={numdays}	Return a MultiDayProjectSummary for this Project containing ProjectSummary instances for the specified number of days.
PUT	{host}/projects/{owner}/{projectname}	Create a representation of the named Project resource
POST	{host}/projects/{owner}/{projectname}/invitation/accept	Moves the authenticated user (not the {owner}) from the Invitations list to the Members list.
POST	{host}/projects/{owner}/{projectname}/invitation/decline	Deletes the authenticated user (not the {owner}) from the Members or Invitations list.
POST	{host}/projects/{owner}/{projectname}/rename/{newprojectname}	Renames {projectname} to {newprojectname}.
DELETE	{host}/projects/{owner}/{projectname}	Delete the named Project resource
GET	{host}/users	Return an index of all User resource names
GET	{host}/users/{user}	Return a representation of the named User resource
HEAD	{host}/users/{user}	Provides a lightweight way for services to check the authentication credentials of a User.
POST	{host}/users/{user}	Update the representation of the named User
DELETE	{host}/users/{user}	Delete the named User resource
GET	{host}/register	Serve an HTML page with a form allowing registration of a User.
POST	{host}/register	Register a User.
GET	{host}/sensordata	Return an index of all Sensor Data resource names
GET	{host}/sensordata/{user}	Return an index of all Sensor Data resource names for this User
GET	{host}/sensordata/{user}?sdt={sensordatatype}	Return an index of all Sensor Data resource names for the named SDT and User resources
GET	{host}/sensordata/{user}?lastModStartTime={tstamp} &lastModEndTime={tstamp}	Return an index of all Sensor Data resource names for the named user that have been received by the SensorBase between the two timestamps.
GET	{host}/sensordata/{user}/{timestamp}	Return a representation of the named Sensor Data resource
PUT	{host}/sensordata/{user}/{timestamp}	Create a representation of the named Sensor Data resource
PUT	{host}/sensordata/{user}/batch	Create a representation of the collection of Sensor Data resources sent as an XML SensorDatas payload
DELETE	{host}/sensordata/{user}/{timestamp}	Delete the named Sensor Data resource
GET	{host}/ping	Return the "ping representation" of this service, which is the string "SensorBase"
GET	{host}/ping?user={user} &password={password}	If {user} and {password} are valid credentials, returns "SensorBase authenticated"
PUT	{host}/db/table/compress	Invoke the database "compress" command (if supported) on all tables to conserve disk space.
PUT	{host}/db/table/index	Ensure that the latest set of indexes for all database tables are available on this repository.
GET	{host}/db/table/{table}/rowcount	Return an integer indicating the number of rows in the specified table.

The remainder of this document is organized as follows.

Section 2.0 presents the specification of the resources that are managed using this SensorBase: Sensor Data, Sensor Data Type, User, Project, Ping, and Database (db). It provides a high-level overview of the structure and purpose of these resources without going into detail on how these resources are manipulated using HTTP calls.

Section 3.0 presents the implementation of these resources, including the specifics of the HTTP methods, their parameters, return values, authorization, caching, and so forth.

2.0 Resource Design

This SensorBase supports the following resource types: Sensor Data, Sensor Data Type, Project, and User.

2.1 Resource Design: Sensor Data

Each Sensor Data resource instance represents an "atomic" unit of software engineering process or product data.

2.1.1 Sensor Data URI Specification

Sensor Data resources are named using the following URI specification:

{host}/sensordata/{user}/{timestamp}

Where:

element	description	example
{host}	the address of a SensorBase server	http://dasha.ics.hawaii.edu:9876/sensorbase
{user}	the email address of a User resource.	johnson@hawaii.edu
{timestamp}	An XmlSchema dateTime indicating the time instant that this sensor data was collected with millisecond accuracy	2007-04-30T09:00:00.000

So, an example Sensor Data URI is:

http://dasha.ics.hawaii.edu:9876/sensorbase/sensordata/johnson@hawaii.edu/2007-04-30T09:00:00.000

Some implications of this URI specification are:

All sensor data must be associated with a previously defined User.
For a given user, there cannot be two sensor data resource instances with the same timestamps.

2.1.2 Sensor Data Contents

Each Sensor Data resource contains the following fields:

field name	description	example
Timestamp	An XmlSchema dateTime indicating the time at which this sensor data was generated.	2007-04-30T09:00:00.000
Runtime	An XmlSchema dateTime enabling "bundling" of sensor data generated at the same time.	2007-04-30T09:00:00.000
Tool	A string identifying the tool that generated this sensor data.	Eclipse
SensorDataType	In response to a GET, this field will contain a URI identifying the sensor data type resource associated with this data. When composing the payload for a PUT, this field should contain the name of a currently defined sensor data type.	For GET: http://dasha.ics.hawaii.edu:9876/sensorbase/sensordatatypes/Commit For PUT: Commit
Resource	A URI indicating the resource (file, website, etc.) on which this sensor data was collected.	file://home/johnson/svn/Foo/build.xml
User	In response to a GET, this field will contain a URI indicating the user resource that "owns" this sensor data. When composing the payload for PUT, this field must contain the email of a currently defined user.	For GET: http://dasha.ics.hawaii.edu:9876/sensorbase/users/johnson@hawaii.edu For PUT: johnson@hawaii.edu
Properties	A set of key-value string pairs containing domain-specific sensor data and/or meta-data	{SLOC=10, LOC=20}

Note that some of the key-value pairs in the Properties field will be "required" by the SDT associated with this sensor data.

2.2 Resource Design: Sensor Data Type (SDT)

The Sensor Data Type (SDT) resource specifies the structure of domain-specific sensor data. SDTs are used to support consistent, generic analyses on sensor data regardless of what tool generated the data. For example, an SDT called "UnitTest" might require any tool that sends data of that type to provide a property called "Result" whose value is either "Passed" or "Failed". This enables a generic analysis over UnitTest data that computes the number of tests invoked in a day and the percentage that passed, and which can generate that analysis regardless of the tool that generated the data, or even when multiple different tools generate sensor data of that type.

Hackystat Version 7 provides examples of 15 sensor data types and their required and optional fields, as documented in Chapter 25. Sensor Data Types.

Currently, the SensorBase will not reject sensor data that does not conform to its declared Sensor Data Type. In a future version, we will enhance sensor data retrieval mechanisms with a "compliant" option that will do this checking.

2.2.1 SDT URI Specification

SDT resources can be named using the following URI specification:

{host}/sensordatatypes/{sensordatatypename}

Where:

element	description	example
{host}	the address of a SensorBase server	http://dasha.ics.hawaii.edu:9876/sensorbase
{sensordatatypename}	the name of an SDT	UnitTest

So, an example SDT URI is:

http://dasha.ics.hawaii.edu:9876/sensorbase/sensordatatypes/UnitTest

2.2.2 SDT Contents

An SDT resource provides the following fields:

field name	description	example
Name	the name of this SDT	UnitTest
Description	the intended meaning of sensor data of this type	Represents the invocation and results of a single unit test
RequiredFields	key-value pairs where keys are the required field names and the values are a description of the field	{Result=Should be either "Passed" or "Failed"}
Properties	A set of key-value string pairs containing SDT meta-data	{Version=2.1}

Some implications of this representation are:

There are no required Properties.
SDT names are unique across a SensorBase server.

2.3 Resource Design: Project

A Project resource names a subset of sensor data corresponding to a group of Users, a time interval, and a "URI Pattern".

2.3.1 Project URI Specification

Project resources can be named using the following URI specification:

{host}/projects/{owner}/{projectname}

Where:

element	description	example
{host}	the address of a SensorBase server	http://dasha.ics.hawaii.edu:9876/sensorbase
{owner}	the email address of the User resource who owns this Project	johnson@hawaii.edu
{projectname}	the name of this Project resource.	Jupiter-3.3

So, an example Project URI is:

http://dasha.ics.hawaii.edu:9876/sensorbase/projects/johnson@hawaii.edu/Jupiter-3.3

Some implications of this representation are:

Project names must be unique on a per-User basis.

2.3.2 Project Contents

A Project resource contains the following fields:

field name	description	example
Name	The name of this Project	Jupiter-3.3
Description	A textual description of this Project	Release 3.3 of the Jupiter code review plugin for Eclipse.
StartTime	A timestamp representing the start of the Project	2006-01-31T00:00:00.000
EndTime	A timestamp representing the end of the Project	2007-01-20T00:00:00.000
Owner	In response to a GET, this field will contain a URI corresponding to the Owner of this Project. When composing the payload for a PUT, this field should contain the email address of the owner.	For GET: http://dasha.ics.hawaii.edu:9876/sensorbase/users/johnson@hawaii.edu For PUT: johnson@hawaii.edu
Members	In response to a GET, this field contains a set of User URIs. When composing the payload for a PUT, this field should contain a list of user email addresses.	For GET: {http://dasha.ics.hawaii.edu:9876/sensorbase/users/johnson@hawaii.edu, http://dasha.ics.hawaii.edu:9876/sensorbase/users/hongbing@hawaii.edu} For PUT: {johnson@hawaii.edu, hongbing@hawaii.edu}
Invitations	In response to a GET, this field contains a set of User URIs. When composing the payload for a PUT, this field should contain a list of user email addresses.	For GET: {http://dasha.ics.hawaii.edu:9876/sensorbase/users/johnson@hawaii.edu, http://dasha.ics.hawaii.edu:9876/sensorbase/users/hongbing@hawaii.edu} For PUT: {johnson@hawaii.edu, hongbing@hawaii.edu}
Spectators	In response to a GET, this field contains a set of User URIs. When composing the payload for a PUT, this field should contain a list of user email addresses.	For GET: {http://dasha.ics.hawaii.edu:9876/sensorbase/users/johnson@hawaii.edu, http://dasha.ics.hawaii.edu:9876/sensorbase/users/hongbing@hawaii.edu} For PUT: {johnson@hawaii.edu, hongbing@hawaii.edu}
UriPatterns	A set of URI Patterns	{file:///Jupiter/}
Properties	A set of key-value string pairs containing Project meta-data	{TDD-Group=true}

Note that the Sensor Data specified by a Project definition is the logical "AND" of the time interval, Owner plus Members, and UriPatterns.

2.3.3 The Default Project

Every user has an implicitly defined Project called "Default" that is defined to encompass all of their personal data ever collected. This Project is named "Default" and is defined at the time of User registration.

The Default project representation is generated by the system and cannot be edited by users.

2.3.4 Invitations and the Membership process

The owner of a Project can "invite" other Hackystat users to become "Members" of this project. When a user is a Project Member, that means that their data can be combined with the Owner and other Member data to support aggregate analyses.

When a user is on the Invitations list, that means that they can retrieve and view the Project definition, but their sensor data will yet not be included in analyses. For this to happen, they must "accept" the invitation, which removes them from the Invitations list and adds them to the Members list.

The "accept" URI specification is:

{host}/projects/{owner}/{projectname}/invitation/accept

Users on the Members or Invitations lists can remove themselves at any time by "declining". The "decline" URI specification is:

{host}/projects/{owner}/{projectname}/invitation/decline

Note that the user accepting or declining is not, by definition, the {owner} in the URL.

2.4 Resource Design: User

A User specifies an "actor" in the software development environment. Usually, each User corresponds to a developer, though there may be non-human Users, such as automated Build processes, that could have their own accounts and generate data that is sent as part of a Project.

2.4.1 User URI Specification

User resources can be named using the following URI specification:

{host}/users/{user}

Where:

element	description	example
{host}	the address of a SensorBase server	http://dasha.ics.hawaii.edu:9876/sensorbase
{user}	an email address indicating the user	qzhang@hawaii.edu

So, an example User URI is:

http://dasha.ics.hawaii.edu:9876/sensorbase/users/qzhang@hawaii.edu

2.4.2 User Contents

The User resource contains the following fields:

field name	description	example
Email	The email address of this user	qzhang@hawaii.edu
Password	A password for this user	changeMe1234
Role	The type of user ("admin" or "basic")	basic
Properties	A set of key-value string pairs containing User meta-data	{DesktopPrefs=Google}

Note that all Properties are optional.

2.5 Resource Design: Ping

The Ping resource simply represents the availability of this service.

2.6 Resource Design: Database (db)

The Database resource provides limited ability to interact with the underlying relational database associated with this repository.

3.0 Resource Implementation

The previous section provided overviews of the resources supported by this SensorBase.

This section shows how to create, retrieve, modify, and delete those resources. It also includes details on the XML representation of the resources, and the possible HTTP status codes that could be returned from a request.

3.0.1 Access Control Levels

The SensorBase uses HTTP Basic authentication to support access control. The SensorBase supports the following types of access control: None, AnyUser, TheUser, ProjectOwner, ProjectOwnerOrMember, ProjectOwnerOrMemberOrInviteeOrSpectator, and Admin.

Access Control Level	Definition
None	No authentication is required. The only SensorBase requests that do not require authentication are the ping and the registration requests.
AnyUser	The operation requires the client to authenticate as a User in the SensorBase. For example, GET {host}/sensordatatypes enforces AnyUser access control.
TheUser	The User specified in the URI must be the same as the User specified in the authentication credentials. For example, GET {host}/projects/{user} enforces TheUser access control, which means that if a client submits {host}/projects/johnson@hawaii.edu, then the client must also submit authentication credentials for johnson@hawaii.edu. Note that a client authenticated as the Admin user (as specified in the sensorbase.properties file) is also allowed to do these operations. For example, if the admin is hongbing@hawaii.edu, then a client authenticated as hongbing@hawaii.edu would be able to GET {host}/projects/johnson@hawaii.edu.
ProjectOwner	The authenticated user must be the Project owner. For example, PUT {host}/projects/johnson@hawaii.edu/MyProject requires the authenticated user to be johnson@hawaii.edu, or the Admin.
ProjectOwnerOrMemberOrSpectator	The authenticated user must be the Project owner or one of the Project Members or Spectators. For example, GET {host}/projects/qzhang@hawaii.edu/MyProject/sensordata requires the authenticated user to be the Owner or a Member.
ProjectOwnerOrMemberOrInviteeOrSpectator	The authenticated user must be the Project owner, or one of the Project Members, or one of the Project invitees, or one of the Project spectators. For example, GET {host}/projects/kagawaa@hawaii.edu/MyProject requires the authenticated user to be either the Project Owner, or a Member, or an Invitee, or a Spectator.
ProjectInvitee	The authenticated user must be one of the Project invitees. For example, POST {host}/projects/austen@hawaii.edu/ProjectFoo/invitations/accept requires the authenticated user to be on the Invitation list for this Project.
Admin	The authenticated user must be the Admin (as specified in the sensorbase.properties file). For example, PUT {host}/sensordatatype/{sensordatatypename} requires the Admin access control level, as only Administrators are allowed to define sensor data types.

3.0.2 Default Implementation Constraints

Hackystat provides an embedded Derby database implementation for storage and retrieval of this information. This implemention currently imposes the following constraints on the sizes of certain fields:

Element	Maximum size (characters)
Email (account) name	64
Password	128
Sdt Name	64
Project Name	128
Tool Name	64
Resource URI	512
Overall Sensor Data instance size (including all properties), in XML	32,000

The following sections present the detailed description of the above operations.

3.1 Resource Implementation: Sensor Data Type

3.1.1 GET {host}/sensordatatypes

Returns an index of all sensor data type resource names. For example, given

GET http://dasha.ics.hawaii.edu:9876/sensorbase/sensordatatypes

An example return value is:

<?xml version="1.0"?>
<SensorDataTypeIndex>
 <SensorDataTypeRef Name="UnitTest" href="http://dasha.ics.hawaii.edu:9876/sensorbase/sensordatatypes/UnitTest"/>
 <SensorDataTypeRef Name="DevEvent" href="http://dasha.ics.hawaii.edu:9876/sensorbase/sensordatatypes/DevEvent"/>
</SensorDataTypeIndex>