Reviews API
On this page
Reviews API#
Introduction#
Most items stored by Internet Archive may be reviewed by registered users. Reviews are stored with the item.
Unlike other operations which write to an item, a user does not require special permissions to add a review.
Review structure, syntax, and policies#
A review consists of the following user-editable fields:
reviewtitle
- A single line of textreviewbody
- Multiline textstars
- From 0 (zero) to 5 (five)
Each review also contains the following system-managed fields:
reviewer
- The user’s screenname (not username/email)reviewer_itemname
(optional) - The user’s item (e.g.,@joe_example
)createdate
- Date and time (UTC) of when the review was first submittedreviewdate
- Date and time (UTC) of when the review was last edited
A user may only supply one review per item. Writing a subsequent review will overwrite the earlier one. reviewdate
will be updated and createdate
preserved.
Reviews may not be written for user items or collections. Other limitations exist as well.
Every item with reviews is assigned an average rating computed by summing all the non-zero star ratings and dividing by the number of non-zero ratings. The average rating is currently unavailable via the Metadata API or the Reviews API.
Metadata API#
Item reviews are available via the Metadata API. A full list of an item’s reviews are available under its 'reviews'
branch.
Reviews service#
To update, delete, and read a user’s review for an item, the Reviews API is available. It’s a RESTful microservice located at:
https://archive.org/services/reviews.php
Service details#
All operations require:
An item identifier (using the
identifier
query parameter)User authentication (see below)
The HTTP method (GET
, POST
, etc.) determines which operation is being performed on the review.
For example, to read a user’s review of an item:
GET /services/reviews.php?identifier=foo HTTP/1.1
Host: archive.org
Authorization: LOW <s3-access>:<s3-secret>
For more information on how to interact with the Reviews API, see Internet Archive RESTful microservices.
Reading the user’s review#
Although a full list of reviews is available via the Metadata API, the user can fetch their review of the item directly (if they’ve submitted one) using the HTTP GET
method:
GET /services/reviews.php?identifier=foo HTTP/1.1
Host: archive.org
Authorization: LOW <s3-access>:<s3-secret>
A successful response might be:
{
"success":true,
"value":{
"reviewbody":"the review text",
"reviewtitle":"the review title",
"reviewer":"Joe Example",
"reviewer_itemname":"@joe_example",
"reviewdate":"2020-07-17 20:35:43",
"createdate":"2020-07-17 20:33:14",
"stars":"3"
}
}
If the item doesn’t exist, or the user has not submitted a review to this item, the API will return HTTP 404 Not Found
.
Adding/updating a review#
To add a new review or update an existing one, the user may HTTP POST
a JSON structure with the following fields:
title
(string)body
(string)stars
(int, optional)
POST services/reviews.php?identifier=foo HTTP/1.1
Host: archive.org
Authorization: LOW <s3-access>:<s3-secret>
{
"title":"A review title",
"body":"A review body",
"stars":1
}
If stars
is not specified or non-numeric, a default value of 0
(zero) is assumed.
A successful response will return two fields in the value
portion of the payload:
task_id
(int) - The catalog task identifier for the submitted reviewreview_updated
(bool) -true
if an existing review was updated
For example:
{
"success":true,
"value":{
"task_id":1234,
"review_updated":false
}
}
Deleting a review#
A user may delete their review using the HTTP DELETE
method:
DELETE /services/reviews.php?identifier=foo HTTP/1.1
Host: archive.org
Authorization: LOW <s3-access>:<s3-secret>
A successful response will include the task_id
(as with adding/updating) indicating which task will delete the review:
{
"success":true,
"value":{
"task_id":1234
}
}
If no review was present to be deleted, the response will be HTTP 200 OK
with success
as false
.