Roundup Tracker - Issues

Issue 2550734

classification
Title: Expose roundup via a RESTful interface.
Type: rfe Severity: normal
Components: Web interface Versions:
process
Status: new Resolution:
Dependencies: xmlrpc interface in cgi is invoked on content type and not url path
View: 2550749
Superseder:
Assigned To: Nosy List: pefu, rouilj
Priority: Keywords: Effort-Medium, GSOC

Created on 2011-10-26 00:07 by rouilj, last changed 2016-03-10 08:22 by pefu.

Messages
msg4459 Author: [hidden] (rouilj) Date: 2011-10-26 00:07
From the thread including:

http://sourceforge.net/mailarchive/forum.php?thread_name=4EA4A0CC.3030802%40seefeld.name&forum_name=roundup-devel

On 10/22/2011 09:23 PM, John P. Rouillard wrote:
> I seem to remember somebody posting/mentioning a set of patches to
> roundup that implemented a restful interface for roundup some time ago.

In message <4EA36F33.1040303@...> on 22 Oct 2011 Stefan
Seefeld asked:
>I'm not entirely sure what you mean by 'restful'.

See: http://developer.mindtouch.com/REST/REST_for_the_Rest_of_Us

The basic url is a resource/noun
(https://roundup-tracker.org/tracker/status2 for example) and
uses the http(s) functions of:

  GET - retrieve data about the resource
  POST - creating new resources
  PUT - updating a resource
  DELETE - to retire/delete a resource

with the semantic requirements that:

  GET - must never change any data (idempotent).

  POST - can change data every time it's called, if called multiple times
         can generate new resources every time it's called (not
         idempotent).

  PUT - can be called multiple times without changing the end state of
        the system (idempotent)

  DELETE - can be called multiple times without changing end
           state (idempotent).

So a POST to https://roundup-tracker.org/tracker/status with data:

Headers:
  Accept: application/json
  Content-Type: text/json

Body:

  { "description": "Work is paused pending another ticket getting resolved",
    "name": "paused",
    "order": 5.0
  }

Response:

  HTTP/1.1 200 OK

  { "link": "https://roundup-tracker.org/tracker/status5" }

will create a new status. If posted again, it would create
another new status (in theory only since name is required to be
unique it would fail. However consider the case where it was
creating message).

Doing a PUT operation with the same headers/data to
https://roundup-tracker.org/tracker/status4 would change the
defintion of the status with id 4. With a possible response of

{ "status": "ok"}

Repeating the PUT operation 1 or 1000 times would still result in
the same values for https://roundup-tracker.org/tracker/status4
and wouldn't change anything else.

Also a PUT operation to:

  https://roundup-tracker.org/tracker/issue2300/status

Headers:
  Accept: application/json
  Content-Type: text/json

Body:

  { "value": 1 }

Response:

A GET operation on https://roundup-tracker.org/tracker/status
would return:

[ { "id": 1, "link": "https://roundup-tracker.org/tracker/status1" },
  { "id": 2, "link": "https://roundup-tracker.org/tracker/status2" },
  { "id": 3, "link": "https://roundup-tracker.org/tracker/status3" },
  { "id": 4, "link": "https://roundup-tracker.org/tracker/status4" } ]


and a GET on one of the links above would result in something like:

  { "id": 4,
    "description":"User feedback required",
    "name": "pending",
    "order": 4.0 }

Repeating either GET would result in the same data (assuming no
POST/PUT/DELETE operations occured in the interim).

A DELETE operation on https://roundup-tracker.org/tracker/status4
would retire the status, and a re-DELETE would result in no
change.

>I did add support for jquery (specifically, in the 'devel'
>tracker, in the user index templates). I would love to see the
>"batch" processing be improved to use jquery, but haven't
>managed to work on this (yet). Did you think of that?

I know you can do rest calls from jquery (and json would be a
useful input/output format) but AFAIK there isn't support for
anything expect POST/GET.

Hopefully that explains what I mean better.

    	
    Re: [Roundup-devel] Is there a RESTful interface for roundup?
    From: Stefan Seefeld <stefan@se...> - 2011-10-23 23:18

    On 2011-10-23 18:52, John P. Rouillard wrote:

    [...]

    > Hopefully that explains what I mean better.

    It does indeed, thanks !

    Yes, I think it would be great to have something for this in Roundup;
    perhaps modeled after the roundup.xmlrpc module (and integration into
    roundup.cgi.client).

    This would allow for tracker templates to become more dynamic, as well
    as entirely new client-side applications to be written.

        Stefan
msg4810 Author: [hidden] (rouilj) Date: 2013-02-25 16:52
issue2550797 "Support AJAX for web frontends." should be made easier by
implementing this issue.
msg5368 Author: [hidden] (rouilj) Date: 2015-09-06 15:08
Googe Summer of Code 2015 has produced a patch for this.

From the roundup mailing list:

Date:    Sun, 06 Sep 2015 14:36:39 +0300
To:      roundup-devel 
cc:      Hieu Nguyen <hieuh25ATgmail.com>, dangchau1991ATgmail.com

From:    Ezio Melotti <ezio.melottiATgmail.com>
Subject: [Roundup-devel] REST interface -- GSoC Project Report

Hi,
Google Summer of Code is now over, and I'm glad to inform you that the
project "Adding a REST API to Roundup" has been completed.  The work
has been done on the Roundup clone used for bugs.python.org, since we
plan to integrate it and test it there first.  The changes shouldn't
affect any b.p.o-specific parts though, so you should be able to apply
the changes on a regular Roundup clone too.  I eventually plan to port
this to upstream Roundup if it proves successful on b.p.o, but my
resources are currently limited, so you are welcomed to beat me to it.

You can find the code at
https://bitbucket.org/kinggreedy1991/roundup-bpo , more information
about the project at https://bpaste.net/show/7e2303d2aa7a , and the
related core-workflow thread with more information (including another
related project) at
https://mail.python.org/pipermail/core-workflow/2015-September/000220.html
.

Best Regards,
Ezio Melotti

==== from bpaste:

=======================
RESTful API for Roundup
=======================


description
------------

The Restful API for Roundup is built up to provide an interface to
communicate
through HTTP. Using the provided API, users can easily access and get data
from Roundup.


source
-------

repo: https://bitbucket.org/kinggreedy1991/roundup-bpo


deploy
-------

a. Setup a b.p.o tracker and apply patch file located at
  
https://bitbucket.org/kinggreedy1991/roundup-bpo/downloads/roundupRestfulAPI.patch

b. Or setup a tracker from the source repo, branch REST


usage
------

1. Documentation Repository is located at 
   https://bitbucket.org/kinggreedy1991/restfulapidocumentation

   The documentation is based on Swagger-UI and need a web server to view.

   a. The project documentation is located inside ProjectDocumentation
folder.

   b. If you want to try the operations, you need to use a detailed version 
      located in DocumentationForTesting. However, this documentation is not
      correct in general case.

2. The RESTful API start with '/rest'

   Example: Tracker location is http://bugs.python.org/ ,
            Restful service will be located at: http://bugs.python.org/rest/

3. You can add new custom URI to the Restful service by making URL Route
   Registrations:

    3.1. Add a new function to class RestfulInstance at roundup/rest.py

         The new function can receive the submitted form by declaring
``input``
         in the parameter

              def summary(self, input)

         Your function must return an ``array`` that will be converted to 
         json string by the module.
      
    3.2. Use ``Routing.route()`` decorator

         Variable parts in the route can be specified with angular brackets
         starting with colon (/data/<:user>). The variable part in the URL
         accepts any string without a slash.

         Variable parts are passed to the function as keyword arguments.
         Variable type is string.

         Trailing slashes will be stripped, leading 'rest/' will also be
         stripped.

         You can also apply multiple route for the same function. 2
routes are
         considered different if rule is different or the method is
different.

             @Routing.route('/issue/')
             @Routing.route('/class/issue/<:issue_id>')
             @Routing.route('/class/issueattr/', methods = ['POST', 'PUT'])
             def get_issue(page):
                 pass

          Here are the parameters that Routing.route(rule, methods) accept.

            rule (string): the URL rule

            methods (string or tuple or list): the http method(s) will be
                handled by the function. Default value is ``GET``

    3.3. Use ``_data_decorator()`` if you want to handle error and
formatting 
         automatically


notes
------

If you cannot access the restful through your browser, try cleaning the
cache
files (roundup/cgi/client.py, roundup/scripts/roundup_server.py) and
reinstall
the tracker.
======

Also the email:

  https://mail.python.org/pipermail/core-workflow/2015-September/000220.html

discusses a mercurial integration as well

=====

Some questions I have are:

 Can a tracker add its own routes without changing the base roundup
 code? (Similar to how you can add functions, attributes and classes.)

 It would be nice to have a pdf or single page html document of the
 rest api. Maybe swagger can do that, I am not sure.
msg5492 Author: [hidden] (pefu) Date: 2016-03-10 08:22
Just a note: 
maciej.szulik has published a patch which adds a 
RESTful API to Roundup and I found it here:

http://psf.upfronthosting.co.za/roundup/meta/issue581

The latest version of his patch can be found here:
http://psf.upfronthosting.co.za/roundup/meta/file385/rest.diff

On the first glance this seems to be an independent implementation
of the same feature.
  
Best regards, Peter.
History
Date User Action Args
2016-03-10 08:22:10pefusetnosy: + pefu
messages: + msg5492
2015-09-06 15:08:44rouiljsetmessages: + msg5368
2013-02-25 16:52:47rouiljsetmessages: + msg4810
2013-02-25 16:46:07rouiljsetkeywords: + Effort-Medium, GSOC
2012-09-05 14:17:37rouiljsetdependencies: + xmlrpc interface in cgi is invoked on content type and not url path
2011-10-26 00:07:21rouiljcreate