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 text

  • reviewbody - Multiline text

  • stars - 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 submitted

  • reviewdate - 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 review

  • review_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.