~launchpad-pqm/launchpad/devel : contents of lib/lp/registry/stories/webservice/xx-project-registry.txt at revision 14458.1.1

~launchpad-pqm/launchpad/devel : (revision 14458.1.1)
==========================
Web Service Project Groups
==========================


Project group collection
------------------------

It is possible to get a batched list of all the project groups.

    >>> group_collection = webservice.get("/projectgroups").jsonBody()
    >>> group_collection['resource_type_link']
    u'http://.../#project_groups'

    >>> group_collection['total_size']
    7

    >>> from operator import itemgetter
    >>> project_group_entries = sorted(
    ...     group_collection['entries'], key=itemgetter('name'))
    >>> project_group_entries[0]['self_link']
    u'http://.../apache'

    >>> for project_group in project_group_entries:
    ...   print project_group['display_name']
    Apache
    GNOME
    ...
    The Mozilla Project

It's possible to search the list and get a subset of the project groups.

    >>> group_collection = webservice.named_get(
    ...     "/projectgroups", "search", text="Apache").jsonBody()
    >>> for project_group in group_collection['entries']:
    ...   print project_group['display_name']
    Apache

Searching without providing a search string is the same as getting all
the project groups.

    >>> group_collection = webservice.named_get(
    ...     "/projectgroups", "search").jsonBody()
    >>> project_group_entries = sorted(
    ...     group_collection['entries'], key=itemgetter('name'))
    >>> for project_group in project_group_entries:
    ...   print project_group['display_name']
    Apache
    GNOME
    ...
    The Mozilla Project


Project group entry
-------------------

Project groups are available at their canonical URL on the API virtual
host.

    >>> from lazr.restful.testing.webservice import pprint_entry

    >>> mozilla = webservice.get('/mozilla').jsonBody()
    >>> pprint_entry(mozilla)
    active: True
    active_milestones_collection_link: u'http://.../mozilla/active_milestones'
    all_milestones_collection_link: u'http://.../mozilla/all_milestones'
    bug_reported_acknowledgement: None
    bug_reporting_guidelines: None
    bug_tracker_link: None
    date_created: u'...'
    description: u'The Mozilla Project...'
    display_name: u'The Mozilla Project'
    driver_link: None
    freshmeat_project: None
    homepage_content: None
    homepage_url: u'http://www.mozilla.org/'
    icon_link: u'http://.../mozilla/icon'
    logo_link: u'http://.../mozilla/logo'
    mugshot_link: u'http://.../mozilla/mugshot'
    name: u'mozilla'
    official_bug_tags: []
    owner_link: u'http://.../~name12'
    projects_collection_link: u'http://.../mozilla/projects'
    registrant_link: u'http://.../~name12'
    resource_type_link: u'...'
    reviewed: False
    self_link: u'http://.../mozilla'
    sourceforge_project: None
    summary: u'The Mozilla Project...'
    title: u'The Mozilla Project'
    web_link: u'http://launchpad.../mozilla'
    wiki_url: None

The milestones can be accessed through the
active_milestones_collection_link and the
all_milestones_collection_link.

    >>> response = webservice.get(
    ...     mozilla['active_milestones_collection_link'])
    >>> active_milestones = response.jsonBody()
    >>> print_self_link_of_entries(active_milestones)
    http://.../mozilla/+milestone/1.0

    >>> response = webservice.get(mozilla['all_milestones_collection_link'])
    >>> all_milestones = response.jsonBody()
    >>> print_self_link_of_entries(all_milestones)
    http://.../mozilla/+milestone/0.8
    http://.../mozilla/+milestone/0.9
    http://.../mozilla/+milestone/0.9.1
    http://.../mozilla/+milestone/0.9.2
    http://.../mozilla/+milestone/1.0.0

The milestones can also be accessed anonymously.

    >>> response = anon_webservice.get(
    ...     mozilla['active_milestones_collection_link'])
    >>> active_milestones = response.jsonBody()
    >>> print_self_link_of_entries(active_milestones)
    http://.../mozilla/+milestone/1.0

    >>> response = anon_webservice.get(
    ...     mozilla['all_milestones_collection_link'])
    >>> all_milestones = response.jsonBody()
    >>> print_self_link_of_entries(all_milestones)
    http://.../mozilla/+milestone/0.8
    http://.../mozilla/+milestone/0.9
    http://.../mozilla/+milestone/0.9.1
    http://.../mozilla/+milestone/0.9.2
    http://.../mozilla/+milestone/1.0.0

"getMilestone" returns a milestone for the given name, or None if there
is no milestone for the given name.

    >>> milestone_1_0 = webservice.named_get(
    ...     mozilla['self_link'], "getMilestone", name="1.0").jsonBody()
    >>> print milestone_1_0['self_link']
    http://.../mozilla/+milestone/1.0

    >>> print webservice.named_get(
    ...     mozilla['self_link'], "getMilestone", name="fnord").jsonBody()
    None


Project entry
-------------

Projects are available at their canonical URL on the API virtual host.

    >>> firefox = webservice.get('/firefox').jsonBody()
    >>> pprint_entry(firefox)
    active: True
    active_milestones_collection_link: u'http://.../firefox/active_milestones'
    all_milestones_collection_link: u'http://.../firefox/all_milestones'
    brand_link: u'http://.../firefox/brand'
    bug_reported_acknowledgement: None
    bug_reporting_guidelines: None
    bug_supervisor_link: None
    bug_tracker_link: None
    commercial_subscription_is_due: True
    commercial_subscription_link: None
    date_created: u'2004-09-24T20:58:02.185708+00:00'
    date_next_suggest_packaging: None
    description: u'The Mozilla Firefox web browser'
    development_focus_link: u'http://.../firefox/trunk'
    display_name: u'Mozilla Firefox'
    download_url: None
    driver_link: None
    freshmeat_project: None
    homepage_url: None
    icon_link: u'http://.../firefox/icon'
    is_permitted: False
    license_approved: False
    license_info: None
    licenses: []
    logo_link: u'http://.../firefox/logo'
    name: u'firefox'
    official_bug_tags: []
    owner_link: u'http://.../~name12'
    programming_language: None
    project_group_link: u'http://.../mozilla'
    project_reviewed: False
    qualifies_for_free_hosting: False
    recipes_collection_link: u'http://.../firefox/recipes'
    registrant_link: u'http://.../~name12'
    releases_collection_link: u'http://.../firefox/releases'
    remote_product: None
    resource_type_link: u'http://.../#project'
    reviewer_whiteboard: None
    screenshots_url: None
    security_contact_link: None
    self_link: u'http://.../firefox'
    series_collection_link: u'http://.../firefox/series'
    sourceforge_project: None
    summary: u'The Mozilla Firefox web browser'
    title: u'Mozilla Firefox'
    translation_focus_link: None
    web_link: u'http://launchpad.../firefox'
    wiki_url: None

In Launchpad project names may not have uppercase letters in their
name.  As a convenience, requests for projects using the wrong case
are redirected to the correct location.

    >>> print webservice.get('/FireFox')
    HTTP/1.1 301 Moved Permanently
    ...
    Location: http://api.launchpad.dev/beta/firefox
    ...

Some entries for projects are only available to admins.  Here we see
several that are not available to non-privileged users marked as
'redacted'.

    >>> firefox = user_webservice.get('/firefox').jsonBody()
    >>> pprint_entry(firefox)
    active: True
    active_milestones_collection_link: u'http://.../firefox/active_milestones'
    all_milestones_collection_link: u'http://.../firefox/all_milestones'
    brand_link: u'http://.../firefox/brand'
    bug_reported_acknowledgement: None
    bug_reporting_guidelines: None
    bug_supervisor_link: None
    bug_tracker_link: None
    commercial_subscription_is_due: True
    commercial_subscription_link: None
    date_created: u'2004-09-24T20:58:02.185708+00:00'
    date_next_suggest_packaging: None
    description: u'The Mozilla Firefox web browser'
    development_focus_link: u'http://.../firefox/trunk'
    display_name: u'Mozilla Firefox'
    download_url: None
    driver_link: None
    freshmeat_project: None
    homepage_url: None
    icon_link: u'http://.../firefox/icon'
    is_permitted:...redacted...
    license_approved:...redacted...
    license_info: None
    licenses: []
    logo_link: u'http://.../firefox/logo'
    name: u'firefox'
    official_bug_tags: []
    owner_link: u'http://.../~name12'
    programming_language: None
    project_group_link: u'http://.../mozilla'
    project_reviewed:...redacted...
    qualifies_for_free_hosting: False
    recipes_collection_link: u'http://.../firefox/recipes'
    registrant_link: u'http://.../~name12'
    releases_collection_link: u'http://.../firefox/releases'
    remote_product: None
    resource_type_link: u'http://.../#project'
    reviewer_whiteboard:...redacted...
    screenshots_url: None
    security_contact_link: None
    self_link: u'http://.../firefox'
    series_collection_link: u'http://.../firefox/series'
    sourceforge_project: None
    summary: u'The Mozilla Firefox web browser'
    title: u'Mozilla Firefox'
    translation_focus_link: None
    web_link: u'http://launchpad.../firefox'
    wiki_url: None

The milestones can be accessed through the
active_milestones_collection_link and the
all_milestones_collection_link.

    >>> response = webservice.get(
    ...     firefox['active_milestones_collection_link'])
    >>> active_milestones = response.jsonBody()
    >>> print_self_link_of_entries(active_milestones)
    http://.../firefox/+milestone/1.0

    >>> response = webservice.get(firefox['all_milestones_collection_link'])
    >>> all_milestones = response.jsonBody()
    >>> print_self_link_of_entries(all_milestones)
    http://.../firefox/+milestone/0.9
    http://.../firefox/+milestone/0.9.1
    http://.../firefox/+milestone/0.9.2
    http://.../firefox/+milestone/1.0
    http://.../firefox/+milestone/1.0.0

"getMilestone" returns a milestone for the given name, or None if there
is no milestone for the given name.

    >>> milestone_1_0 = webservice.named_get(
    ...     firefox['self_link'], "getMilestone", name="1.0").jsonBody()
    >>> print milestone_1_0['self_link']
    http://.../firefox/+milestone/1.0

    >>> print webservice.named_get(
    ...     firefox['self_link'], "getMilestone", name="fnord").jsonBody()
    None

The project group can be accessed through the project_group_link.

    >>> webservice.get(firefox['project_group_link']).jsonBody()['self_link']
    u'http://.../mozilla'

A list of series can be accessed through the series_collection_link.

    >>> response = webservice.get(firefox['series_collection_link'])
    >>> series = response.jsonBody()
    >>> print series['total_size']
    2

    >>> print_self_link_of_entries(series)
    http://.../firefox/1.0
    http://.../firefox/trunk

"getSeries" returns the series for the given name.

    >>> series_1_0 = webservice.named_get(
    ...     firefox['self_link'], "getSeries", name="1.0").jsonBody()
    >>> print series_1_0['self_link']
    http://.../firefox/1.0

Series can also be accessed anonymously.

    >>> response = anon_webservice.get(firefox['series_collection_link'])
    >>> series = response.jsonBody()
    >>> print series['total_size']
    2

"newSeries" permits the creation of new series.

    >>> experimental_new_series = webservice.named_post(
    ...     firefox['self_link'], "newSeries", name="experimental",
    ...     summary="An experimental new series.")
    >>> print experimental_new_series
    HTTP/1.1 201 Created
    ...
    Location: http://.../firefox/experimental
    ...

A list of releases can be accessed through the releases_collection_link.

    >>> response = webservice.get(firefox['releases_collection_link'])
    >>> releases = response.jsonBody()
    >>> print releases['total_size']
    4

    >>> print_self_link_of_entries(releases)
    http://.../firefox/1.0/1.0.0
    http://.../firefox/trunk/0.9
    http://.../firefox/trunk/0.9.1
    http://.../firefox/trunk/0.9.2

"getRelease" returns the release for the given version.

    >>> release_0_9_1 = webservice.named_get(
    ...     firefox['self_link'], "getRelease", version="0.9.1").jsonBody()
    >>> print release_0_9_1['self_link']
    http://.../firefox/trunk/0.9.1

Releases can also be accessed anonymously.

    >>> response = anon_webservice.get(firefox['releases_collection_link'])
    >>> releases = response.jsonBody()
    >>> print releases['total_size']
    4

The development focus series can be accessed through the
development_focus_link.

    >>> response = webservice.get(firefox['development_focus_link'])
    >>> response.jsonBody()['self_link']
    u'http://.../firefox/trunk'

Attributes can be edited via the webservice.patch() method.

    >>> from simplejson import dumps
    >>> patch = {
    ...     u'driver_link': webservice.getAbsoluteUrl('/~mark'),
    ...     u'homepage_url': u'http://sf.net/firefox',
    ...     u'licenses': [u'Python License', u'GNU GPL v2'],
    ...     u'bug_tracker_link':
    ...         webservice.getAbsoluteUrl('/bugs/bugtrackers/mozilla.org'),
    ...     }
    >>> print webservice.patch(
    ...     '/firefox', 'application/json', dumps(patch))
    HTTP/1.1 209 Content Returned
    ...

    >>> firefox = webservice.get('/firefox').jsonBody()
    >>> firefox['driver_link']
    u'http://.../~mark'

    >>> firefox['homepage_url']
    u'http://sf.net/firefox'

    >>> webservice.get(firefox['driver_link']).jsonBody()['self_link']
    u'http://.../~mark'

    >>> webservice.get(firefox['owner_link']).jsonBody()['self_link']
    u'http://.../~name12'

    >>> webservice.get(firefox['bug_tracker_link']).jsonBody()['self_link']
    u'http://.../bugs/bugtrackers/mozilla.org'

When the owner_link is changed the ownership of some attributes is
changed as well.

    >>> # Create a product with a series and release.
    >>> login('test@canonical.com')
    >>> test_project_owner = factory.makePerson(name='test-project-owner')
    >>> test_project = factory.makeProduct(
    ...     name='test-project', owner=test_project_owner)
    >>> test_series = factory.makeProductSeries(
    ...     product=test_project, name='test-series',
    ...     owner=test_project_owner)
    >>> test_milestone = factory.makeMilestone(
    ...     product=test_project, name='test-milestone',
    ...     productseries=test_series)
    >>> test_project_release = factory.makeProductRelease(
    ...     product=test_project, milestone=test_milestone)
    >>> logout()

    >>> test_project = webservice.get('/test-project').jsonBody()
    >>> test_project['owner_link']
    u'http://.../~test-project-owner'

    >>> patch = {
    ...     u'owner_link': webservice.getAbsoluteUrl('/~mark'),
    ...     }
    >>> print webservice.patch(
    ...     '/test-project', 'application/json', dumps(patch))
    HTTP/1.1 209 Content Returned
    ...

    >>> test_project = webservice.get('/test-project').jsonBody()
    >>> test_project['owner_link']
    u'http://.../~mark'

Read-only attributes, like registrant, cannot be modified via the
webservice.patch() method.

    >>> patch = {
    ...     u'registrant_link': webservice.getAbsoluteUrl('/~mark'),
    ...     }
    >>> print webservice.patch(
    ...     '/firefox', 'application/json', dumps(patch))
    HTTP/1.1 400 Bad Request
    ...
    registrant_link: You tried to modify a read-only attribute.

    >>> firefox = webservice.get('/firefox').jsonBody()
    >>> firefox['registrant_link']
    u'http://.../~name12'

Similarly the date_created attribute cannot be modified.

    >>> original_date_created = firefox['date_created']
    >>> patch = {
    ...     u'date_created': u'2000-01-01T01:01:01+00:00Z'
    ...     }
    >>> print webservice.patch(
    ...     '/firefox', 'application/json', dumps(patch))
    HTTP/1.1 400 Bad Request
    ...
    date_created: You tried to modify a read-only attribute.

    >>> firefox = webservice.get('/firefox').jsonBody()
    >>> firefox['date_created'] == original_date_created
    True

"get_timeline" returns a lightweight representation of the project's
hierarchy of series, milestones, and releases.

    >>> patch = {'status': 'Obsolete'}
    >>> print webservice.patch(
    ...     '/firefox/trunk', 'application/json', dumps(patch))
    HTTP/1.1 209 Content Returned...
    >>> timeline = webservice.named_get(
    ...     firefox['self_link'],
    ...     "get_timeline",
    ...     include_inactive=True).jsonBody()
    >>> print pretty(timeline)
    {u'entries': [{u'http_etag': ...
                   u'is_development_focus': True,
                   u'landmarks': [{u'code_name': None,
                                   u'date': u'2056-10-16',
                                   u'name': u'1.0',
                                   u'type': u'milestone',
                                   u'uri': u'/firefox/+milestone/1.0'},
                                  {u'code_name': u'One (secure) Tree Hill',
                                   u'date': u'2004-10-15',
                                   u'name': u'0.9.2',
                                   u'type': u'release',
                                   u'uri': u'/firefox/trunk/0.9.2'},
                                  {u'code_name': u'One Tree Hill (v2)',
                                   u'date': u'2004-10-15',
                                   u'name': u'0.9.1',
                                   u'type': u'release',
                                   u'uri': u'/firefox/trunk/0.9.1'},
                                  {u'code_name': u'One Tree Hill',
                                   u'date': u'2004-10-15',
                                   u'name': u'0.9',
                                   u'type': u'release',
                                   u'uri': u'/firefox/trunk/0.9'}],
                   u'name': u'trunk',
                   u'project_link': u'http://.../firefox',
                   u'resource_type_link': u'.../#timeline_project_series',
                   u'self_link': u'http://.../firefox/trunk',
                   u'status': u'Obsolete',
                   u'uri': u'/firefox/trunk',
                   u'web_link': u'http://launchpad.../firefox/trunk'},
                  {u'http_etag': ...
                   u'is_development_focus': False,
                   u'landmarks': [{u'code_name': u'First Stable Release',
                                   u'date': u'2004-06-28',
                                   u'name': u'1.0.0',
                                   u'type': u'release',
                                   u'uri': u'/firefox/1.0/1.0.0'}],
                   u'name': u'1.0',
                   u'project_link': u'http://.../firefox',
                   u'resource_type_link': u'.../#timeline_project_series',
                   u'self_link': u'http://.../firefox/1.0',
                   u'status': u'Active Development',
                   u'uri': u'/firefox/1.0',
                   u'web_link': u'http://launchpad.../firefox/1.0'},
                  {u'http_etag': ...
                   u'is_development_focus': False,
                   u'landmarks': [],
                   u'name': u'experimental',
                   u'project_link': u'http://.../firefox',
                   u'resource_type_link': u'.../#timeline_project_series',
                   u'self_link': u'http://.../firefox/experimental',
                   u'status': u'Active Development',
                   u'uri': u'/firefox/experimental',
                   u'web_link': u'http://launchpad.../firefox/experimental'}],
     u'start': 0,
     u'total_size': 3}


Project collection
------------------

It is possible to get a batched list of all the projects.

    >>> project_collection = webservice.get("/projects").jsonBody()
    >>> project_collection['resource_type_link']
    u'http://.../#projects'

The entire collection has 24 entries.

    >>> project_collection['total_size']
    24

But the batch has only 5.  (The batch size is 5 for testing but larger
in production.)

    >>> project_entries = project_collection['entries']
    >>> len(project_entries)
    5

The batch size can be changed through the ws.size argument.

    >>> project_collection = webservice.get("/projects?ws.size=75").jsonBody()

    >>> project_entries = sorted(
    ...     project_collection['entries'],
    ...     key=itemgetter('display_name', 'name'))
    >>> len(project_entries)
    24

    >>> project_entries[0]['self_link']
    u'http://.../aptoncd'

    >>> for project in project_entries[:5]:
    ...   print "%s (%s)" % (project['display_name'], project['name'])
    APTonCD (aptoncd)
    Arch mirrors (arch-mirrors)
    Bazaar (bazaar)
    Bazaar (bzr)
    Derby (derby)

It's possible to search the list and get a subset of the project groups.

    >>> project_collection = webservice.named_get(
    ...     "/projects", "search", text="Apache").jsonBody()
    >>> projects = [
    ...     project['display_name']
    ...     for project in project_collection['entries']]
    >>> for project_name in sorted(projects):
    ...     print project_name
    Derby
    Tomcat

If you don't specify "text" to the search a batched list of all the
projects is returned.

    >>> project_collection = webservice.named_get(
    ...     "/projects", "search").jsonBody()
    >>> len(project_collection['entries'])
    5

It is also possible to search for projects by a text string by adding
the ws.op=search parameter.

    >>> project_collection = webservice.get(
    ...   "/projects?ws.op=search&text=gnome").jsonBody()
    >>> project_collection['total_size']
    4

The latest projects registered can be retrieved.

    >>> latest = webservice.named_get(
    ...     "/projects", "latest").jsonBody()
    >>> entries = sorted(
    ...    latest['entries'], key=itemgetter('display_name'))
    >>> for project in entries:
    ...     print project['display_name']
    Derby
    Mega Money Maker
    Obsolete Junk
    Redfish
    Test-project

There is a method for doing a query about attributes related to project
licensing.  We can find all projects with unreviewed licenses.

    >>> unreviewed = webservice.named_get(
    ...     "/projects", "licensing_search",
    ...     project_reviewed=False).jsonBody()

    >>> entries = sorted(
    ...    unreviewed['entries'], key=itemgetter('display_name'))
    >>> for project in entries:
    ...     print project['display_name']
    Arch mirrors
    ...

Or those that are reviewed.

    >>> reviewed = webservice.named_get(
    ...     "/projects", "licensing_search",
    ...     project_reviewed=True).jsonBody()

    >>> entries = sorted(
    ...    reviewed['entries'], key=itemgetter('display_name'))
    >>> for project in entries:
    ...     print project['display_name']
    Obsolete Junk
    alsa-utils
    python gnome2 dev
    unassigned syncs

We can also find all projects with no licensing information.

    >>> no_licenses = webservice.named_get(
    ...     "/projects", "licensing_search",
    ...     has_zero_license=True).jsonBody()

    >>> entries = sorted(
    ...    no_licenses['entries'], key=itemgetter('display_name'))
    >>> for project in entries:
    ...     print project['display_name']
    Arch mirrors
    ...

We can find projects based on creation date.

    >>> old = webservice.named_get(
    ...     "/projects", "licensing_search",
    ...     created_before="2006-01-01").jsonBody()

    >>> entries = sorted(
    ...    old['entries'], key=itemgetter('display_name'))
    >>> for project in entries:
    ...     print project['display_name']
    Arch mirrors
    ...

Similarly we can find new projects.

    >>> new = webservice.named_get(
    ...     "/projects", "licensing_search",
    ...     created_after="2006-01-01").jsonBody()

    >>> entries = sorted(
    ...    new['entries'], key=itemgetter('display_name'))
    >>> for project in entries:
    ...     print project['display_name']
    APTonCD
    ...

All of the projects of a given license can be found.

    >>> proprietary = webservice.named_get(
    ...     "/projects", "licensing_search",
    ...     licenses=["Other/Proprietary"]).jsonBody()

    >>> entries = sorted(
    ...    proprietary['entries'], key=itemgetter('display_name'))
    >>> for project in entries:
    ...     print project['display_name']
    Mega Money Maker

The use of "licensing_search" is restricted to commercial admins.
Attempting to access it as a normal users is unauthorized.

    >>> print user_webservice.named_get(
    ...     "/projects", "licensing_search",
    ...     licenses=["Other/Proprietary"])
    HTTP/1.1 401 Unauthorized
    ...
    (<...>, 'forReview', 'launchpad.Moderate')

The project collection has a method for creating a new project.

    >>> def create_project(name, display_name, title, summary,
    ...                    description=None, project=None, homepage_url=None,
    ...                    screenshots_url=None, wiki_url=None,
    ...                    download_url=None, freshmeat_project=None,
    ...                    sourceforge_project=None, programming_lang=None,
    ...                    licenses=(), license_info=None,
    ...                    project_reviewed=False,
    ...                    registrant=None):
    ...     return webservice.named_post(
    ...         "/projects", "new_project",
    ...         name=name, display_name=display_name,
    ...         title=title, summary=summary, description=description,
    ...         homepage_url=homepage_url, screenshots_url=screenshots_url,
    ...         wiki_url=wiki_url, download_url=download_url,
    ...         freshmeat_project=freshmeat_project,
    ...         sourceforge_project=sourceforge_project,
    ...         programming_lang=programming_lang,
    ...         licenses=licenses, license_info=license_info,
    ...         project_reviewed=project_reviewed,
    ...         registrant=registrant)

Verify a project does not exist and then create it.

    >>> print webservice.get('/my-new-project')
    HTTP/1.1 404 Not Found
    ...

    >>> print create_project('my-new-project', 'My New Project',
    ...     'My New Project', 'My Shiny New Project',
    ...     licenses=["Zope Public License", "GNU GPL v2"],
    ...     wiki_url="http://example.com/shiny")
    HTTP/1.1 201 Created
    ...
    Location: http://.../my-new-project
    ...

    >>> print webservice.get('/my-new-project')
    HTTP/1.1 200 Ok
    ...

    >>> new_project = webservice.get('/my-new-project').jsonBody()
    >>> print new_project['name']
    my-new-project

    >>> print new_project['display_name']
    My New Project

    >>> print new_project['summary']
    My Shiny New Project

    >>> print sorted(new_project['licenses'])
    [u'GNU GPL v2', u'Zope Public License']

    >>> print new_project['project_reviewed']
    False

    >>> print new_project['homepage_url']
    None

Attempting to create a project with a name that has already been used is
an error.

    >>> print create_project('my-new-project', 'My New Project',
    ...     'My New Project', 'My Shiny New Project')
    HTTP/1.1 400 Bad Request
    ...
    name: my-new-project is already used by another project

If the fields do not validate a Bad Request error is received.  Here the
URL is not properly formed.

    >>> print create_project('my-new-project', 'My New Project',
    ...     'My New Project', 'My Shiny New Project',
    ...     wiki_url="htp://badurl.example.com")
    HTTP/1.1 400 Bad Request
    ...
    wiki_url: The URI scheme "htp" is not allowed.  Only URIs with the
    following schemes may be used: ftp, http, https
    ...


The pillar set
--------------

A few features are common to projects, project groups, and
distributions. We call all three "pillars", and publish the common
functionality at an object called the pillar set.

    >>> pillar_set = webservice.get("/pillars").jsonBody()
    >>> pprint_entry(pillar_set)
    featured_pillars_collection_link: u'http://.../pillars/featured_pillars'
    resource_type_link: u'...'
    self_link: u'...'

The featured pillars are available as a separate collection. Because
they're of different resource types, the best way to compare them is by
comparing the self_link, which every resource has.

    >>> featured_link = pillar_set['featured_pillars_collection_link']
    >>> featured_pillars = webservice.get(featured_link).jsonBody()
    >>> featured_pillars['total_size']
    9

    >>> featured_entries = sorted(
    ...     featured_pillars['entries'], key=itemgetter('self_link'))
    >>> for pillar in featured_entries:
    ...     print pillar['self_link']
    http://.../applets
    http://.../bazaar
    ...
    http://.../gnome

    >>> search_result = webservice.named_get(
    ...     "/pillars", "search", text="bazaar").jsonBody()
    >>> found_entries = sorted(search_result['entries'],
    ...     key=itemgetter('self_link'))
    >>> for pillar in found_entries:
    ...     print pillar['self_link']
    http://.../bazaar
    http://.../bzr
    http://.../launchpad

    >>> search_result = webservice.named_get(
    ...     "/pillars", "search", text="bazaar", limit="1").jsonBody()
    >>> for pillar in search_result['entries']:
    ...     print pillar['self_link']
    http://.../bazaar


Project series entry
--------------------

The entry for a project series is available at its canonical URL on the
virtual host.

    >>> from zope.security.proxy import removeSecurityProxy
    >>> login('test@canonical.com')
    >>> babadoo_owner = factory.makePerson(name='babadoo-owner')
    >>> babadoo = factory.makeProduct(name='babadoo', owner=babadoo_owner)
    >>> foobadoo = factory.makeProductSeries(
    ...     product=babadoo, name='foobadoo', owner=babadoo_owner)
    >>> removeSecurityProxy(foobadoo).summary = (
    ...     u'Foobadoo support for Babadoo')
    >>> fooey = factory.makeAnyBranch(
    ...     product=babadoo, name='fooey', owner=babadoo_owner)
    >>> removeSecurityProxy(foobadoo).branch = fooey
    >>> logout()

    >>> babadoo_foobadoo = webservice.get('/babadoo/foobadoo').jsonBody()
    >>> pprint_entry(babadoo_foobadoo)
    active: True
    active_milestones_collection_link:
            u'http://.../babadoo/foobadoo/active_milestones'
    all_milestones_collection_link:
            u'http://.../babadoo/foobadoo/all_milestones'
    branch_link: u'http://.../~babadoo-owner/babadoo/fooey'
    bug_reported_acknowledgement: None
    bug_reporting_guidelines: None
    date_created: u'...'
    display_name: u'foobadoo'
    driver_link: None
    drivers_collection_link: u'http://.../babadoo/foobadoo/drivers'
    name: u'foobadoo'
    official_bug_tags: []
    owner_link: u'http://.../~babadoo-owner'
    project_link: u'http://.../babadoo'
    release_finder_url_pattern: None
    releases_collection_link: u'http://.../babadoo/foobadoo/releases'
    resource_type_link: u'...'
    self_link: u'http://.../babadoo/foobadoo'
    status: u'Active Development'
    summary: u'Foobadoo support for Babadoo'
    title: u'Babadoo foobadoo series'
    web_link: u'http://launchpad.../babadoo/foobadoo'

"get_timeline" returns a lightweight representation of the series'
milestones and releases.

    >>> timeline = webservice.named_get(
    ...     babadoo_foobadoo['self_link'], "get_timeline").jsonBody()
    >>> print pretty(timeline)
    {u'http_etag': ...
     u'is_development_focus': False,
     u'landmarks': [],
     u'name': u'foobadoo',
     u'project_link': u'http://.../babadoo',
     u'resource_type_link': u'http://.../#timeline_project_series',
     u'self_link': u'http://.../babadoo/foobadoo',
     u'status': u'Active Development',
     u'uri': u'/babadoo/foobadoo',
     u'web_link': u'http://launchpad.../babadoo/foobadoo'}


Creating a milestone on the product series
==========================================

The newMilstone method is called by sending "ws.op=newMilestone" as a
request variable along with the parameters. The webservice.named_post()
method simplifies this for us.

    >>> firefox_1_0 = webservice.get('/firefox/1.0').jsonBody()
    >>> response = webservice.named_post(
    ...     firefox_1_0['self_link'], 'newMilestone', {},
    ...     name='alpha1', code_name='Elmer', date_targeted=u'2005-06-06',
    ...     summary='Feature complete but buggy.')
    >>> print response
    HTTP/1.1 201 Created
    ...
    Location: http://.../firefox/+milestone/alpha1
    ...

    >>> milestone = webservice.get(response.getHeader('Location')).jsonBody()
    >>> print milestone['name']
    alpha1

    >>> print milestone['code_name']
    Elmer

    >>> print milestone['date_targeted']
    2005-06-06T00:00:00

    >>> print milestone['summary']
    Feature complete but buggy.

The milestone name must be unique on the product series.

    >>> print webservice.named_post(
    ...     firefox_1_0['self_link'], 'newMilestone', {},
    ...     name='alpha1', dateexpected='157.0',
    ...     summary='Feature complete but buggy.')
    HTTP/1.1 400 Bad Request
    ...
    name: The name alpha1 is already used by a milestone in Mozilla Firefox.

The milestone name can only contain letters, numbers, "-", "+", and ".".

    >>> print webservice.named_post(
    ...     firefox_1_0['self_link'], 'newMilestone', {},
    ...     name='!@#$%^&*()', dateexpected='157.0',
    ...     summary='Feature complete but buggy.')
    HTTP/1.1 400 Bad Request
    ...
    Invalid name...

Invalid data will return a Bad Request error.

    >>> response = webservice.named_post(
    ...     firefox_1_0['self_link'], 'newMilestone', {},
    ...     name='buggy', date_targeted=u'2005-10-36',
    ...     code_name='Samurai Monkey',
    ...     summary='Very buggy.')
    >>> print response
    HTTP/1.1 400 Bad Request
    ...
    date_targeted: Value doesn't look like a date.


Project release
===============

Project releases are available at their canonical URL on the API virtual
host.

    >>> firefox_1_0_0 = webservice.get('/firefox/1.0/1.0.0').jsonBody()
    >>> pprint_entry(firefox_1_0_0)
    changelog: u''
    date_created: u'2005-06-06T08:59:51.930201+00:00'
    date_released: u'2004-06-28T00:00:00+00:00'
    display_name: u'Mozilla Firefox 1.0.0'
    files_collection_link: u'http://.../firefox/1.0/1.0.0/files'
    milestone_link: u'http://.../firefox/+milestone/1.0.0'
    owner_link: u'http://.../~name12'
    project_link: u'http://.../firefox'
    release_notes: u'...'
    resource_type_link: u'...'
    self_link: u'http://.../firefox/1.0/1.0.0'
    title: u'Mozilla Firefox 1.0.0 "First Stable Release"'
    version: u'1.0.0'
    web_link: u'http://launchpad.../firefox/1.0/1.0.0'

The createProductRelease method is called by sending
"ws.op=createProductRelease" as a request variable along with the
parameters.  The webservice.named_post() method simplifies this for us.

    >>> response = webservice.named_post(
    ...     milestone['self_link'], 'createProductRelease', {},
    ...     date_released='2000-01-01T01:01:01+00:00Z',
    ...     release_notes='New stuff', changelog='Added 5,000 features.')
    >>> print response
    HTTP/1.1 201 Created
    ...
    Location: http://.../firefox/1.0/alpha1
    ...

    >>> release = webservice.get(response.getHeader('Location')).jsonBody()
    >>> print release['version']
    alpha1

    >>> print release['release_notes']
    New stuff

    >>> print release['changelog']
    Added 5,000 features.

Only one product release can be created per milestone.

    >>> response = webservice.named_post(
    ...     milestone['self_link'], 'createProductRelease', {},
    ...     date_released='2000-01-01T01:01:01+00:00Z',
    ...     changelog='Added 5,000 features.')
    >>> print response
    HTTP/1.1 400 Bad Request
    ...
    A milestone can only have one ProductRelease.


Project release entries
-----------------------

    >>> releases = webservice.get(
    ...     '/firefox/1.0/releases').jsonBody()
    >>> print_self_link_of_entries(releases)
    http://.../firefox/1.0/1.0.0
    http://.../firefox/1.0/alpha1


Project release file collection
-------------------------------

    >>> pr_files = webservice.get(
    ...     '/firefox/trunk/0.9.2/files').jsonBody()
    >>> print_self_link_of_entries(pr_files)
    http://.../firefox/trunk/0.9.2/+file/firefox_0.9.2.orig.tar.gz


Milestone entry
---------------

The entry for a milestone is available at its canonical URL on the API
virtual host.

    >>> firefox_milestone_1_0 = webservice.get(
    ...     '/firefox/+milestone/1.0').jsonBody()
    >>> pprint_entry(firefox_milestone_1_0)
    code_name: None
    date_targeted: u'2056-10-16T18:31:44.293448'
    is_active: True
    name: u'1.0'
    official_bug_tags: []
    release_link: None
    resource_type_link: u'...'
    self_link: u'http://.../firefox/+milestone/1.0'
    series_target_link: u'http://.../firefox/trunk'
    summary: None
    target_link: u'http://.../firefox'
    title: u'Mozilla Firefox 1.0'
    web_link: u'http://launchpad.../firefox/+milestone/1.0'

The milestone entry has a link to its release if it has one.

    >>> milestone = webservice.get('/firefox/+milestone/1.0.0').jsonBody()
    >>> print milestone['release_link']
    http://.../firefox/1.0/1.0.0


Project release entries
-----------------------

    >>> releases = webservice.get(
    ...     '/firefox/1.0/releases').jsonBody()
    >>> print_self_link_of_entries(releases)
    http://.../firefox/1.0/1.0.0
    http://.../firefox/1.0/alpha1

They can be deleted with the 'delete' operation.

    >>> results = webservice.named_post('/firefox/1.0/alpha1', 'delete')
    >>> print results
    HTTP/1.1 200 Ok
    ...


Project release file entry
--------------------------

Project release files are available at their canonical URL on the API
virtual host.

    >>> url = '/firefox/trunk/0.9.2/+file/firefox_0.9.2.orig.tar.gz'
    >>> result = webservice.get(url).jsonBody()
    >>> pprint_entry(result)
    date_uploaded: u'2005-06-06T08:59:51.926792+00:00'
    description: None
    file_link:
        u'http://.../firefox/trunk/0.9.2/+file/firefox_0.9.2.orig.tar.gz/file'
    file_type: u'Code Release Tarball'
    project_release_link: u'http://.../firefox/trunk/0.9.2'
    resource_type_link: u'http://.../#project_release_file'
    self_link:
        u'http://.../firefox/trunk/0.9.2/+file/firefox_0.9.2.orig.tar.gz'
    signature_link:
        u'http://.../trunk/0.9.2/+file/firefox_0.9.2.orig.tar.gz/signature'

The actual file redirects to the librarian when accessed.

    >>> url = '/firefox/trunk/0.9.2/+file/firefox_0.9.2.orig.tar.gz/file'
    >>> result = webservice.get(url)
    >>> print result
    HTTP/1.1 303 See Other
    ...
    Location: http://.../firefox_0.9.2.orig.tar.gz
    ...

The signature file will redirect too, if found.  In this case there is
no signature so we get a 404.

    >>> url = '/firefox/trunk/0.9.2/+file/firefox_0.9.2.orig.tar.gz/signature'
    >>> result = webservice.get(url)
    >>> print result
    HTTP/1.1 404 Not Found
    ...

The file and signature on a Project Release File are 'readonly'. Trying
to put new content will result in a ForbiddenAttribute error.

    >>> url = '/firefox/trunk/0.9.2/+file/firefox_0.9.2.orig.tar.gz/file'
    >>> response = webservice.put(url, 'application/x-tar-gz', 'fakefiledata')
    >>> print response
    HTTP/1.1 405 Method Not Allowed...
    Allow: GET
    ...

    >>> url = '/firefox/trunk/0.9.2/+file/firefox_0.9.2.orig.tar.gz/signature'
    >>> response = webservice.put(url, 'pgpapplication/data', 'signaturedata')
    >>> print response
    HTTP/1.1 405 Method Not Allowed...
    Allow: GET
    ...


Project release files
---------------------

Project release files can be added to a project release using the API
'add_file' method.

    >>> files_url = '/firefox/1.0/1.0.0/files'
    >>> ff_100_files = webservice.get(files_url).jsonBody()
    >>> print_self_link_of_entries(ff_100_files)

    >>> pr_url = '/firefox/1.0/1.0.0'
    >>> ff_100 = webservice.get(pr_url).jsonBody()
    >>> file_content="first attachment file content"
    >>> sig_file_content="hash hash hash"
    >>> response = webservice.named_post(ff_100['self_link'], 'add_file',
    ...     filename='filename.txt',
    ...     file_content=file_content,
    ...     content_type='plain/txt',
    ...     signature_filename='filename.txt.md5',
    ...     signature_content=sig_file_content,
    ...     file_type='README File',
    ...     description="test file")
    >>> print response
    HTTP/1.1 201 Created
    ...
    Location: http://.../firefox/1.0/1.0.0/+file/filename.txt
    ...

Firefox 1.0/1.0.0 now has one file.

    >>> files_url = '/firefox/1.0/1.0.0/files'
    >>> ff_100_files = webservice.get(files_url).jsonBody()
    >>> print_self_link_of_entries(ff_100_files)
    http://.../firefox/1.0/1.0.0/+file/filename.txt

The file type and description are optional.  If no signature is
available then it must be explicitly set to None.

    >>> file_content="second attachment file content"
    >>> response = webservice.named_post(ff_100['self_link'], 'add_file',
    ...     filename='filename2.txt',
    ...     file_content=file_content,
    ...     content_type='plain/txt')
    >>> print response
    HTTP/1.1 201 Created
    ...
    Location: http://.../firefox/1.0/1.0.0/+file/filename2.txt
    ...

Firefox 1.0/1.0.0 now has two files.

    >>> files_url = '/firefox/1.0/1.0.0/files'
    >>> ff_100_files = webservice.get(files_url).jsonBody()
    >>> print_self_link_of_entries(ff_100_files)
    http://.../firefox/1.0/1.0.0/+file/filename.txt
    http://.../firefox/1.0/1.0.0/+file/filename2.txt

The file redirects to the librarian when accessed.

    >>> url = webservice.getAbsoluteUrl(
    ...     '/firefox/1.0/1.0.0/+file/filename.txt/file')
    >>> result = webservice.get(url)
    >>> print result
    HTTP/1.1 303 See Other
    ...
    Location: http://.../filename.txt
    ...

Project release files can be deleted using the 'delete' method.  The
project maintainer, project series owners, admins, or registry experts
can delete files.

    >>> url = webservice.getAbsoluteUrl(
    ...     '/firefox/1.0/1.0.0/+file/filename.txt')
    >>> results = webservice.named_post(url, 'delete')
    >>> print results
    HTTP/1.1 200 Ok
    ...

    >>> files_url = '/firefox/1.0/1.0.0/files'
    >>> ff_100_files = webservice.get(files_url).jsonBody()
    >>> print_self_link_of_entries(ff_100_files)
    http://.../firefox/1.0/1.0.0/+file/filename2.txt

Anonymous users can access project release files.

    >>> release_files = anon_webservice.get(
    ...     '/firefox/1.0/1.0.0/files').jsonBody()
    >>> print_self_link_of_entries(release_files)
    http://.../firefox/1.0/1.0.0/+file/filename2.txt


Commercial subscriptions
------------------------

If a project has a commercial-use subscription then it can be retrieved
through the API.

    >>> from zope.component import getUtility
    >>> from lp.registry.interfaces.product import IProductSet
    >>> from canonical.launchpad.ftests import login, logout
    >>> login('bac@canonical.com')
    >>> product_set = getUtility(IProductSet)
    >>> mmm = product_set.getByName('mega-money-maker')
    >>> print mmm.commercial_subscription
    None

    >>> owner = mmm.owner
    >>> mmm.redeemSubscriptionVoucher('mmm_voucher', owner, owner, 12,
    ...     'notes')
    >>> print mmm.commercial_subscription.product.name
    mega-money-maker

    >>> logout()

    >>> ws_uncache(mmm)
    >>> mmm = webservice.get("/mega-money-maker").jsonBody()
    >>> print mmm['display_name']
    Mega Money Maker

    >>> print mmm['commercial_subscription_link']
    http://.../mega-money-maker/+commercialsubscription/1