Translations API

Our intention is to provide APIs to Launchpad Translations starting with the import queue. From there, we'll follow an "oil slick" approach: from the translation queue we'll arrive naturally at exposing templates. Next is searching for templates on the one hand, and for translations of a template on the other. At that point it will also make sense to expose import queues for individual templates, and to support uploads.

Download requests and individual messages come later, unless we come across high-priority work that requires them.

Applications

Some things we can do with the API:

Some cool things users could do with a Translations API:

Designing an API

If you are working on a feature that involves adding or extending an API, keep that work in a separate branch. Sketch out what the API will look like and organize an API call with your team.

Adding items to an API is very easy to do, and changing APIs is often painful. So worry more about exposing too much than about exposing too little!

The API call will go over each element of the API: is it safe to expose? Is it something we'll end up regretting, or wanting to change? Is it maybe something that would be better exposed in another place altogether?

You may be working on some complex feature that you don't want to hold up for a lengthy design discussion. When in doubt, leave out items that you don't have an immediate use for. If you can still think of a great use, file a bug or blueprint.

Properties

Start by identifying properties that can be exposed. The main risk is exposing information that is meant to be private: private team memberships, private bugs, and so on.

If a property's name is unhelpful or misleading, change it:

Methods

Avoid adding operations that modify anything until you're confident enough with read-only ones.

With read-only operations, the main risk besides exposing private information is overloading a server. When you expose a method, will you allow clients to do something that's much more costly than it is when triggered from a web page?

You may want to expose only part of what a method does, and it may deserve a different name in that form. Or the existing name may simply be wrong. In that case, change it:

Cheat sheet

Documentation in lib/canonical/lazr/doc/webservice-declarations.txt.

Tests are in lib/canonical/launchpad/pagetests/webservice.

Use canonical.launchpad.lazr.interface.copy_field to declare an API parameter with the same definition as an existing schema field.

Open issues

We still have some questions:

Translations/ApiDevelopment (last edited 2008-11-25 16:30:05 by jtv)