natalie/indefero
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Added the first work on an API.

Browse Source
This commit is contained in:
Loic d'Anterroches 2008-11-21 20:33:39 +01:00
parent 0e725bea26
commit 9814a75f82
12 changed files with 305 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
src/IDF/Middleware.php
View File

@ -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
* /p/(\w+)/whatever. This means that it will not try to match on
* /login/ or /logout/.
* The url to match a project is in the format /p/(\w+)/whatever
* or /api/p/(\w+)/whatever. This means that it will not try to
* 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) {

32
src/IDF/Precondition.php
View File

@ -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;
}
}

16
src/IDF/Views.php
View File

@ -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.
*

110
src/IDF/Views/Api.php Normal file
View File

@ -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();
}
}

38
src/IDF/Views/Issue.php
View File

@ -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,
'page_title' => $title,
'open' => $open,
'closed' => $closed,
'issues' => $pag,
'cloud' => 'issues',
),
$request);
$params, $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(
array('project' => $prj,
'form' => $form,
'page_title' => $title,
),
$arrays),
$request);
$params, $request);
}
public $search_precond = array('IDF_Precondition::accessIssues');

4
src/IDF/Views/User.php
View File

@ -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);
}

20
src/IDF/conf/urls.php
View File

@ -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;

2
src/IDF/templates/idf/base-simple.html
View File

@ -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>

2
src/IDF/templates/idf/base.html
View File

@ -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">

83
src/IDF/templates/idf/faq-api.html Normal file
View File

@ -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}

6
src/IDF/templates/idf/faq.html
View File

@ -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}

8
src/IDF/templates/idf/user/myaccount.html
View File

@ -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>