The REST API

Submitted by gousiosg on Thu, 05/13/2010 - 22:20

In General

The REST API allows for accessing the stored metadata and metric results in a structured manner. There are two basic entities for the API, namely Projects and Metrics, and everything else is hierarchically mapped under those. To call the API, the Alitheia Core REST bundle must be enabled.

Accessing the SQO-OSS metrics database

To access the SQO-OSS project main database repository (or at least a snapshot of it) you need to append API calls to the following
base URL:

http://demo.sqo-oss.org/web/proxy/

This is a bit different from accessing the API from a local Alitheia Core installation, which requires the following prefix:

http://localhost:8080/api

Basically, the project uses a proxy to hide the actual Alitheia Core installation machine behind it. All you need to do is to change /api to /web/proxy. Some of the examples below are actually calling the main SQO-OSS metrics database.

To see some examples for accessing the API, you can see the implementation of the web page that runs at http://demo.sqo-oss.org

Variable types

The service can return either JSON or XML, using content negotiation. Specifically, if the Accepts HTTP header specifies the application/json content type with higher priority than application/xml then content is returned as JSON. In all other cases, including when Acceptis absent from the request, XML is preferred. The names of JSON keys/XML fields is the same in both cases.

The following example demonstrates how to call the REST API using the code command line HTTP client. The same call is shown using XML and JSON return types.

curl http://$HOST/api/project/31

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<project>
    <id>31</id>
    <name>FreeBSD</name>
</project>

curl -H "Accept: application/json" http://$HOST/api/project/31

{"project":{"id":31,"name":"FreeBSD"}}

Arguments

Several API calls can accept a variable number of arguments. As shown in the API descriptions below, in all API calls that accept multiple arguments, those are separated with commas and they always occur at the end of the call.

The API

/api: The root for all API requests

/api/metrics/: Returns all installed metrics.

curl -H "Accept: application/json" http://localhost:8080/api/metrics

[ 
  {"metric":{"id":13,"metrictype":{"id":3, "type":"SOURCE_DIRECTORY"}, "mnemonic":"MNOF", 
   "description":"Number of Source Code Files in Module"},
  [...]
]

/api/metrics/types: Returns all available types of metrics

Example

$ curl -H "Accept: application/json" http://$HOST/api/metrics/types

[
   { "metrictype":{ "id":1, "type":"SOURCE_FILE" } },
   { "metrictype":{ "id":2, "type":"PROJECT_VERSION" }},
   { "metrictype":{ "id":3, "type":"MAILTHREAD"}}
]

/api/metrics/by-type/{type}: Returns all metrics of a certain type. The parameter corresponds to the real name (not the id) of the metric type, as returned by the /metrics/types call.

Example

curl -H "Accept: application/json" http://localhost:8080/api/metrics/by-type/SOURCE_FILE

[
  {"metric":{"id":16, "metrictype":{"id":2, "type":"SOURCE_FILE"}, "mnemonic":"EMCC_TOTAL", "description":"Total Extended McCabe Cyclomatic Complexity"}},
  {"metric":{"id":17,"metrictype":{"id":2,"type":"SOURCE_FILE"}, "mnemonic":"HD", "description":"Halstead Difficulty Level"}}
]

/api/metrics/by-id/{id}: Returns a metric by its id. The id can be retrieved by querying for all metrics

Example

curl http://$HOST:8080/api/metrics/by-id/2

<metric>
  <id>2</id>
  <metrictype>
    <id>1</id>
    <type>PROJECT_VERSION</type>
  </metrictype>
  <mnemonic>NOF</mnemonic>
  <description>Number of Files</description>
</metric>

/api/metrics/by-id/{id}/result/{resid, ...}: Get the result of a metric run for metric with the provided id on the resourses identified by the ids at the end of the request URL. Up to 64 resource IDs can be specified in a comma seperated list. If no result has been calculated for a resource Id, then this ID is ignored in the returned result.

curl -H "Accept: application/json" http://localhost:8080/api/metrics/by-id/2/result/3,4,5

[
  {"r":{"artifactId":3,"metricId":2,"result":2,"type":"INTEGER"}},
  {"r":{"artifactId":5,"metricId":2,"result":4,"type":"INTEGER"}}
]

/api/metrics/by-mnem/{mnem}: Get a metric description by mnemonic

curl -H "Accept: application/json" http://localhost:8080/api/metrics/by-mnem/"Wc.loc"

{"metric":{"id":11,"metrictype":{"id":2,"type":"SOURCE_FILE"},"mnemonic":"Wc.loc","description":"Total lines"}}

/api/project/: Get a list of all projects

curl -H "Accept: application/json" http://localhost:8080/api/project

[{"project":{"id":1,"name":"Gnome-VFS"}}]

/api/project/{id}: Get a single project by id.

curl http://$HOST/api/project/33

<project>
  <id>22</id>
  <name>JikesRVM</name>
</project>

/api/project/{id}/versions: Get a list of all project versions, for the project with the provided id. This method might return a very big number of results for long running projects. Use wisely.

$curl http://$HOST/api/project/33/versions

<collection>
<version><id>348819</id><revisionId>0</revisionId><timestamp>1177950980280</timestamp><committer><id>20564</id><username>sqo-oss</username></committer><commitMsg>Artificial revision to include / directory</commitMsg><sequence>0</sequence></version>
<version><id>348965</id><revisionId>146</revisionId><timestamp>1021492080000</timestamp><committer><id>20710</id><username>tarantula</username></committer><commitMsg>New repository initialized by cvs2svn.</commitMsg><sequence>1</sequence></version>
<version><id>348966</id><revisionId>147</revisionId><timestamp>1021492080000</timestamp><committer><id>20711</id><username>jsiek</username></committer><commitMsg>new file </commitMsg><sequence>2</sequence></version>
<version><id>348967</id><revisionId>148</revisionId><timestamp>1021492476000</timestamp><committer><id>20711</id><username>jsiek</username></committer><commitMsg>added minmax algo </commitMsg><sequence>3</sequence></version>
<version><id>348968</id><revisionId>149</revisionId><timestamp>1021560222000</timestamp><committer><id>20712</id><username>peti</username></committer><commitMsg>Initial version of the enum_state&lt;&gt; template, which is actually called State&lt;&gt; at the moment. :-)</commitMsg></version>
</collection>

/api/project/{id}/versions/{revid, revid, ...}: Get information on specific versions of the project with the provided ID.

$curl http://$HOST/api/project/33/versions/0,1

<collection>
<version><id>348819</id><revisionId>0</revisionId><timestamp>1177950980280</timestamp><committer><id>20564</id><username>sqo-oss</username></committer><commitMsg>Artificial revision to include / directory</commitMsg><sequence>0</sequence></version>
<version><id>348965</id><revisionId>146</revisionId><timestamp>1021492080000</timestamp><committer><id>20710</id><username>tarantula</username></committer><commitMsg>New repository initialized by cvs2svn.</commitMsg><sequence>1</sequence></version>
</collection>

/api/project/{id}/version/{vid}/files/: Get all files that are live for the project with the provided ID in the specidied revision. Only file nodes (not directories) are returned, recursively.

/api/project/{id}/version/{vid}/files/{dir: .+}: Get all files that are live for the project with the provided ID in the specidied revision. Only files that are live in the provided directory path are returned.

curl http://demo.sqo-oss.org/web/proxy/project/10/version/5551/files/trunk/doc

<collection>
  <file>
    <id>97198</id>
    <name>uri.txt</name>
    <state>
      <status>2</status>
    </state>
    <isdir>false</isdir>
    <dir>
      <id>1136</id>
      <path>/trunk/doc</path>
    </dir>
  </file>
  <file>
    <id>102736</id>
    <name>mime-descriptions-guidelines.txt</name>
    <state>
      <status>1</status>
    </state>
    <isdir>false</isdir>
    <dir>
      <id>1136</id>
      <path>/trunk/doc</path>
    </dir>
  </file>
</collection>

/api/project/{id}/version/{vid}/files/changed: Get a list of files that changed in the specified revision

curl http://demo.sqo-oss.org/web/proxy/project/10/version/5551/files/changed

<collection>
  <file>
    <id>19408686</id>
    <name>modules</name>
    <state>
      <status>2</status>
    </state>
    <isdir>true</isdir>
    <dir>
      <id>27</id>
      <path>/trunk</path>
    </dir>
  </file>
  <file>
    <id>19408684</id>
    <name>sftp-method.c</name>
    <state>
      <status>2</status>
    </state>
    <isdir>false</isdir>
    <dir>
      <id>1947</id>
      <path>/trunk/modules</path>
    </dir>
  </file>
  <file>
    <id>19408685</id>
    <name>ChangeLog</name>
    <state>
      <status>2</status>
    </state>
    <isdir>false</isdir>
    <dir>
      <id>27</id>
      <path>/trunk</path>
    </dir>
  </file>
[...]
 </collection>

/api/project/{id}/version/{vid}/dirs/: Get all directories (recursively) for the current version of the file

http://$HOST/10/version/5551/dirs/

[{"file":{"id":113233,"name":"tarpet","state":{"status":1},"isdir":true,"dir":{"id":1136,"path":"\/trunk\/doc"}}},{"file":{"id":113317,"name":"mime-test-files","state":{"status":2},"isdir":true,"dir":{"id":1948,"path":"\/trunk\/test"}}},
{"file":{"id":198381,"name":"imported","state":{"status":2},"isdir":true,"dir":{"id":27,"path":"\/trunk"}}},{"file":{"id":198383,"name":"gnome-vfs-tutorial","state":{"status":2},"isdir":true,"dir":{"id":1115,"path":"\/trunk\/devel-docs"}}}
...]

/api/project/{id}/version/{vid}/dirs/{dir: .+}: Get all directories contained in a specific project directory in the provided project version.

curl http://demo.sqo-oss.org/web/proxy/project/10/version/5551/dirs/trunk/doc

<collection>
  <file>
    <id>113233</id>
    <name>tarpet</name>
    <state>
      <status>1</status>
    </state>
    <isdir>true</isdir>
    <dir>
      <id>1136</id>
      <path>/trunk/doc</path>
    </dir>
  </file>
  <file>
    <id>200276</id>
    <name>tmpl</name>
    <state>
      <status>2</status>
    </state>
    <isdir>true</isdir>
    <dir>
      <id>1136</id>
      <path>/trunk/doc</path>
    </dir>
  </file>
</collection>

re

Submitted by nahshal on Sun, 02/05/2012 - 12:38.

thanks for this use ful shairng..

frases para orkut

The home of Alitheia Core

The REST API

In General

Accessing the SQO-OSS metrics database

Variable types

Arguments

The API

re

Navigation

Search

User login

Syndicate