Hello Amara API consumers!
We are planning on making some changes to our API over the next few months, including a handful of backwards incompatible changes. This may require changes to your client code, although we hope that it should be fairly minor. The majority of the changes are simply dropping fields that have been deprecated for a long time now and have been replaced with new fields.
We also have new and improved API documentation. Check it out at apidocs.amara.org. We’ve stopped updating our old API docs at https://amara.readthedocs.io/. Please update your bookmarks.
When?
- On June 19th, 2019 we will switch over to the new API behavior.
- Anytime between now and the switch over date, you can send the header
X-API-FUTURE: 20190619
to get the new API behavior. Use this to test your code changes and also to deploy your updated production code before the switch over date. - Please give us feedback by emailing support@amara.org with the subject “Amara API changes” if any of these changes will cause significant issues with your API integration.
Our API change policy specifies how we handle API changes.
Authentication
x-api-username
will no longer be needed. We will only requirex-api-key
to authenticate.
Video Resource
(https://apidocs.amara.org/#videos-resource)
- Input handling:
- Blank values will no longer be ignored. If you pass in an empty string for the fields like team or primary_audio_language_code, we will set the value to the empty string rather than ignoring it. If you want to leave a field unchanged, simply leave it out of the JSON dict.
- The string
"null"
will no longer be treated asnull
.
- One deprecated field will be dropped:
original_language
. Use thenew name primary_audio_language_code
instead.
- New features:
- We will add a
primary_audio_language_code
query param to allow filtering by video language.
- We will add a
Video URL Resource
(https://apidocs.amara.org/#video-urls)
original
will be read-only. It was never intended to allow changes.
Subtitles Resource
(https://apidocs.amara.org/#subtitles-resource)
- Several deprecated fields will be dropped:
version_no
. Use the new nameversion_number
insteadvideo
. Use the new namevideo_title
instead.
Subtitle Language Resource
(https://apidocs.amara.org/#subtitle-language-resource)
- Several deprecated fields will be dropped:
is_original
. Use the new nameis_primary_audio_language_code
instead.is_complete
. Use the new namesubtitles_complete
instead. (Note that is_complete will still continue to be supported for the Subtitles resource )https://apidocs.amara.org/#subtitles-resourcenum_versions
. Count the items in theversions
array instead.original_language
. This field used to be used to track “language forks”, but we haven’t supported that for a long time.is_translation
. This field used to be used to track “language forks”, but we haven’t supported that for a long time.id
. This is an internal amara identifier and shouldn’t be used by 3rd parties. The one thing that it was useful for was manually creating URLs to the Amara page. However usingsite_uri
is simpler and more reliable.reviewer
andapprover
. As far as we know, these were only used by 1 partner and they now have a better way to get this data.
- The versions list data will be changed
version_no
will be renamed toversion_number
Team Applications Resource
(https://apidocs.amara.org/#team-applications)
- Improved before/after filters:
- Right now these input a unix timestamp integer
- We will change it so they also support ISO-8601 as well.
Team Member Resource
(https://apidocs.amara.org/#list-team-members)
- API clients will no longer be able to add arbitrary users to their teams:
- API clients will still be able to add users that they created via the API
- API clients with the partner flag set will still be able to add arbitrary users.
Legacy Activity Resource
(https://apidocs.amara.org/#legacy-activity-resource)
- Changing the default listing:
- We will change what gets returned when you fetch this endpoint without any filter params.
- The new behavior will be to list activity that your user has performed. It will no longer include activity for all teams that you are a member of.
Activity Resource
(https://apidocs.amara.org/#activity)
- Improved subtitle request records
- Added extra fields in the response so that these are more useful to work with. For example when a user accepts an assignment, we now return user and role data.
- Updated the documentation for this (https://apidocs.amara.org/upcoming/#activity-types)