=  PTS SOAP Interface =

The [[PTS|Package Tracking System]] (PTS) gathers information about
(source) packages and meld them together in
[[http://packages.qa.debian.org|web pages]] targeted at package
maintainers. Those pages are meant for consumption by humans.

On the other hand, there is often the need to access the very same
information programmatically, from software and utilities. To aid in
that respect, the PTS offers a '''SOAP interface''' to the content
exported in its pages.

'''BIG FAT WARNING:''' the SOAP API is still '''work in progress''', and
methods are being added continuously until all information available
on the web pages are available also via SOAP. Please hold your breath.

<<TableOfContents(2)>>

== URL and Namespace ==

`http://packages.qa.debian.org/cgi-bin/soap-alpha.cgi` is the
current URL for the '''development alpha version''' of the PTS SOAP
API.

As you have guessed, the API is still subject to changes, please test
it and send '''comments''' to [[mailto:zack@debian.org|zack]]. If instead of
comments you have '''bug reports''' (misbehaving methods, wishlist for missing
methods, ...) please use the usual bug submission rules for the [[PTS]].

Eventually, the URL for the stable PTS SOAP API will be
`http://packages.qa.debian.org/cgi-bin/soap.cgi`.

== Code ==

The API is implemented by a handful of files in the
[[https://salsa.debian.org/qa/pts/blob/master/www/|PTS codebase]]. In
particular
[[https://salsa.debian.org/qa/pts/blob/master/www/cgi-bin/soap-alpha.cgi?view=markup|soap-alpha.cgi]]
is the external layer, each of its method is a method of the SOAP API.

== API Documentation ==

The documentation of the SOAP API can be generated by running
[[http://packages.debian.org/unstable/python-epydoc|epydoc]] on
`soap-alpha.cgi`:
{{{
epydoc soap-alpha.cgi
}}}
then have a look into the `html/` dir.

A version of the HTML doc updated from time to time is available '''on
the web''' at http://people.debian.org/~zack/pts/soap/.

== Examples ==

If you want to test from the command line, you can use the
[[https://salsa.debian.org/qa/pts/blob/master/www/bin/soap_query.py|soap_query.py]]
script shipped with the PTS. The script is self-contained, and does not depend on other parts
of the PTS. Here is a proof of concept:
{{{
zack@usha:/home/srv/debian/pts/www$ bin/soap_query.py latest_version source=ocaml
3.10.2-3
}}}

`soap_query.py --help` will tell you more.

The [[DebbugsSoapInterface]] page contains SOAP client snippets in various languages, they can
be easily adapted for the PTS SOAP interface, by using the URL above, and no `namespace`.