Hi all, it’s been a while since we’ve done any API changes, but there are some in the pipeline. Most of them are fairly minor, but they may require some code changes. Here’s a rundown of what’s happening:
When?
Backwards compatible changes are currently live. These changes are things like adding a new field to response data or accepting a new type of input. They are listed below as “effective immediately.”
The rest of the changes will go into effect 12/1/2016. If you need to test code changes, or just want to check out the new stuff, you can can see the changes early by adding the GET paramater api-future=20161201 to your requests.
User Data Changes
The largest change is centered around user data. The main reason for this change is to fix an issue with our current API. Whenever we want to identify a user we use their username, however users can change their usernames. This can cause problems if you try to use the username in a later API request.
The first change we’re making to address this is to give users a unique ID that’s guaranteed not to change. When you specify users, you can either use their username or the value “id$[user-id]”. The id method is preferred since it avoids the problems with users changing their usernames, but we also will still allow usernames to be used for backwards compatibility.
The second change is that we will return user data differently. Right now when an API resource contains a user, we typically return the username in one field and the URI to the user API endpoint in a second field. The new system will return a dict of user data with the following fields:
- username: User username
- id: User ID
- uri: User API endpoint
For example, the team member endpoint will change from returning this data:
{
"username": "ben"
"user_uri": "https://amara.org/api/users/ben",
"role": "manager"
}
To this:
{
"user": {
"username": "ben",
"id": "hhhcVFzP0uND6638LBe4rb5B-2b069rna5A64Z98ODU",
"uri": "https://amara.org/api/users/id$hhhcVFzP0uND6638LBe4rb5B-2b069rna5A64Z98ODU/"
},
"role": "manager"
}
Removing the “Safe Team Members” endpoint
Rather than update this one, we’re planning on removing it. A check through the logs indicates that it’s not in use. Is anyone using this one?
Subtitle Language: published flag (formally visible)
We had a flag called “visible” which was present on languages list inside the video resource. It would be set if the language had public subtitles available. This flag seems useful so we added it to the subtitle language resource as well. Also we renamed it to “published” which seems closer to its meaning.
Deleting subtitles
You now have the option to issue a DELETE request on subtitles. This will reset the subtitles by deleting all existing versions. This is only possible for team videos, when the API user is the admin of the team.
Tasks: Modified field
We will be adding a new field on the tasks resource called “modified”. It will be present in the response data and also be available as a sorter.
Team Create: Different workflow styles
This one shouldn’t affect many people, but if you’re one of our partners that uses the API to create teams, you now have the option of creating teams with the collaboration workflow. Talk to an Amara
Summary of changes
Here’s a list of all the endpoint changes. Note that some of the backwards compatible changes will go into effect immediately. Also, check out this readthedocs page for the full description of how the API will look on 12/1/2016: http://amara.readthedocs.io/en/newapi/
Users
- (effective immediately) added id field
- (effective immediately) allow either user IDs or usernames in the path. Either of these now work:
- /api/users/[username]
- /api/users/id$[user-id]
Team Members
- Removed the username field
- Added a user field
- (effective immediately) Allow either user IDs or usernames in the path
Safe Team Members
- Will be removed
Subtitle Language
- Changed author attribute of the versions list to return user dict rather than a username
- Removed author_uri field from the versions list
- (effective immediately) Added published flag
Subtitles
- (effective immediately) Added author field that returns user dict
- (effectivy immediately) Added support for DELETE requests to delete the subtitles
Task
- Changed assignee field to return user dict rather than a username
- (effective immediately) assignee filter now accepts either usernames or user IDs
- (effective immediately) assignee input field now accepts either usernames or user IDs
- (effective immediately) Added modified field
- (effective immediately) Added modified sort parameter
Team
- (effective immediately) Added type field when creating teams. (Note: only user accounts for Amara partners have permission to create teams).
Team application
- Changed user field to return user dict
- (effective immediately) User filter accepts now accepts either usernames or user ID
Video
- Renamed “visible” to “published” for language data inside the languages list.
Activity
- Changed user field to return user dict
- Removed user_uri field
- This only applies to the newer activity resources. The legacy url (/api/activity) will stay the same. The new activity urls are:
- /api/videos/[video-id]/activity/
- /api/users/[user-identifier]/activity/
- /api/teams/[team-slug]/activity/
Messages
- (effective immediately) Made the user field accept either usernames or user IDs
