Melquiades API

Melquiades API

Documentation about the Melquiades API, which is still work in progress. Beware, some parts of this could still be nonfunctional.

Note on urls: all FLOSSMetrics urls are not qualified by the domain name, but start with the resource name within the corresponding FLOSSMetrics domain. Therefore, instead of http://melquiades.flossmetrics.org/projects/evince, the API will always return /projects/evince

URL's (Simple API)

For each url, several formats will be returned, according to the extension. See ”Returned objects” below. The extensions used are:

json: JSON code

rss: RSS channel

html: Static HTML element (suitable for including in an HTML body). XHTML will be used

ajx: Ajax enabled HTML element

URL description

/projects

Description: List of all projects in the database.
Returns: projectsList

/projects/$id

Description: Information about an specific project.
Returns: projectsList

/projects/$id/dumps

Description: List of dumps belongs to an specific project.
Returns: dumpsList

/projects/$id/dumps/$repo

Description: List of dump types of an specific project.
Returns: dumpsList

/projects/$id/dumps/$repo/$dump

Description: Information about a very specific dump.
Returns: dumpInfo

/projects/$id/resources

Description: List of resources of an specific project.
Returns: resourcesList

/projects/$id/graphs

Description: Graphs of an specific project.
Returns: graphsList

Returned objects

projectsList

List of projects (usually, result of a query).

Attributes

id: Number to identify the project.

name : project identifier (usually, project name in lowercase)

url: url of the corresponding |projectInfo object (no extension)

data: url of the webdav repository with data about the project (dump files, graph files, etc.)

JSON

Format:

[{id="id1", name="name1", url="url1", data="data1"}, {...}, ...]

Example:

[{id="1091", name="evince", url="/projects/evince", data="/projectsd/evince"},
 {id="1095", name="evolution", url="/projects/evolution", data="/projectsd/evolution"}]

RSS

Format:

<?xml version="1.0"?>
<rss version="2.0">
  <channel>
    <title>title</title>
    <link>url</link>
    <description>short_desc</description>    
    <item>
      <name>name1</name>
      <url>/project/id1</url>
      <desc>desc1</desc>
      <data>/projectsd/id1</data>
    </item>
    <item>  
      <name>name2</name>
      <url>/project/id2</url>
      <desc>desc2</desc>
      <data>/projectsd/id2</data>
    </item>
      .
      .
      .
    <item>
      <name>namen</name>
      <url>/project/idn</url>
      <desc>descn</desc>
      <data>/projectsd/idn</data>
    </item>
  </channel>
</rss>

Examples:

<?xml version="1.0"?>
<rss version="2.0">
  <channel>
    <title>List of Projects in Melquiades</title>
    <link>http://melquiades.flossmetrics.org/projects</link>
    <description>List of projects...</description>  
    <item>
      <name>evince</name>
      <url>/projects/evince</url>
      <data>/projectsd/evince</data>
    </item>   
    <item> 
      <name>evolution</name>
      <url>/projects/evolution</url>
      <data>/projectsd/evolution</data>
    </item>
  </channel>
</rss>

HTML

Format:

<ul>
   <li><a href="/projects/name1">name1</a> - <a href="/projectsd/id1">project data</a></li>
   <li><a href="/projects/name2">name2</a> - <a href="/projectsd/id2">project data</a></li>
   .
   .
   .
   <li><a href="/projects/namen">namen</a> - <a href="/projectsd/idn">project data</a></li>
</ul>

Example:

<ul>
   <li><a href="/projects/evince">evince</a> (id: evince, <a href="/projectsd/evince">project data</a>)</li>
   <li><a href="/projects/evolution">evolution</a> (id: evolution, <a href="/projectsd/evolution">project data</a>)</li>
</ul>

projectInfo

Gives Information about a project

Attributes

id: Number which identify a project.

name : project identifier (usually, project name in lowercase)

title: project real name (capitalized as usual)

desc: Short description of the project

|dumpsList : URL to the dumps in melquiades.

url : Is the Home URL of the project.

|resourcesList : URl to the resources in melquiades

|graphsList : URL to the graphs in melquiades.

JSON

Format:

[{id="id1",name="name1",title="title1",desc="desc1",dump_link="link1",url="link1",resources_link="link1",data_link="data_link1"}, {...}, ...]

Example:

[{id=1091, name="evince", title="Evince", desc="This project...", dump_link="/projects/evince/dumps/",url="http://...",resources_link="/projects/evince/resources/",data_link="/projectsd/evince" },
 {id=1095,name="evolution", title="Evolution",desc="This project...", dump_link="/projects/evolution/dumps/",url="http://...",resources_link="/projects/evolution/resources/",data_link="/projectsd/evolution" }]

RSS

Format:

<?xml version="1.0"?>
<rss version="2.0">
  <channel>
    <title>title</title>
    <link>url</link> 
    <description>short_desc</description>   
    <item>
      <id>id1</id>
      <name>name1</name>
      <title>title1</title>
      <desc>desc1</desc>
      <dump_link>dump_link1</dump_link>
      <url>project_link1</url>
      <resources_link>resources_link1</resources_link>
      <data_link>data_link1</data_link>
    </item>
  </channel>
</rss>

Example:

<?xml version="1.0"?>
<rss version="2.0">
  <channel>
    <title>Information about Evince project</title>
    <link>http://melquiades.flossmetrics.org/projects/evince</link>  
    <description>Information about...</description>  
    <item>
      <id>1091</id>
      <name>evince</name>
      <title>Evince</title>
      <desc>This project....</desc>
      <dump_link>/projects/evince/dumps</dump_link>
      <url>/projects/evince/</url>
      <resources_link>/projects/evince/resources</resources_link>
      <data_link>/projectsd/evince</data_link>
    </item>
  </channel>
</rss>

HTML

Format:

<ul>
   <li>
      <a href="/projects/name">title</a>
      <p>desc1</p>
      <a href="url">url1</a>
      <a href="dump_link">dump_link1</a>
      <a href="resources_link">resources_link1</a>
      <a href="data_link">data_link1</a>
   </li>
</ul>

Example:

<ul>
   <li>
      <a href="/projects/evince">Evince</a>
      <p>This project...</p>
      <a href="/projects/evince">Evince Project in Melquiades</a>
      <a href="/projects/evince/dumps">Dumps</a>
      <a href="/projects/resources/evince">Resources</a>
      <a href="/projectsd/evince">Data</a>
   </li>
</ul>

dumpsList

Returns information about dumps of a project.

Attributes

dump_name: name of the dump.

url_repository_type : The name of the repository, is a link because we want to offer explanations about every single type of repository in the wiki.

url : Is the melquiades URL.

dump_url : Is the link to the dump file.

JSON

Format:

[{dump_name="dump_name1", url_repository_type="url_repository_type", url="url1",dump_url="dump_url1"}, {...}, ...]

Example:

[{dump_name="fm3_evince_cvsanaly2_svn_scm_20080905T03:36:19.446695.sql.gz", url_repository_type="scm", url="/projects/evince/dumps/svn",dump_url="http://melquiades.flossmetrics.org/projects/evince/fm3_evince_cvsanaly2_svn_scm_20080905T03:36:19.446695.sql.gz" }, 
 {dump_name="fm3_evince_mlstats_mbox_mls_20080828T11:57:46.993686.sql.gz", url_repository_type="mls", url="/projects/evince/dumps/mls",dump_url="http://melquiades.flossmetrics.org/projects/evince/fm3_evince_mlstats_mbox_mls_20080828T11:57:46.993686.sql.gz" }]

RSS

Format:

<?xml version="1.0"?>
<rss version="2.0">
  <channel>
    <title>title</title>
    <link>url</link>
    <description>short_desc</description>      
    <item>
      <dump_name>dump_name1</dump_name>
      <url_repository_type>url_repository_type1</url_repository_type>
      <url>url1</url>
      <dump_url>dump_url1</dump_url1>
    </item>
    <item>  
      <dump_name>dump_name2</dump_name>
      <url_repository_type>url_repository_type2</url_repository_type>
      <url>url2</url>
      <dump_url>dump_url2</dump_url1>
    </item>
    .     
    .
    .  
    <item>
      <dump_name>dump_namen</dump_name>
      <url_repository_type>url_repository_typen</url_repository_type>
      <url>urln</url>
      <dump_url>dump_urln</dump_url1>
    </item>
  </channel>
</rss>

Example:

<?xml version="1.0"?>
<rss version="2.0">
  <channel>
    <title>List of dumps of Evince</title>
    <link>http://melquiades.flossmetrics.org/projects/evince/dumps</link>
    <description>List of...</description>        
    <item>
      <dump_name>fm3_evince_cvsanaly2_svn_scm_20080905T03:36:19.446695.sql.gz</dump_name>
      <url_repository_type>SCM</url_repository_type>
      <url>/projects/evince/dumps/scm</url>
      <dump_url>http://melquiades.flossmetrics.org/projects/evince/fm3_evince_cvsanaly2_svn_scm_20080905T03:36:19.446695.sql.gz</dump_url1>
    </item>
    <item>
      <dump_name>fm3_evince_mlstats_mbox_mls_20080828T11:57:46.993686.sql.gz</dump_name>
      <url_repository_type>MLS</url_repository_type>
      <url>/projects/evince/dumps/mls</url>
      <dump_url>http://melquiades.flossmetrics.org/projects/evince/fm3_evince_mlstats_mbox_mls_20080828T11:57:46.993686.sql.gz</dump_url1>
    </item>
  </channel>
</rss>

HTML

Format:

<ul>
  <li>
    <p>name1</p>
    <a href="url_repostory_type">repository_type1</a>
    <a href="url">url1</a>
    <a href="dump_url">dump_url1</a>
  </li>
  <li>
    <p>name2</p>
    <a href="url_repostory_type">repository_type2</a>
    <a href="url">url2</a>
    <a href="dump_url">dump_url2</a>
  </li>
  .
  .
  .
  <li>
    <p>namen</p>
    <a href="url_repostory_type">repository_typen</a>
    <a href="url">urln</a>
    <a href="dump_url">dump_urln</a>
  </li>
<ul>

Example:

<ul>
  <li>
    <p>Evince</p>
    <a href="url_repostory_type">SCM</a>
    <a href="/projects/evince/dumps">/projects/evince/dumps/scm</a>
    <a href="http://melquiades.flossmetrics.org/projects/evince/fm3_evince_cvsanaly2_svn_scm_20080905T03:36:19.446695.sql.gz">fm3_evince_cvsanaly2_svn_scm_20080905T03:36:19.446695.sql.gz</a>
  </li>
  <li>
    <p>Evolution</p>
    <a href="url_repostory_type">MLS</a>
    <a href="url">/projects/evince/dumps/mls</a>
    <a href="http://melquiades.flossmetrics.org/projects/evince/fm3_evince_mlstats_mbox_mls_20080828T11:57:46.993686.sql.gz">fm3_evince_mlstats_mbox_mls_20080828T11:57:46.993686.sql.gz</a>
  </li>
<ul>

dumpInfo

Returns specific information about a dump of a project.

Attributes

name : Name of the dump.

date : When dump was created.

tool : Tools used to get the information that the dump contains.

dump_url : URL to the file.

url : melquiades URL to the dump.

type : Type of dump (may be : svn, cvs, mbox and so on)

JSON

Format:

[{name="name", date="date", tool="tool", dump_url="dump_url", url="url",type="type"}, {...}, ...]

Example:

[{name="fm3_evince_cvsanaly2_svn_scm_20080905T03:36:19.446695.sql.gz", date="2008-09-05", tool="CVSAnaly2", dump_url="http://melquiades.flossmetrics.org/projects/evince/fm3_evince_cvsanaly2_svn_scm_20080905T03:36:19.446695.sql.gz", url="/project/evince/dumps/scm",type="SCM"}]

RSS

Format:

<?xml version="1.0"?>
<rss version="2.0">
  <channel>
    <title>title</title>
    <link>url</link>
    <description>short_desc</description>       
    <item>
      <name>name</name>
      <date>date</date>
      <tools>tool</tool>
      <dump_url>dump_url</dump_url>  
      <url>url1</url>
    </item>
  </channel>
</rss>

Example:

<?xml version="1.0"?>
<rss version="2.0">
  <channel>
    <title>Information about SCM dump of Evince</title>
    <link>http://melquiades.flossmetrics.org/projects/evince/dumps/scm</link>
    <description>Information about...</description>  
    <item>
      <name>fm3_evince_cvsanaly2_svn_scm_20080905T03:36:19.446695.sql.gz</name>
      <date>2008-09-05</date>
      <tools>CVSAnaly2</tool>
      <dump_url>http://melquiades.flossmetrics.org/projects/evince/fm3_evince_cvsanaly2_svn_scm_20080905T03:36:19.446695.sql.gz</dump_url1>  
      <url>/projects/evince/dumps/scm</url>
    </item>
  </channel>
</rss>

HTML

Format:

<ul>
  <li>name - date - tool - <a href="dump_url">dump_url</a> - <a href="url">url</a></li>  
</ul>

Example:

<ul>
  <li>fm3_evince_cvsanaly2_svn_scm_20080905T03:36:19.446695.sql.gz - 2008-09-05 - Mlstats - <a href="http://melquiades.flossmetrics.org/projects/evince/fm3_evince_cvsanaly2_svn_scm_20080905T03:36:19.446695.sql.gz">fm3_evince_cvsanaly2_svn_scm_20080905T03:36:19.446695.sql.gz</a> - <a href="/projects/evince/dumps/scm">/project/evince/dumps/scm</a></li>  
</ul>

resourcesList

Returns the sources used to do the studies and analyzes.

Attributes

name : Name of the resource.

url : URL to the resource.

type : Type of resource (may be : graphs, links, videos and so on)

JSON

Format:

[{name="name1", url="url1", type="type1"}, {...}, ...]

Example:

[{name="SVN Repository",url="http://svn.gnome.org/svn/evince",type="svn"},
 {name="Mailing Lists", url="http://mail.gnome.org/archives/evince-list", type="mls"}]

RSS

Format:

<?xml version="1.0"?>
<rss version="2.0">
  <channel>
    <title>title</title>
    <link>url</link>
    <description>short_desc</description>
    <item>
      <name>name1</name>
      <url>url1</url>  
      <type>type1</type>  
    </item>
    <item>  
      <name>name2</name>
      <url>url2</url>  
      <type>type2</type>  
    </item>
  </channel>
</rss>

Example:

<?xml version="1.0"?>
<rss version="2.0">
  <channel>
    <title>Resource List of Evince Project</title>
    <link>http://melquiades.flossmetrics.org/projects/evince/resources</link>
    <description>This list of resources...</description>
    <item>
     <name>SVN Repository</name>
     <url>http://svn.gnome.org/svn/evince</url>
     <type>scm</type>
    </item>
    <item>
     <name>Mailing Lists</name>
     <url>http://mail.gnome.org/archives/evolution-list</url>
     <type>mls</type>
    </item>
  </channel>
</rss>

HTML

Format:

<ul>
  <li><p>name1</p> - <a href="url1">url1</a> - <p>type</p></li>
  <li><p>name2</p> - <a href="url2">url2</a> - <p>type</p></li>

Example:

<ul>
  <li><p>SVN Repository</p> - <a href="http://svn.gnome.org/svn/evince">http://svn.gnome.org/svn/evince</a> - <p>scm</p></li>
  <li><p>Mailing Lists</p> - <a href="http://mail.gnome.org/archives/evolution-list">http://mail.gnome.org/archives/evolution-list</a> - <p>mls</p></li>
</ul>

resourceInfo

Returns specific information about an specific resource.

Note on resourceInfo : This object is under study yet, because, may be, using a list of resources and their URL it is enough.

Attributes

name : Name of the resource.

date : When the resources were created

url : Home URL to the resource.

JSON

Format:

[{name="name1", date="date", url="url"}]

Example:

[{name="SVN Repository", date="2006-05-08", url="http://svn.gnome.org/svn/evince"}]

RSS

Format:

<?xml version="1.0"?>
<rss version="2.0">
  <channel>
    <title>title</title>
    <link>url</link>
    <description>short_desc</description>
    <item>
      <name>name</name>
      <date>date</date>
      <url>url</url>
    </item>
  </channel>
</rss>

Example:

<?xml version="1.0"?>
<rss version="2.0">
  <channel>  
    <title>Information about this resource</title>
    <link>http://melquiades.flossmetrics.org/projects/evince/resources/scm</link>
    <description>The SCM resource...</description>
    <item>
      <name>SVN Repository</name>
      <date>2006-05-08</date>
      <url>http://svn.gnome.org/svn/evince</url>
    </item>
  </channel>
</rss>

HTML

Format:

<ul>
  <li><p>name</p> - <p> date </p> - <a href="url">url</a></li>
</ul>

Example:

<ul>
  <li><p>SVN Repository</p> - <p> 2006-05-08 </p> - <a href="http://svn.gnome.org/svn/evince">Download</a></li>
</ul>

graphsList

Returns a list of available graphs of the project (includes graphs such as : studies, analyzes and so on).

Attributes

name : Name of the graph.

date : When it was created.

url : Link to the graph in order to download it (may be)

JSON

Format:

[{name="name1", date="date1", url="url1"}, {...}, ...]''

Example:

[{name="Total Committers per Year", date="2008-07-09", url="/projects/evince/graphs/comperyear"},
 {name="Commits per month", date="2008-07-10", url="/projects/evince/graphs/commitspermonth"}]

RSS

Format:

<?xml version="1.0"?>
<rss version="2.0">
  <channel>
    <title>title</title>
    <link>link</link>
    <description>short_desc</description>
    <item>
      <name>name1</name>
      <date>date1</name>
      <url>url1</url>
   </item>
   <item>
     <name>name2</name>
     <date>date2</name>
     <url>url2</url>
   </item>
     .
     . 
     .
   <item>
     <name>namen</name>
     <date>daten</name>
     <url>urln</url>
   </item>
  </channel>
</rss>

Example:

<?xml version="1.0"?>
<rss version="2.0">
  <channel>
    <title>List of Graphs of Evince</title>
    <link>http://melquides.flossmetrics.org/projects/evince/graphs</link>
    <description>Graphs generated by...</description>
    <item>
      <name>Total Committers per Year</name>
      <date>2008-07-09</name>
      <url>/projects/evince/graphs/comperyear</url>
    </item>
    <item>
      <name>Commits per month</name>
      <date>2008-07-10</date>
      <url/projects/evince/graphs/commitspermonth</url>
    <item>
  </channel>
</rss>

HTML

Format:

<ul>
  <li><p>name1</p> - <p>date1</p> - <a href="url1">name1</a></li>
  <li><p>name2</p> - <p>date2</p> - <a href="url2">name2</a></li>
</ul>

Example:

<ul>
  <li><p>Total Committer per Year</p> - <p>2008-07-09</p> - <a href="/projects/evince/graphs/comperyear">Total Committers per Year</a></li>
  <li><p>Commits per month</p> - <p>2008-07-10</p> - <a href="/projects/evince/graphs/commitspermonth">Commits per Month</a></li>
</ul>

graphInfo

Returns information about an specific graph.

Note on graphInfo: We have to discuss in detail about this object, because may be a long description of the graph can be accessed through a link to the wiki, explaining how we got it or something like that.

Attributes

name : Name of the graph.

date : When it was created.

desc : Short description of the graph

url : Link to the graph in order to download it (may be)

url_wiki : Link to the wiki information of the graph (not defined yet)

JSON

Format:

[{name="name", date="date", url="url", url_wiki="url_wiki"}, {...}, ...]''

Example:

[{name="Total Committers per Year", date="2008-07-09", url="/projects/evince/resources/graphs/comperyear",url_wiki="url_wiki"}]

RSS

Format:

<?xml version="1.0"?>
<rss version="2.0">
  <channel>
    <title>title</title>
    <link>link</link>
    <description>short_desc</description>  
    <item>
      <name>name</name>
      <date>date</name>
      <url>url</url>
      <url_wiki>url</url_wiki>
   </item>
 </channel>
</rss>

Example:

<?xml version="1.0"?>
<rss version="2.0">
  <channel>
    <title>Information about Evince Graphs</title>
    <link>http://melquiades.flossmetrics.org/projects/evince/graphs/comperyear</link>
    <description>This graph...</description>  
    <item>
      <name>Total Committers per Year</name>
      <date>2008-07-09</name>
      <url>/projects/evince/resources/graphs/comperyear</url>
      <url_wiki>url_wiki</url_wiki>
    </item>
  </channel>
</rss>

HTML

Format:

<ul>
  <li><p>name</p> - <p>date</p> - <a href="url">name</a> - <a href="url_wiki">url_wiki</a></li>
</ul>

Example:

<ul>
  <li><p>Total Committer per Year</p> - <p>2008-07-09</p> - <a href="/projects/evince/graphs/comperyear">Total Committers per Year</a> - <a href="url_wiki">url_wiki</a> </li>
</ul>