Added the first work on an API.

src/IDF/Middleware.php

@@ -34,9 +34,9 @@ class IDF_Middleware
      * When processing the request, check if matching a project. If
      * so, directly set $request->project to the project.
      *
-     * The url to match a project is in the format
+     * The url to match a project is in the format /p/(\w+)/whatever
-     * /p/(\w+)/whatever. This means that it will not try to match on
+     * or /api/p/(\w+)/whatever. This means that it will not try to
-     * /login/ or /logout/.
+     * match on /login/ or /logout/.
      *
      * @param Pluf_HTTP_Request The request
      * @return bool false or redirect.
@@ -44,7 +44,7 @@ class IDF_Middleware
     function process_request(&$request)
     {
         $match = array();
-        if (preg_match('#^/p/([\-\w]+)/#', $request->query, $match)) {
+        if (preg_match('#^/(?:api/p|p)/([\-\w]+)/#', $request->query, $match)) {
             try {
                 $request->project = IDF_Project::getOr404($match[1]);
             } catch (Pluf_HTTP_Error404 $e) {

src/IDF/Precondition.php

@@ -142,4 +142,36 @@ class IDF_Precondition
         }
         return self::accessTabGeneric($request, 'downloads_access_rights');
     }
+
+    /**
+     * Based on the request, it is automatically setting the user.
+     *
+     * API calls are not translated.
+     */
+    static public function apiSetUser($request)
+    {
+        // REQUEST is used to be used both for POST and GET requests.
+        if (!isset($request->REQUEST['_hash'])
+            or !isset($request->REQUEST['_login'])
+            or !isset($request->REQUEST['_salt'])) {
+            // equivalent to anonymous access.
+            return true;
+        }
+        $db =& Pluf::db();
+        $true = Pluf_DB_BooleanToDb(true, $db);
+        $sql = new Pluf_SQL('login=%s AND active='.$true,
+                            $request->REQUEST['_login']);
+        $users = Pluf::factory('Pluf_User')->getList(array('filter'=>$sql->gen()));
+        if ($users->count() != 1) {
+            // Should return a special authentication error like user
+            // not found.
+            return true;
+        }
+        $hash = sha1($request->REQUEST['_salt'].sha1($users[0]->password));
+        if ($hash != $request->REQUEST['_hash']) {
+            return true; // Again need authentication error
+        }
+        $request->user = $users[0];
+        return true;
+    }
 }

src/IDF/Views.php

@@ -184,6 +184,22 @@ class IDF_Views
 
     }
 
+    /**
+     * API FAQ.
+     */
+    public function faqApi($request, $match)
+    {
+        $title = __('InDefero API (Application Programming Interface)');
+        $projects = self::getProjects($request->user);
+        return Pluf_Shortcuts_RenderToResponse('idf/faq-api.html', 
+                                               array(
+                                                     'page_title' => $title,
+                                                     'projects' => $projects,
+                                                     ),
+                                               $request);
+
+    }
+
     /**
      * Returns a list of projects accessible for the user.
      *

src/IDF/Views/Api.php

@@ -0,0 +1,110 @@
+<?php
+/* -*- tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
+/*
+# ***** BEGIN LICENSE BLOCK *****
+# This file is part of InDefero, an open source project management application.
+# Copyright (C) 2008 Céondo Ltd and contributors.
+#
+# InDefero is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# InDefero is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+#
+# ***** END LICENSE BLOCK ***** */
+
+/**
+ * API views.
+ *
+ * These are just small wrappers around the "normal" views. The normal
+ * views are called with a third parameters $api set to true to return
+ * JSON instead of HTML.
+ *
+ * A special precondition is used to set the $request->user from the
+ * _login, _hash and _salt parameters. 
+ */
+class IDF_Views_Api
+{
+    /**
+     * View list of issues for a given project.
+     */
+    public $issuesIndex_precond = array('IDF_Precondition::apiSetUser',
+                                        'IDF_Precondition::accessIssues');
+    public function issuesIndex($request, $match)
+    {
+        $views = new IDF_Views_Issue();
+        $p = $views->index($request, $match, true);
+        $out = array(
+                     'project' => $request->project->shortname,
+                     'open' => $p['open'],
+                     'closed' => $p['closed'],
+                     'issues' => $p['issues']->render_array(),
+                     );
+        return new Pluf_HTTP_Response_Json($out);
+    }
+
+    /**
+     * Create a new issue.
+     */
+    public $issueCreate_precond = array('IDF_Precondition::apiSetUser',
+                                        'IDF_Precondition::accessIssues');
+    public function issueCreate($request, $match)
+    {
+        $views = new IDF_Views_Issue();
+        $p = $views->create($request, $match, true);
+        $out = array();
+        if ($request->method == 'GET') {
+            // We give the details of the form
+            $out['doc'] = 'A POST request against this url will allow you to create a new issue.';
+            if ($request->user->hasPerm('IDF.project-owner', $request->project)
+                or $request->user->hasPerm('IDF.project-member', $request->project)) {
+                $out['status'] = array();
+                foreach (self::getTags($request->project) as $tag) {
+                    $out['status'][] = $tag->name;
+                }
+            }
+
+        } else {
+            // We need to give back the results of the creation
+            if (is_object($p) and 'IDF_Issue' == get_class($p)) {
+                $out['mess'] = 'success';
+                $out['issue'] = $p->id;
+            } else {
+                $out['mess'] = 'error';
+                $out['errors'] = $p['form']->errors;
+            }
+        }
+        return new Pluf_HTTP_Response_Json($out);
+    }
+
+    /**
+     * Get the list of tags to give them to the end users when doing a
+     * GET request against a form. That way it is possible for them to
+     * know which tags/labels are available.
+     *
+     * @param IDF_Project Current project
+     * @param string Which tags to get ('issue-open')
+     * @return ArrayObject Tags
+     */
+
+    public static function getTags($project, $what='issue-open')
+    {
+        switch ($what) {
+        case 'issue-open':
+            $key = 'labels_issue_open';
+            $default = IDF_Form_IssueTrackingConf::init_open;
+            return $project->getTagsFromConfig($key, $default);
+        case 'issue-closed':
+            return $project->getTagIdsByStatus('closed');
+        }
+        return array();
+    }
+}

src/IDF/Views/Issue.php

@@ -35,7 +35,7 @@ class IDF_Views_Issue
      * View list of issues for a given project.
      */
     public $index_precond = array('IDF_Precondition::accessIssues');
-    public function index($request, $match)
+    public function index($request, $match, $api=false)
     {
         $prj = $request->project;
         $title = sprintf(__('%s Open Issues'), (string) $prj);
@@ -65,15 +65,15 @@ class IDF_Views_Issue
         $pag->items_per_page = 10;
         $pag->no_results_text = __('No issues were found.');
         $pag->setFromRequest($request);
+        $params = array('project' => $prj,
+                        'page_title' => $title,
+                        'open' => $open,
+                        'closed' => $closed,
+                        'issues' => $pag,
+                        'cloud' => 'issues');
+        if ($api) return $params;
         return Pluf_Shortcuts_RenderToResponse('idf/issues/index.html',
-                                               array('project' => $prj,
+                                               $params, $request);
-                                                     'page_title' => $title,
-                                                     'open' => $open,
-                                                     'closed' => $closed,
-                                                     'issues' => $pag,
-                                                     'cloud' => 'issues',
-                                                     ),
-                                               $request);
     }
 
     /**
@@ -133,7 +133,7 @@ class IDF_Views_Issue
 
     public $create_precond = array('IDF_Precondition::accessIssues',
                                    'Pluf_Precondition::loginRequired');
-    public function create($request, $match)
+    public function create($request, $match, $api=false)
     {
         $prj = $request->project;
         $title = __('Submit a new issue');
@@ -169,20 +169,22 @@ class IDF_Views_Issue
                     $email->addTextMessage($tmpl->render($context));
                     $email->sendMail();
                 }
+                if ($api) return $issue;
                 return new Pluf_HTTP_Response_Redirect($url);
             }
         } else {
             $form = new IDF_Form_IssueCreate(null, $params);
         }
-        $arrays = self::autoCompleteArrays($prj);
+        $params = array_merge(
+                              array('project' => $prj,
+                                    'form' => $form,
+                                    'page_title' => $title,
+                                    ),
+                              self::autoCompleteArrays($prj)
+                              );
+        if ($api == true) return $params;
         return Pluf_Shortcuts_RenderToResponse('idf/issues/create.html',
-                                               array_merge(
+                                               $params, $request);
-                                               array('project' => $prj,
-                                                     'form' => $form,
-                                                     'page_title' => $title,
-                                                     ),
-                                               $arrays),
-                                               $request);
     }
 
     public $search_precond = array('IDF_Precondition::accessIssues');

src/IDF/Views/User.php

@@ -38,6 +38,9 @@ class IDF_Views_User
     public $myAccount_precond = array('Pluf_Precondition::loginRequired');
     public function myAccount($request, $match)
     {
+        // As the password is salted, we can directly take the sha1 of
+        // the salted password.
+        $api_key = sha1($request->user->password);
         $params = array('user' => $request->user);
         if ($request->method == 'POST') {
             $form = new IDF_Form_UserAccount($request->POST, $params);
@@ -52,6 +55,7 @@ class IDF_Views_User
         }
         return Pluf_Shortcuts_RenderToResponse('idf/user/myaccount.html', 
                                                array('page_title' => __('Your Account'),
+                                                     'api_key' => $api_key,
                                                      'form' => $form),
                                                $request);
     }

src/IDF/conf/urls.php

@@ -272,4 +272,24 @@ $ctl[] = array('regex' => '#^/p/([\-\w]+)/admin/tabs/$#',
                'model' => 'IDF_Views_Project',
                'method' => 'adminTabs');
 
+// ---------- API ----------------------------------------
+
+$ctl[] = array('regex' => '#^/help/api/$#',
+               'base' => $base,
+               'priority' => 4,
+               'model' => 'IDF_Views',
+               'method' => 'faqApi');
+
+$ctl[] = array('regex' => '#^/api/p/([\-\w]+)/issues/$#',
+               'base' => $base,
+               'priority' => 4,
+               'model' => 'IDF_Views_Api',
+               'method' => 'issuesIndex');
+
+$ctl[] = array('regex' => '#^/api/p/([\-\w]+)/issues/create/$#',
+               'base' => $base,
+               'priority' => 4,
+               'model' => 'IDF_Views_Api',
+               'method' => 'issueCreate');
+
 return $ctl;

src/IDF/templates/idf/base-simple.html

@@ -35,7 +35,7 @@
   <div id="hd">
     <p class="top"><a href="#title" accesskey="2"></a>
 {if !$user.isAnonymous()}{aurl 'url', 'IDF_Views_User::myAccount'}{blocktrans}Welcome, <strong><a class="userw" href="{$url}">{$user}</a></strong>.{/blocktrans} <a href="{url 'IDF_Views::logout'}">{trans 'Sign Out'}</a>{else}<a href="{url 'IDF_Views::login'}">{trans 'Sign in or create your account'}</a>{/if}
-| <a href="{url 'IDF_Views::faq'}">{trans 'Help'}</a>
+| <a href="{url 'IDF_Views::faq'}" title="{trans 'Help and accessibility features'}">{trans 'Help'}</a>
     </p>
 	  <h1 id="title" class="title">{block title}{$page_title}{/block}</h1>
 

src/IDF/templates/idf/base.html

@@ -37,7 +37,7 @@
     <p class="top"><a href="#title" accesskey="2"></a>
 {if !$user.isAnonymous()}{aurl 'url', 'IDF_Views_User::myAccount'}{blocktrans}Welcome, <strong><a class="userw" href="{$url}">{$user}</a></strong>.{/blocktrans} <a href="{url 'IDF_Views::logout'}">{trans 'Sign Out'}</a>{else}<a href="{url 'IDF_Views::login'}">{trans 'Sign in or create your account'}</a>{/if}
 {if $project} | <a href="{url 'IDF_Views::index'}">{trans 'Project List'}</a>{/if}
-| <a href="{url 'IDF_Views::faq'}">{trans 'Help'}</a>
+| <a href="{url 'IDF_Views::faq'}" title="{trans 'Help and accessibility features'}">{trans 'Help'}</a>
     </p>
 <div id="header">
 <div id="main-tabs">

src/IDF/templates/idf/faq-api.html

@@ -0,0 +1,83 @@
+{extends "idf/base-simple.html"}
+{block docclass}yui-t3{/block}
+{block body}
+<p>At the moment, this documentation is only available in English.</p>
+
+<ul>
+<li><a href="#q-overview">How to access the API?</a></li>
+<li><a href="#q-authentication">How to authenticate the queries?</a></li>
+</ul>
+
+<h2 id="q-overview">How to access the API?</h2>
+
+<p>
+The API is a REST API and you can access it by using the same URL you
+are using for the web interface but with the <code>/api/</code>
+prefix.
+</p>
+<p>
+For example, if you access a project with the
+URL <code>http://www.example.com/p/myproject/</code>, you have the
+following API URLs available:
+</p>
+<ul>
+<li><code>http://www.example.com/api/p/myproject/issues/</code>: list the open issues.</li>
+<li><code>http://www.example.com/api/p/myproject/issues/create/</code>: create a new issue.</li>
+</ul>
+<p>
+The answer you get is JSON and UTF-8 encoded. 
+</p>
+
+
+<h2 id="q-authentication">How to authenticate the queries?</h2>
+
+<p>
+Authentication is really simple and is optional. If you do not
+authenticate your queries, you will have the same rights as an
+anonymous user visiting the normal web interface.
+</p>
+<p>
+To authenticate your query, you need to provide 3 parameters to your
+requests, the parameters are the followings:
+</p>
+<ul>
+<li><code>_login</code>: your login.</li>
+<li><code>_salt</code>: a random salt string.</li>
+<li><code>_hash</code>: the sha1 hash created from the concatenation of the random salt string and the API key.</li>
+</ul>
+<p>
+Please note that the 3 parameters are all starting with the underscore
+"_" character. 
+</p> 
+<p>
+An example of PHP code to generate the <code>_hash</code> value is:
+</p>
+<pre>
+&lt;?php 
+$api_key = '1234567890abcdefghijklmnopqrstuvwxyz';
+$_salt = rand(10000, 999999);
+$_hash = sha1($_salt.$api_key);
+echo sprintf("_salt: %s\n", $_salt);
+echo sprintf("_hash: %s\n", $_hash);
+?&gt;
+</pre>
+<p>
+If you replace the string '123...xyz' with your own API key and
+execute this script, you will have as output something like that:
+</p>
+<pre>
+_salt: 123456
+_hash: 1357924680acegikmoqsuwybdfhjlnprtvxz
+</pre>
+<p>
+Together with your login, you will be able to use those values to
+authenticate a query.
+</p>
+
+{/block} {block context}
+<p>{trans 'Here we are, just to help you.'}</p>
+<h2>{trans 'Projects'}</h2>
+<ul>{foreach $projects as $p}
+<li><a href="{url 'IDF_Views_Project::home', array($p.shortname)}">{$p}</a></li>
+{/foreach}</ul>
+{/block}

src/IDF/templates/idf/faq.html

@@ -4,6 +4,7 @@
 <ul>
 <li><a href="#q-keyboard">{trans 'What are the keyboard shortcuts?'}</a></li>
 <li><a href="#q-duplicate">{trans 'How to mark an issue as duplicate?'}</a></li>
+<li><a href="#q-api">{trans 'What is the API and how to use it?'}</a></li>
 </ul>
 
 <h2 id="q-keyboard">{trans 'What are the keyboard shortcuts?'}</h2>
@@ -37,6 +38,11 @@
 <li>Change the status of the current issue to <em>Duplicate</em>.</li>
 <li>Submit the changes.</li>
 </ol>{/blocktrans}
+
+<h2 id="q-api">{trans 'What is the API and how to use it?'}</h2>
+
+<p>{blocktrans}The API (Application Programming Interface) is used to interact with InDefero with another program. For example, this can be used to create a desktop program to submit new tickets easily.{/blocktrans}</p>{aurl 'url', 'IDF_Views::faqApi'}
+<p>{blocktrans}<a href="{$url}">Learn more about the API</a>.{/blocktrans}</p>
  
 {/block}
 {block context}

src/IDF/templates/idf/user/myaccount.html

@@ -41,6 +41,12 @@
 </td>
 </tr>
 <tr>
+<th>{trans 'API key'}:</th>
+<td><span class="mono">{$api_key}</span><br />
+<span class="helptext">{trans 'Your API key will automatically be regenerated if you change your password.'}</span>
+</td>
+</tr>
+<tr>
 <td>&nbsp;</td>
 <td><input type="submit" value="{trans 'Update Your Account'}" name="submit" /> | <a href="{url 'IDF_Views::index'}">{trans 'Cancel'}</a>
 </td>
@@ -51,7 +57,9 @@
 {block context}
 <div class="issue-submit-info">
 <p>{trans 'If possible, use your real name. By using your real name, people will have more trust in your comments and remarks.'}</p>
+<p>{trans 'The API key is used to interact with this website using a program.'}</p>
 </div>{/block}
+
 {block javascript}<script type="text/javascript">
 document.getElementById('id_first_name').focus()
 </script>