API/ImplementingAPIs

Not logged in - Log In / Register

Launchpad Web Service

Prerequisites

Process Overview

For each content interface that a developer would like to expose on the webservice, a Launchpad developer does the the following:

Architectural Principles

Gotchas

Testing

Examples

Changing the status of a bug task

In our internal API, a bugtask status can be changed by using the IBugTask.transitionToStatus() methods. To export this method on the web service, the interface is tagged in the following way:

This allows us to change the bugtask status using the following request:

Assigning a milestone to a bugtask

The IMilestone and IBugTask interfaces are tagged in the following way to export them on the webservice and specify that the milestone field is mutable.

The bug task milestone field can then be modified by using the PATCH request:

Note that multiple attributes could be modified at the same time in the same PATCH request.

Listing the members of a team

Our internal API supports several ways to retrieve members of a team. It offers various attributes retrieving various subset of the members. It also has some methods to query the list of members.

The active members of a team is available in the activemembers attribute. Tagging the IPerson in the following way will allow us to retrieve this list.

We can then retrieve the active members by using the following request:

The members are returned in batches:

Note here that entries contains the complete representation of each member. This is identical to what you would get by retrieving the 'self_link'.

There is also a getMembersByStatus() method that can be used to retrieve members with a particular status.

This is how the method is tagged in the content interface:

This allows us to call the operation using the following request:

Which will give us also a batch result set, but the next batch URLs point back to the method call this time.

Adding a member to the team

A team administrator can add a person to the team by using the addMember() operation. This how to tag the method in the content interface to allow this:

This allows us to add a user to the field by doing the following web request:

Registering a new project

Projects are created using the IProductSet.createProduct() method. Here is how the method should be tagged for export on the web site. This example also demonstrates how to rename exported names on the web service for forward-looking reasons.

A new product can then be created using the following request:

We can see in the response, the main difference between a regular 'write_operation' and a 'factory_operation'. In the latter, instead of replying with the generic 200 response code, the server uses 201 and reports the URL of the newly created project.

Don't repeat yourself

We are also designing an improvement to how we declare parameter types so that we can say "the parameter status has the same type as Membership.status".

Error handling

Errors are reported using regular HTTP status code. So for example, here are the replies that would be returned in the following conditions:

Complete example branch

This merge proposal is for a branch that exports from scratch three new classes IProcessor, IProcessorFamily, and IProcessorFamilySet. None of these classes previously existed in the web UI and none had traversal code.

Some tips and tricks

* to update the lp.dev/+apidoc/index.html and the wadl file you must first manualy delete them

* You can access the API from a web browser in the following ways

API/ImplementingAPIs (last edited 2011-06-23 17:57:25 by bac)