Added the first work on an API.
Loic d'Anterroches
parent
0e725bea26
commit
9814a75f82
|
|
@ -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) {
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
}
|
||||
}
|
||||
|
|
@ -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.
|
||||
*
|
||||
|
|
|
|||
|
|
@ -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();
|
||||
}
|
||||
}
|
||||
|
|
@ -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');
|
||||
|
|
|
|||
|
|
@ -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);
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
|
||||
|
|
|
|||
|
|
@ -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">
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
<?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);
|
||||
?>
|
||||
</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}
|
||||
|
|
@ -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}
|
||||
|
|
|
|||
|
|
@ -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> </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>
|
||||
|
|
|
|||
Loading…
Reference in New Issue