Re: Migrating debbugs' SOAP interface to JSON
On 07.12.18 05:23, Don Armstrong wrote:
On Thu, 06 Dec 2018, Bastian Venthur wrote:
I'm Bastian the developer of python-debianbts, the library that is used by
reportbug to query the BTS.
First of all, I'm really happy that we have an API that allows to query the
BTS, and the current interface is *a lot* better than the HTML parsing that
we did 10 years ago. However, while SOAP was state of the art a while ago,
it has it's limitations. The most severe one for us: it's getting harder and
harder to find libraries that parse SOAP properly in Python and trying to
parse SOAP replies "by hand" seems daunting.
Yeah, I totally agree that we should move to replace SOAP.
My long-standing plan is to have it replaced with a REST API that
returns json or html (maybe even xml?) depending on the Accepts: header.
I'd certainly love to see someone write a good specification for that
API using openAPI (swagger) which I (or someone else) could then work to
write the perl backend to the BTS to spit out that API.
Good to hear! To start it off, I've created a swagger spec that is
faithful to the current setup:
https://github.com/venthur/debbugs-proposal/blob/master/yaml-unresolved/swagger.yaml
The only changes so far:
* renamed `get_foo` methods to `foo`, the "get_" part is implied by the
HTTP verb `GET`
* complex parameters are passed as JSON
* Return values are JSON
There is another branch in this repo `SWAGGERHUB` that is connected to
swaggerhub, which I use to make changes. The changes are pushed to the
branch automatically but not the other way round. This makes it tricky
to collaborate, since only I can edit in swaggerhub.
However you can see the current status of the `SWAGGERHUB` branch here:
https://app.swaggerhub.com/apis-docs/venthur/debbugs/1.0.0
If you want to take over the repo as owner, that's fine with me. I can
also manually merge the current best version to `master` and others make
PRs against that branch, I don't really mind.
As next steps I propose to improve the `Status` data type (i.e. the
return value of the former `get_status`:
* do we really need all fields?
* the `done` field is currently a maintainer or empty if not closed,
maybe we can introduce `status` with the possible states: `open`,
`pending`, `closed`, `archived` and introduce an optional `closed_by`:
<maintaine>, this way we could also get rid of `archived`,
`pending` and `unarchived`
Cheers,
Bastian
Reply to: