~rnr-developers/rnr-server/rnrclient

Quickstart

==========

To use the client library for the ratings and review API you'll need to get

`the client library code`_.  That depends on `piston-mini-client`_

that you can also get from the `software-store ppa`_.

To make authenticated calls you'll also need a valid SSO token.

There's a brief snippet to get one using lazr.restfulclient farther down.

.. _the client library code: https://code.launchpad.net/~rnr-developers/rnr-server/rnrclient

.. _piston-mini-client: https://code.edge.launchpad.net/piston-mini-client

.. _software-store ppa: https://launchpad.net/~software-store-developers/+archive/daily-build

.. _public-api-calls:

=======================

Making public API calls

=======================

First thing to do is initialize the API::

    >>> from rnrclient import RatingsAndReviewsAPI

    >>> api_public = RatingsAndReviewsAPI('https://reviews.staging.ubuntu.com/reviews/api/1.0')

We can check that we've initialized the API correctly by using::

    >>> api_public.server_status()

    'ok'

We can also request the rating summaries::

    >>> stats = api_public.review_stats()

    >>> stats

    [<rnrclient.ReviewsStats object at 0x1a79d10>]

We can see there's just one package/app been reviewed so far.  For each item

in the list we can check which package/app it belongs to, what the average

rating is and the total number of ratings it has::

    >>> stats[0].package_name

    'liferea'

    >>> stats[0].app_name

    ''

    >>> stats[0].ratings_average # Average rating for this package/app

    '5.00'

    >>> stats[0].ratings_total   # Total amount of ratings for this app

    1

You can also use the public API to retrieve the reviews for any package

and/or application.  Here you can also provide an optional ``appname``

argument::

    >>> reviews = api_public.get_reviews(language='en', origin='ubuntu',

    ... distroseries='maverick', packagename='liferea')

    >>> reviews

    [<rnrclient.ReviewDetails object at 0x1bc3f90>]

As reported by the stats summary, there's only one review for this package.

We can look at the details for the review, including the review ID that we'll

use later on::

    >>> reviews[0].date_created

    '2011-01-10 12:16:24'

    >>> reviews[0].reviewer_username

    'elachuni'

    >>> reviews[0].summary

    'Some summary'

    >>> reviews[0].review_text

    'Some review text.  And then some more.'

    >>> reviews[0].rating

    5

    >>> reviews[0].language

    'en'

    >>> reviews[0].id

    1

==============================

Making authenticated API calls

==============================

For certain API calls like submitting or flagging reviews you need to have a

valid SSO token.  You can get this from seahorse if you already have one in

your keyring, or you can use a lazr.restfulclient snippet like the one farther

down to get a new one.  These snippets suppose that ``token`` is a dict

containing appropriate token bits.

First we need to instantiate a new API client by passing in a valid oauth

authenticator::

    >>> from piston_mini_client.auth import OAuthAuthorizer

    >>> auth = OAuthAuthorizer(token_key=token['token'],

    ... token_secret=token['token_secret'], consumer_key=token['consumer_key'],

    ... consumer_secret=token['consumer_secret'])

    >>> api_authenticated = RatingsAndReviewsAPI('https://reviews.staging.ubuntu.com/reviews/api/1.0',

    ... auth=auth)

Now we've got an authenticated API, we can submit a new review.

We need to create a ReviewRequest object for that::

    >>> from rnrclient import ReviewRequest

    >>> review = ReviewRequest(package_name='3dchess', summary='Game is great', 

    ... version='0.8.1-16', review_text='Good graphics, great replay value', 

    ... distroseries='maverick', arch_tag='i386', app_name='3D Chess',

    ... rating=4, language='en', origin='ubuntu')

    >>> api_authenticated.submit_review(review=review)

    {'rating': 4, 'hide': False, 'package_name': '3dchess', 'language': 'en', 

    'review_text': 'Good graphics, great replay value', 

    'reviewer_username': 'elachuni', 'date_created': '2011-01-10 12:49:19', 

    'summary': 'Game is great', 'id': 2, 'app_name': '3D Chess'}

You can see the submit_review returns the newly created review.

We can also mark another review as useful (or not).  For this we'll just need

to know the right review id, that was fetched together with the review details

(see :ref:`public-api-calls` at the top of this page)::

    >>> api_authenticated.submit_usefulness(review_id=1, useful='True')

    'Created'

Finally, you can also flag a review for moderation, using the same review id::

    >>> api_authenticated.flag_review(review_id=1,

    ... reason='Inappropriate language', text='"Some" is inappropriate')

==============================================

Getting a valid token using lazr.restfulclient

==============================================

You can get a valid token by using lazr.restfulclient to talk to the sso api::

    >>> from lazr.restfulclient.resource import ServiceRoot

    >>> from lazr.restfulclient.authorize import BasicHttpAuthorizer

    >>> basic = BasicHttpAuthorizer('myemail@myhost.com', '...password...')

    >>> api = ServiceRoot(basic, "https://login.ubuntu.com/api/1.0")

    >>> token = api.authentications.authenticate(token_name="hacking-by-the-pool")

The token name is unimportant here, but it'll let you identify the token you

just created in `the web interface`_.  You'll need to provide a valid SSO

email/password for this to work.  Also note that

``reviews.staging.ubuntu.com`` works against production SSO, so staging tokens

will not work.

.. _the web interface: https://login.staging.ubuntu.com/+applications