Upcoming Amara API Changes – Summer 2019

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.

Authentication

• x-api-username will no longer be needed. We will only require x-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 as null.
• One deprecated field will be dropped:
  • original_language. Use the new name primary_audio_language_code instead.
• New features:
  • We will add a primary_audio_language_code query param to allow filtering by video language.

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 name version_number instead
  • video. Use the new name video_title instead.

Subtitle Language Resource

(https://apidocs.amara.org/#subtitle-language-resource)

• Several deprecated fields will be dropped:
  • is_original. Use the new name is_primary_audio_language_code instead.
  • is_complete. Use the new name subtitles_complete instead. (Note that is_complete will still continue to be supported for the Subtitles resource )https://apidocs.amara.org/#subtitles-resource
  • num_versions. Count the items in the versions 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 using site_uri is simpler and more reliable.
  • reviewer and approver. 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 to version_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)