1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
|
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
|