Launchpad API Docs generation¶
The Launchpad API documentation portal is available at https://api.launchpad.net/. It contains summaries of the different web service versions, and links to version-specific documents.
To define our web resources we are using the lazr.restful decorators and capabilities. These decorators are also responsible to generate the related documentation for the exported fields.
We can build API docs using make apidoc
command: this command will
generate the documentation under lib/canonical/launchpad/apidoc
.
Note
Note that we should delete the aforementioned folder in order to generate fresh docs.
$ rm -rf lib/canonical/launchpad/apidoc
$ make apidoc
The command above is responsible for calling the
utilities/create-lp-wadl-and-apidoc.py
script and generating the related
documentation using the lp.services.webservice.wadl
module utilities.
This script will create the related wadl
file and translate it to
HTML
. During this process generate_html
function will be called: this
function is responsible to map wadl
entries to HTML
.
For that we use wadl-to-refhtml.xsl
template. In
this file we can also apply patches to fix not-well generated entry points
for given wadl
entries.
Example¶
For example for the SocialAccount
webservice we used the
@exported_as_webservice_entry("social_account", as_of="beta")
decorator.
Thanks to that the social_account
entry is created.
We can use the aforementioned id to refer this wadl
entry in the wadl-to-refhtml.xsl
file.
Let’s say that we want to change the entry URL
from URL: https://api.launchpad.net/beta/
to URL: https://api.launchpad.net/beta/<person.name>/+socialaccount/<id>
:
we should create an entry inside the find-entry-uri
template inside the
wadl-to-refhtml.xsl
file and we should search for wadl
entry using the
social_account
id. After that we can write xsl
code that will append the
right string to the $base
URL:
<xsl:template name="find-entry-uri">
<xsl:value-of select="$base"/>
<xsl:choose>
<xsl:when test="@id = 'social_account'">
<xsl:text>/</xsl:text>
<var><person.name></var>
<xsl:text>/+socialaccount/</xsl:text>
<var><id></var>
</xsl:when>
</xsl:choose>
</xsl:template>
The resulting URL will be: URL: https://api.launchpad.net/beta/<person.name>/+socialaccount/<id>