Updated Jul 10, 2009 by myriam.l...@gmail.com
Labels:	Phase-Design

RestApiSpecification

Specifies the REST API for Linked Service Data

Introduction

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 Linked Service Data, in other words, it should provide everything you need to know in order to send data to this LinkedServiceData and get data from it.

This is a work in progress

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.

Authorization levels meaning:

Any - anyone can access
User - only the specified user can access
Admin - only the administer can access
Admin/User - only the administer or the specified user can access
AnyHUser - only the registered Hackystat users can access
Depends - the access depends upon privacy settings specified by the user

Since the SensorBase (upon which every hackystat service relies)alway requires to be registered users in order to access anything, I cannot implement an 'Any' access mode even if it's contemplated. So if you see 'Any' in the table below, consider that it's implemented as AnyHUser but in the future, as the SensorBase will allow this, it could be implemented as 'Any'.

The method is always 'GET' and that's why it's not specified in the table below.

Already implemented	Authorization Level	URI	Effect	Main Motivation
V	Admin	{host}/users	Return a collection including all the existing User profiles	Search for user's skills
V	Admin	{host}/projects	Return a collection including all the existing Project profiles	Search for projects with the same purposes and/or high data quality
V	AnyHUser	{host}/users	Return a collection including all the profiles belonging to users who want be retrievable by other Hackystat users	Search for user's skills
V	AnyHUser	{host}/projects	Return a collection including profiles of all the projects that want be visible to other Hackystat users	Search for projects with the same purposes and/or high data quality
V	Any	{host}/users	Return a collection including all the profiles belonging to users who want be visible to anyone	Search for user's skills
V	Any	{host}/projects	Return a collection including profiles of all the projects that want be visible to anyone	Search for projects with the same purposes and/or high data quality
V	Depends	{host}/users/{user}	Return the profile of the given user.	Search for user's skills
V	Depends	{host}/projects/{user}	Return a representation of the collection including all the existing Project resources descriptions associated with this User.	Search for projects with the same purposes and/or high data quality
V	Depends	{host}/projects/{owner}/{projectname}	Return a representation of the named Project resource.	Search for projects with the same purposes and/or high data quality



V	Admin/User	{host}/file/{user}/{project}/{fileFullPath}/{day}	file representation for a specific day (it includes complexity value plus LOC taken from DPD, plus coverage and coupling values).	Linkable to a SW development phase. Useful to maintain code, letting individuate issues in a particular file. Specifying a day you can monitor file changes before and after a code manipulation
V	Admin/User	{host}/devPhase/{user}/{project}/{phaseId}	Return a representation of the named software development phase.	Facility for project managers to monitor and design their projects. Each phase could be linked to frequent issues, files and developers involved
V	Depends	{host}/repository/{user}/{project}	Returns a represenation of the repository associated with the given project	Useful info for new project developers and sw maintainers. Can be linked to projects using the same kind of repository.
V	Admin/User	{host}/test/{user}/{project}/{testId}	Returns a representation of the test identified by the given id	This will include the test purpose (useful for project maintainers) and links to external tests having the same purpose
V	Any	{host}/issue/{issueId}	Return a representation of the named issue. This could be any kind of issue (also a 'code' issue).	links to info about this issue. A same issue can be collected in different projects and by sensors of different users; that's why only its id is specified rather than together with user and project names



		Main motivation for each resources listed below: info provided here are already provided by DPD, while here they're simply aggregated and provided as Linked Data. This because they can be useful to deeper investigate a user's work/skills that is only approximated (with average values) in user profiles.
V	Admin/User	{host}/commitment/{user}/{project}/{day}	dev-time and commits over only one day. Only the amount of dev-time and commits is reported because here the focus is on general 'user commitment'
V	Admin/User	{host}/commitment/{user}/{project}/{start}/{end}/{granularity}	dev-time and commits over only one day. E.g. it could be useful when someone checks for a developer having some skills but that also, has been active in the last month. Only the amount of dev-time and commits is reported because here the focus is on general 'user commitment'
V	Depends	{host}/command/{user}/{commandName}	Return a representation of the named command executed by the given user, including any result or parameter passed during execution and collected in the SensorBase within SD of 'Cli' SDT.
V	Admin/User	{host}/commit/{user}/{project}/{member}/{day}	Returns a collection of each of the single commit instances made by a specified member in a specified day (they should be more than one because commits having different summaries or related to different issues, cannot be aggregated).	You can understand immediately what changes have occurred after a commit and on which issues a developer is working on.
V	Admin/User	{host}/commit/{user}/{project}/{member}/{day}/{commitId}	Returns a representation of the single commit instance identified by the specified Id, including the amount of lines added, changed, deleted; the summary and a collection of issues to which it's related to. It's also specified how many commits are aggregated under this same Id becuase having the same summary and are related to the same issues.
V	Admin/User	{host}/build/{owner}/{project}/{member}/{start}/{end}/{granularity}	Returns the ratio between build successes and failures collected by the given user for the given project, between the given start and end time period, using the specified granularity
V	Admin/User	{host}/build/{owner}/{project}/{member}/{day}	Returns the ratio between build successes and failures collected by the given user for the given project, during the specified day
V	Admin/User	{host}/unitTest/{user}/{project}/{member}/{day}	Returns a represenation of the unit test successes and failures collected by the given project member during the given day
V	Admin/User	{host}/unitTest/{user}/{project}/{start}/{end}/{granularity}	Returns a represenation of the unit test successes and failures collected for the given project during the time period between the given start and end dates, using the specified granularity
V	Admin/User	{host}/codeIssue/{user}/{project}/{day}	Returns a representation of code issues encountered during the specified day
V	Admin/User	{host}/codeIssue/{user}/{project}/{start}/{end}/{granularity}	Returns a collection of those code issues encountered for the given project, during the time period between the given start and end dates, using the specified granularity



		Main motivation for each resources listed below: referenced within project profiles (every URI must be dereference-able).
V	Admin/User	{host}/codeIssue/{user}/{project}	Returns a representation of the amount of code issues encountered per month during development of the given project from the start date of a project till its end (or till now if not already terminated)
V	Admin/User	{host}/build/{owner}/{project}/	Returns a collection of ratio values between number of build successes and build failures colleveted byb all the involved developers per month, starting from the creation date of the specified project till now
V	Admin/User	{host}/commit/{user}/{project}	Returns a collection of commit frequencies per month from the start date of a project till its end (or till now if not already terminated)
V	Admin/User	{host}/coverage/{user}/{project}/	Returns a collection of coverage percentages per month starting from the creation date of the specified project
V	Admin/User	{host}/devTime/{user}/{project}/	Returns a collection of the average time spent by the given user developing, per month from the creation date of the specified project till its end (or till now if it's not yet terminated).
	Admin/User	{host}/unitTest/{user}/{project}	Returns a collection of the ratios between unit test successes and failures collected during development of the given project, per month from the creation date of the specified project till its end (or till now if it's not yet terminated).
V	Admin/User	{host}/unitTest/{user}/{project}	Returns a representation of the ratio between unit test successes and failures per month during development of the given project from the start date of a project till its end (or till now if not already terminated)
V	Admin/User	{host}/codeIssue/value/{owner}/{project}/{month}/{value}	Returns a representation of a particular instance of codeIssue characterized by the given amount of code issues collected for the given project, during the specified month
V	Admin/User	{host}/build/value/{owner}/{project}/{month}/{value}	Returns a representation of a particular instance of build characterized by the given amount of builds collected for the given project, during the specified month
V	Admin/User	{host}/commit/value/{user}/{project}/{month}/{value}	Returns a representation of a particular commit instance characterized by the given average commit frequency collected for the given project, during the specified month
V	Admin/User	{host}/coverage/value/{user}/{project}/{month}/{value}	Returns a represenation of a particular instance of coverage characterized by the given ratio between build successes and failures collected for the given project, during the specified month.
V	Admin/User	{host}/unitTest/value/{user}/{project}/{month}/{value}	Returns a represenation of a particular instance of unitTest characterized by the given ratio between test successes and failures collected for the given project, during the specified month.

Resource types that don't change in time and are not affected by privacy troubles:

Already implemented	Authorization Level	URI	Effect	Main Motivation
V	Any	{host}/tool/{toolName}	Return a representation of the named tool	links to info about this tool
V	Any	{host}/programmingLanguage/{name}	Return a representation of the named programming language	links to info about this language
V	Any	{host}/operatingSystem/{name}	Return a representation of the named operating system	links to info about this os
V	Any	{host}/machine/{name}	Return a representation of the named machine	links to info about this machine
V	Any	{host}/priority/{priorityName}	Return a representation of the named file located at the named priority
V	Any	{host}/patch/{patchId}	Return a representation of the named patch.
V	Any	{host}/ping	Return the "ping representation" of this service, which is the string "LinkedServiceData"
V	Any	{host}/ping?user={user} &password={password}	If {user} and {password} are valid credentials, returns "LinkedServiceData authenticated"

Resources regarding Tests and Issues are still under planning (with the help of suggestions from the dev-ml).

Cache

Already implemented	Method	URI	Effect
V	DELETE	{host}/cache/{user}	Deletes any cached LinkedServiceData instances associated with this user.
V	DELETE	{host}/cache/{user}/{project}	Deletes any cached LinkedServiceData instances associated with this user and project.
V	DELETE	{host}/cache/others	Deletes any cached LinkedServiceData instances not associated with any user.

Has been checked and is granted that this REST API allows the realization of all proposed use case scenarios.

A user profile (reference-able by {host}/users/{user}) will (accordingly to the privacy setting) include:

project profiles of each project the user has actively worked in (as a member) with a month granularity;
any kind of 'knowledge' resource (subclassof the knowledge resource within the proposed schema) such as commands, programming language, operating system, tools;
programming skills through values taken for each project the user has actively worked in (as a member)) on a month granularity

his commitment values (which currently includes: 1 the average time spent developing each month; 2 the average commits per month)
build quality calculated as the ratio buildSuccesses/buildFailures
average code issues encountered
unit test quality calculated as the ratio unittestSuccess/unittestFailures
ratio between successful and unsuccessful tests to which he has been/is contributing
list of bugs reported by him
list of bugs assigned to him

With a sensor retrieving also users posts to developer's ml or forums, the average number of posts sent could become part of the user's commitment, together with average commits and dev-time. This will require a new SDT and a proper resource provided by DPD and Telemetry.

A project profile (reference-able by {host}/projects/{owner}/{projectname} ) will (accordingly to the privacy setting) include:

average commits per month
coverage percentage
unit test ratio between successes and failures
build ratio between successes and failures
development time average per month
amount of code issues per month

Note that complexity values can't be reported for a whole project because the telemetry 'complexity' chart seems to not exist; while metrics about files can be not so interesting and coupling values seems to be too linked to specific tools.

Hackystat users can set privacy level for:

the projects owned by them
their own user profiles
their sensor data (that could be accessible, if the user wants, only specifying the owner and the type)

which means that:

- Project data in their 'properties' field have to include the couple:

key="Profile visibility", value="2" or "1" or "0" ((2 means visible to anyone; 1 means visible only to other registered hackystat users; 0 means visible only to project members, invitated and spectators, as usual).

- User data in their 'properties' field have to include the couple:

key="Profile visibility", value="2" or "1" or "0" (2 means visible to anyone; 1 means visible only to other registered hackystat users; 0 means visible only to the user himself and the admin, as usual);
key="Sensor Data visibility", value="2" or "1" or "0" (which mean the same as above).

In case such properties are not found, then the visibility is considered as set to 0 for each resource (which corresponds to the current usual setting). The value "2" is always considered as 'accessible to any registered hackystat user' because, as stated before, the Sensorbase currently doesn't yet allow access to non registered users at all.

NOTE: It could be helpful for a developer to have a test result linked with external projects in which a test for the same purpose ( http://www.w3.org/TR/test-metadata/#purpose-def ) has come to the same result and status. Then a developer could browse other projects to see how this result has been improved. The same could happen with command results. In this case a command result would be linked to other external projects in which the same command has been invoked obtaining the same result.

These data would be provided firstly by other Hackystat servers.

LiSeD REST API Details

Here follows examples of server responses containing basic information, that is information which doesn't include links to external datasets (as the fourth Linked Data principle requires).

User

This an example user profile, provided by the server for the URI:

http://localhost:9875/linkedservicedata/users/myrpandemon@yahoo.it

Result:

<http://localhost:9875/linkedservicedata/users/myrpandemon@yahoo.it>     
	a       
		<http://xmlns.com/foaf/0.1/Person> ;      
	<http://dasha.ics.hawaii.edu:9875/linkedservicedata/vocab/developer>              
		"http://localhost:9875/linkedservicedata/projects/myrpandemon@yahoo.it/Default" ;      
	<http://dasha.ics.hawaii.edu:9875/linkedservicedata/vocab/knows>              
		"http://localhost:9875/linkedservicedata/tool/Emma" , 
		"http://localhost:9875/linkedservicedata/tool/JUnit" , 
		"http://localhost:9875/linkedservicedata/command/awk" , 
		"http://localhost:9875/linkedservicedata/tool/JDepend" , 
		"http://localhost:9875/linkedservicedata/tool/Eclipse" , 
		"http://localhost:9875/linkedservicedata/tool/SCLC" , 
		"http://localhost:9875/linkedservicedata/language/Java" , 
		"http://localhost:9875/linkedservicedata/tool/FindBugs" , 
		"http://localhost:9875/linkedservicedata/tool/Emacs" , 
		"http://localhost:9875/linkedservicedata/tool/Subversion" , 
		"http://localhost:9875/linkedservicedata/tool/PMD" , 
		"http://localhost:9875/linkedservicedata/tool/Ant" , 
		"http://localhost:9875/linkedservicedata/tool/Checkstyle" , 
		"http://localhost:9875/linkedservicedata/tool/DependencyFinder" , 
		"http://localhost:9875/linkedservicedata/operatingSystem/Debian" , 
		"http://localhost:9875/linkedservicedata/command/octave-config" , 
		"http://localhost:9875/linkedservicedata/tool/Bash" , 
		"http://localhost:9875/linkedservicedata/tool/Netbeans" , 
		"http://localhost:9875/linkedservicedata/operatingSystem/Leon" , 
		"http://localhost:9875/linkedservicedata/language/C" , 
		"http://localhost:9875/linkedservicedata/machine/i386" , 
		"http://localhost:9875/linkedservicedata/tool/JavaNCSS" , 
		"http://localhost:9875/linkedservicedata/machine/sparc" ;      
	<http://dasha.ics.hawaii.edu:9875/linkedservicedata/vocab/maintainer>              
		"http://localhost:9875/linkedservicedata/projects/myrpandemon@yahoo.it/LiSeD_Test_1" , 
		"http://localhost:9875/linkedservicedata/projects/myrpandemon@yahoo.it/LiSeD_Test_2" ;      
<http://dasha.ics.hawaii.edu:9875/linkedservicedata/vocab/buildQuality>              
		"2" ;      
<http://dasha.ics.hawaii.edu:9875/linkedservicedata/vocab/commitFrequency>
              		"4" ;
	<http://dasha.ics.hawaii.edu:9875/linkedservicedata/vocab/amountOfCodeIssues>               
		"0.0" ;      
	<http://dasha.ics.hawaii.edu:9875/linkedservicedata/vocab/developmentTime>
              "9.416666666666666" ;
      
	<http://xmlns.com/foaf/0.1/mbox>              
		"myrpandemon@yahoo.it" .

All the URIs are derefenceable. Here the user profile stiil lack of bugs assigned to and reported by this user, and the ratio between successful and unsuccessful tests to which this user has been or is contributing.

Project

This an example project profile, provided by the server for the URI:

http://localhost:9875/linkedservicedata/projects/myrpandemon@yahoo.it/Default

Result:

<http://localhost:9875/linkedservicedata/projects/myrpandemon@yahoo.it/default>      
	a       
		<http://usefulinc.com/ns/doap#Project> ;      
	<http://dasha.ics.hawaii.edu:9875/linkedservicedata/vocab/amountOfCodeIssues>              
		<http://localhost:9875/linkedservicedata/codeIssue/myrpandemon@yahoo.it/Default> ;      
	<http://dasha.ics.hawaii.edu:9875/linkedservicedata/vocab/buildQuality>              
		<http://localhost:9875/linkedservicedata/build/myrpandemon@yahoo.it/Default> ;      
	<http://dasha.ics.hawaii.edu:9875/linkedservicedata/vocab/commitFrequency>              
		<http://localhost:9875/linkedservicedata/commit/myrpandemon@yahoo.it/Default> ;      
	<http://dasha.ics.hawaii.edu:9875/linkedservicedata/vocab/coveragePercentage>              
		<http://localhost:9875/linkedservicedata/coverage/myrpandemon@yahoo.it/Default> ;      
	<http://dasha.ics.hawaii.edu:9875/linkedservicedata/vocab/developmentTime>              
		<http://localhost:9875/linkedservicedata/devTime/myrpandemon@yahoo.it/Default> ;      
	<http://dasha.ics.hawaii.edu:9875/linkedservicedata/vocab/ended>              
		"2010-01-01T23:59:59.999-10:00" ;      
	<http://dasha.ics.hawaii.edu:9875/linkedservicedata/vocab/modified>              
		"2009-07-03T12:27:05.424-10:00" ;      
	<http://dasha.ics.hawaii.edu:9875/linkedservicedata/vocab/unitTestQuality>              
		<http://localhost:9875/linkedservicedata/unitTest/myrpandemon@yahoo.it/Default> ;      
	<http://usefulinc.com/ns/doap#created>              
		"2000-01-01T00:00:00.000-10:00" ;      
	<http://usefulinc.com/ns/doap#description>              
		"The default Project" ;      
	<http://usefulinc.com/ns/doap#maintainer>              
		"myrpandemon@yahoo.it" ;      
	<http://usefulinc.com/ns/doap#name>              
		"Default" .

<http://localhost:9875/linkedservicedata/unitTest/myrpandemon@yahoo.it/Default>      
	a       
		<http://www.w3.org/1999/02/22-rdf-syntax-ns#Seq> ;      
			<http://www.w3.org/1999/02/22-rdf-syntax-ns#_1>              
				"http://localhost:9875/linkedservicedata/unitTest/myrpandemon@yahoo.it/Default/2009-05-01-10:00/12.0" .

<http://localhost:9875/linkedservicedata/build/myrpandemon@yahoo.it/Default>      
	a       
		<http://www.w3.org/1999/02/22-rdf-syntax-ns#Seq> ;      
			<http://www.w3.org/1999/02/22-rdf-syntax-ns#_1>              
				"http://localhost:9875/linkedservicedata/build/myrpandemon@yahoo.it/Default/2009-05-01-10:00/2.0" .

<http://localhost:9875/linkedservicedata/devTime/myrpandemon@yahoo.it/Default>      
	a       
		<http://www.w3.org/1999/02/22-rdf-syntax-ns#Seq> ;      
			<http://www.w3.org/1999/02/22-rdf-syntax-ns#_1>              
				"http://localhost:9875/linkedservicedata/devTime/myrpandemon@yahoo.it/Default/2009-07-01-10:00/9.416666666666666" .

<http://localhost:9875/linkedservicedata/coverage/myrpandemon@yahoo.it/Default>      
	a       
		<http://www.w3.org/1999/02/22-rdf-syntax-ns#Seq> ;      
			<http://www.w3.org/1999/02/22-rdf-syntax-ns#_1>              
				"http://localhost:9875/linkedservicedata/coverage/myrpandemon@yahoo.it/Default/2009-05-01-10:00/100" .

<http://localhost:9875/linkedservicedata/codeIssue/myrpandemon@yahoo.it/Default>      
	a      
		<http://www.w3.org/1999/02/22-rdf-syntax-ns#Seq> ;      
			<http://www.w3.org/1999/02/22-rdf-syntax-ns#_1>              
				"http://localhost:9875/linkedservicedata/codeIssue/myrpandemon@yahoo.it/Default/2009-07-01-10:00/0" ;      
			<http://www.w3.org/1999/02/22-rdf-syntax-ns#_2>              
				"http://localhost:9875/linkedservicedata/codeIssue/myrpandemon@yahoo.it/Default/2009-05-01-10:00/0" .

<http://localhost:9875/linkedservicedata/commit/myrpandemon@yahoo.it/Default>     
	a       
		<http://www.w3.org/1999/02/22-rdf-syntax-ns#Seq> ;      
			<http://www.w3.org/1999/02/22-rdf-syntax-ns#_1>              
				"http://localhost:9875/linkedservicedata/commit/myrpandemon@yahoo.it/Default/2007-10-01-10:00/4" .

Project Profiles constitute the only situation in which a resource description contains also triples which doesn't have the resource itself as subject. That's just because I thought it should be sure that someone asking for project data is interested in getting also info about quality (code issues, coverage, etc.), and then providing them without compelling the user to dereference new URIs it's more comfortable. However the URIs are all dereference-able.

SW Component

Suppressed because data about really low-level component (lines, methods, classes etc.) are not collected.

Source File

This is an example description of a file (a type of SD source), provided by the server for the URI:

http://localhost:9875/linkedservicedata/source/file/myrpandemon@yahoo.it/Default/__home__myrtill__HackystatHackerCertification__hackystat-projects__hackystat-sensor-example-8.3.523__src__edu__hawaii__stack__Stack.java/2009-05-24T00:00:00.000-10:00

Result:

<http://localhost:9875/linkedservicedata/source/file/filetype/myrpandemon@yahoo.it/Default/__home__myrtill__HackystatHackerCertification__hackystat-projects__hackystat-sensor-example-8.3.523__src__edu__hawaii__stack__Stack.java>      
	a       
		<http://dasha.ics.hawaii.edu:9875/linkedservicedata/vocab/File> ;      

	<http://dasha.ics.hawaii.edu:9875/linkedservicedata/vocab/afferent>              
		"unknown" ;      

	<http://dasha.ics.hawaii.edu:9875/linkedservicedata/vocab/coverageQuality>              
		"unknown" ;      

	<http://dasha.ics.hawaii.edu:9875/linkedservicedata/vocab/efferent>              
		"unknown" ;      

	<http://dasha.ics.hawaii.edu:9875/linkedservicedata/vocab/totLines>              
		"17.0" .

SW Development Phase

This is an example description of a development phase, provided by the server for the URI:

http://localhost:9875/linkedservicedata/devPhase/myrpandemon@yahoo.it/LiSeD_Test_1/analysis

Result:

<http://localhost:9875/linkedservicedata/devPhase/myrpandemon@yahoo.it/LiSeD_Test_1/analysis>      
	a       
		<http://dasha.ics.hawaii.edu:9875/linkedservicedata/vocab/DevelopmentPhase> ;      
	<http://dasha.ics.hawaii.edu:9875/linkedservicedata/vocab/couldCauses>              
		"http://localhost:9875/linkedservicedata/issue/130267" ;      
	<http://dasha.ics.hawaii.edu:9875/linkedservicedata/vocab/involvedUser>              
		"http://localhost:9875/linkedservicedata/users/myrpandemon@yahoo.it" .

Test Suite

To be truly useful, a test suite should consist of more than a simple collection of tests. Additional information is typically required to help users understand how to execute the tests and how to interpret the results. Much of this information should be provided in the test suite documentation but some is more appropriately provided in the form of metadata about the tests themselves. Well-defined metadata can help in:

tracking tests during development and review process
filtering tests according to a variety of criteria (for example, whether or not they are applicable for a particular profile or optional feature)
identifying the area of the specification that is tested by the tests
constructing a test harness to automatically execute the tests
formatting test results so that they are easily understood

I think these facilities could be very useful, then I'm supposing the existence of a Test SDT, able to provide some kinds of info about tests.