From OpenForge

Written in 2008.
Version 0.1

Brief description

OpenForge is an API (Application Programming Interface) that allows different forge to communicate each others. All the work is focused on interoperability.

With this API, you can imagine a lot of features based on the aims:

• retrieve project's datas
• retrieve user's datas
• search an user or a project

This document was originally written for communication between CodingTeam and ShareSource. All outputs are in XML.

Versions

OpenForge has only one version:

• 0.1

Implementation

This section is list of requirements or advices to implement OpenForge in your software. Please read carefully and see the difference between "could" and "should".

• You should not have projects and users with a " " (space) within the name.
• You should use an URL like http://www.example.org/api/*
• You should use project/projectname for projects, user/username for users and search/keyword for search.
• Empty results could returns an empty <project/>, <user/> or <search/>

XML file skeleton

A OpenForge result's file will be something like that:

 <?xml version='1.0' encoding='UTF-8'?>
 <openforge>
   <forge>
     <name></name>
     <url></url>
     <version></version>
     <apiversion></apiversion>
   </forge>
 
   [1]
 </openforge>

The <forge/> contains informations about API and forge compatibility. Indeed, <name/> is the name of the forge, <url/> is the URL of the forge, <version/> is the version of forge and <apiversion/> the version of the OpenForge API.

[1] will contains the wanted XML output (see sections 5, 6 and 7).

Projects

Here is a default output for project's datas:

 <project>
   <name></name>
   <title></title>
   <state common=""></state>

   <downloads></downloads>

   <administrators>
     <administrator></administrator>
   </administrators>

   <developers>
     <developer></developer>
     <developer></developer>
   </developers>

   <date></date>

   <description>
   </description>

   <info>
     <licenses>
       <license common=""></license>
     </licenses>
       
     <languages>
       <language common=""></language>
     </languages>
   </info>

   <url>
     <home></home>
     <download></download>
     <screenshot></screenshot>
   </url>
 </project>

<name/> is the name of the project in tiny characters, that correponds to this regular expression: [0-9a-z_-]. <title/> is the name of the project without any rules. <state/> has a value and a "common" attribute. To know what are the possible values, see the Appendice A.

<downloads/> is the number of downloads for the whole project.

<administrators/> and <developers/> contains both <administrator/> and <developer/> fields for each users. Usernames retrieved have to be accessible with the user's data fetching (see section 6).

<date/> is the date of the project's submition. The date have to be in the following format: RFC-822.

<description/> contains the project's description. The text could use several lines and contains escaped HTML/XHTML.

<info/> contains two blocks:

• <licenses/> could had more than one <license/> field. To setup the value and the "common" attribute, see the Appendice B.
• <languages/> could had more than one <language/> field. To setup the value and the "common" attribute, see the Appendice C.

<url/> should contains at least three fields:

• <home/> that is the link to the project's homepage
• <download/> that is the link to the project's download page
• <screenshot/> that is the link to the project's screenshot page

You are allowed to add others links as long as these three links are already supported.

Users

Here is a default output for user's datas:

 <user>
   <nickname></nickname>
   <firstname></firstname>
   <lastname></lastname>

   <date></date>

   <projects>
     <project></project>
     <project></project>
     <project></project>
   </projects>
 </user>

<nickname/> is the nickname of the user that corresponds to this regular expression: [0-9A-Za-z_-] and can be accessible with the user's data fetching. <firstname/> and <lastname/> just contains firstname and lastname of an user.

<date/> is the date of the user's registration. The date have to be in the following format: RFC-822.

<projects/> contains a <project/> for each projects the ser is involved.

Search

Here is a default output for search result's datas:

 <search>
   <users>
     <user nickname="" firstname="" lastname="" url="">
   </users>
   
   <projects>
     <project name="" title="" url="">
     <project name="" title="" url="">
   </projects>
 </search>

Specifications are in sections 5 and 6. The "url" attribute should provide a link to the resource:

• for projects, the equivalent to <url/> → <home/>
• for users, a link to the profile webpage

This should not send more than twenty results for users and twenty results for projects. Also, search results should be ordered from newer to older.

Appendice A

<state/> possible values

The "common" attribute should be one of them:

• planned
• development
• testing
• alpha
• beta
• stable
• abandonned

The value can be translated and you could write anything you want. The better way is to send "Planned" for "planned", "Development" for "development"...

It is allowed to add more states as long as all theses states are supported.

Appendice B

<licence/> possible values

As they are a big number of licenses and everyone can write his own license, it is allowed to use every license you want. You should use this way to write the "common" attribute :

• GNU General Public License becomes "gnugpl"
• Apache License 2.0 becomes "al20"
• CeCILL becomes "cecill"

Appendice C

<language/> possible values

Here is default a list of "common" attribute and field values:

• abap for: ABAP
• actionscript for: ActionScript
• ada for: Ada
• applescript for: AppleScript
• asm for: ASM (NASM based)
• asp for: ASP
• autoit for: AutoIT
• bash for: Bash
• blitzbasic for: BlitzBasic
• bnf for: Backus-Naur form
• c for: C
• caddcl for: CAD DCL
• cadlisp for: CAD Lisp
• cfdg for: CFDG
• cfm for: ColdFusion
• cpp for: C++
• csharp for: C#
• css for: CSS
• d for: D
• delphi for: Delphi
• diff for: Diff
• div for: DIV
• dos for: DOS
• dot for: GraphViz
• eiffel for: Eiffel
• fortran for: Fortran
• freebasic for: FreeBasic
• genero for: Genero (4GL)
• gml for: GML
• groovy for: Groovy
• haskell for: Haskell
• idl for: Uno IDL
• inno for: Inno
• io for: IO
• java for: Java
• java5 for: Java 5
• javascript for: Javascript
• latex for: LaTeX
• lisp for: Lisp
• lua for: Lua
• m68k for: Motorola 68000 Assembler
• matlab for: Matlab
• mpasm for: MPASM
• mysql for: MySQL
• objc for: Objective C
• ocaml for: OCaml
• oobas for: Openoffice.org BASIC
• oracle8 for: Oracle 8
• pascal for: Pascal
• per for: Per (4GL)
• perl for: Perl
• php for: PHP
• plsql for: PL/SQL
• python for: Python
• qbasic for: QBasic/QuickBASIC
• rails for: Rails
• ruby for: Ruby
• sas for: SAS
• scheme for: Scheme
• sdlbasic for: SDLBasic
• smalltalk for: Smalltalk
• smarty for: Smarty
• sql for: SQL
• tcl for: TCL
• text for: Plain text
• thinbasic for: thinBasic
• tsql for: T-SQL
• vb for: VisualBasic
• vbnet for: VB.NET
• vhdl for: VHDL
• visualfoxpro for: VisualFoxPro
• winbatch for: Winbatch
• xml for: XML
• xpp for: X++
• z80 for: Z80 Assembler

It is allowed to add more languages as long as all theses languages are supported.

This document was written by:

 - Erwan Briand <erwan [(at)] codingteam.net>
 - Tim Groeneveld <tim [(at)] sharesource.org>

License of the document is GNU General Public License, version 3 only. See: http://www.gnu.org/licenses/gpl.txt