Bug#824912: tracker.d.o: add an API for action items

[efkin <efkin@riseup.net>]

Hello raphael,

Raphael Hertzog <hertzog@debian.org> writes:

> Hello efkin,
>
> thanks for your work on this but this is the kind of feature where
> we want to push some thoughts in the initial design. So I'll try to do that
> now.

Thx for the review and if you agree with the following notes i would
like to start with this ticket if possible. I thought at the beginning
that it was a specific task, now i realize the opposite. I'm happy to
participate in the API design process.

> On Mon, 12 Dec 2016, efkin wrote:
>> The API endpoint atm just returns a list of dicts with `type_name` and
>> `extra_data`.
>
> It should certainly return all other fields from the ActionItem:
> - type_description
>   => info for the user
> - package
>   => in case we query action items by something else than package
> - short_description
>   => info for the user
> - severity
>   => info for the user
> - created_timestamp
>   => info for the user
> - last_updated_timestamp
>   => info for the user
> - id
>   => in case we later want to support PUT/PATCH/DELETE operations to
>   edit the action item (for example assigning it to someone), we will
>   want need this unique identifier

it makes sense.

>> $ curl http://tracker.dev:8000/api/ibniz/actions
>
> The URL also needs a bit of thought:
> - first I would suggest to use a versioned namespace so that we can create
>   an enhanced version of the API without breaking backwards compatibility
>   so /api/v1/ at the start

great.

> - then I would not put the package name here in the URL, it will conflict
>   with other non-package based API calls and we might want to retrieve
>   action items by maintainer email and not by package too... so I would
>   turn the package name into a GET query parameter.
>   /api/v1/action-items?package=ibniz
>   That let us support other queries like ?maintainer=foo@bar in the
>   future.

great.

> Also the API might be easier to develop/extend with some dedicated Django
> helper applications. Did you look into the existing applications like
> http://www.django-rest-framework.org/ ?

i like this framework a lot even if used just to play around with it;
it has nice testing features. i also saw that there's a debian package
for it so no need for pip.

so my next questions are:

* should we create a dedicated app for the API (called "api")?
* should we change the title of the issue or take it as it is and use it
as an snowpiercer for the API development?
* is it better to discuss these things on irc and then copy-paste on this
thread?
* i saw that the actual view design patterns are to use mainly CBV,
should we go for coherence with this pattern in the API?
* as this task can take some commits, is it okay to clone in my gitlab
  acocunt and then choose from there relevant commits or can i have push
  access to a specific branch or is it just okay for the QA Team to
  handle patches by email?


> Cheers,
> -- 
> Raphaël Hertzog ◈ Debian Developer
>
> Support Debian LTS: http://www.freexian.com/services/debian-lts.html
> Learn to master Debian: http://debian-handbook.info/get/

cheers,

-- 
efkin.