In concert with our release of our redesign, a new version of the Appbot API has been released. The use of this version, v2, is mandatory for new users. For existing users, the v1 API has now been depreciated, and users must migrate to the v2 API by 1 November 2018.
The changes between v1 and v2 are mostly minor and should require little change to the existing code. The changes between the APIs are discussed below.
You can find full documentation for the new API at https://app.appbot.co/api.
Required Code Changes to move to v2 API
Swapping “v1” for “v2” in the URLs
The v1 API is located at https://api.appbot.co/api/v1/, while the v2 API is located at https://api.appbot.co/api/v2/. You will need to substitute “v1” for “v2” in the URLs you’re querying. Almost all the URLs will work once this change is made, with one exception.
The exception is the Custom Topics API. The URL for Custom Topics has changed as follows;
- List Custom Topics: https://api.appbot.co/api/v1/apps/:app_id/review_filters changed to https://api.appbot.co/api/v2/apps/:app_id/custom_topics
- List Reviews for Custom Topics: https://api.appbot.co/api/v1/apps/:app_id/review_filters/:custom_topic_id/reviews changed to https://api.appbot.co/api/v2/apps/:app_id/custom_topics/:custom_topic_id/reviews
Generate an API key in the new format
In the v1 API, each API user was automatically assigned a single 40-character hexadecimal API key.
In the v2 API, any team member may create an API key that is associated with the team. This API key consists of a description, a 10 character username (all uppercase letters) and a 44 character password (A-Z, a-z, 0-9, “+” & “/” characters).
To use the new API you will need to generate one or more v2 API keys at https://app.appbot.co/api.
Switch to the new authentication method
In the v1 API, you authenticated to the API by passing your API key via the “key=” query parameter.
In the v2 API, you authenticate with HTTP Basic Authentication, using your API key username as your username, and your API key password as your password. Most HTTP clients support this functionality natively; simply supply the username and password and they will handle the rest.
If your client does not support this, you may be able to pass a URL of the form https://USERNAME:PASSWORD@api.appbot.co/v2/your_api_path to your client. If your password contains any “+” or “/” characters, you will need to replace any “+” with “%2B” and any “/” with “%2F”.
Update to the new review attributes
The v2 API removes the “emotion” attribute from review metadata. This has been replaced by the “sentiment” attribute, which can be “positive”, “negative”, “neutral”, or “mixed”.
Other changes and improvements to the Appbot API
Team-based
The v1 API was a user-based API, and each individual user had their own API key. You were able to access the apps that you personally were tracking with your API queries. Translations were visible in the API output if you personally had translations enabled for a given app.
The v2 API is team-based, and API keys are shared between a given team. You are able to access apps that are tracked by any member of your team. Translations are visible in the API output if any member of your team has translations enabled for a given app.
Rate limiting
The v1 API rate limited based on IP address, the v2 API rate limits based on the team.
Review attributes
The v2 API also adds the following attributes;
- detected_language: The estimated language of the review, from the list of languages from the new “Detected Languages” endpoint.
- permalink_url: Publicly viewable URL for the review (public reviews only)
- reply_url: URL to access the reply page for the review (when supported)
- internal_url: URL to view the review inside Appbot
Aggregate statistic attributes
When viewing review statistics, the v1 API provided tallies of the “positive” and “negative” reviews, which were bucketed based on the star rating.
The v2 API provides tallies of “positive”, “negative”, “neutral” and “mixed” reviews, which are bucked based on the sentiment classification.
New filters
The v2 API endpoints returning reviews can be filtered by a variety of additional attributes, including keyword, country, sentiment, detected language, version, and topic.
New endpoints
The v2 API provides a “Detected Languages” endpoint, which lists all possible languages the “detected_language” attribute can produce.
The v2 API also provides a “Countries” endpoint, which provides the IDs of all countries for a given app, to allow for country-based filtering.
