Over the past few weeks we've been quietly slipping mentions of API V2 in to our documentation and its usage has slowly increased. We're now ready to officially announce V2 of the Zencoder API. We're introducing versioning into our API because it makes it easier for us to introduce changes without breaking backwards compatibility, plus it makes it easier for developers working with Zencoder to transition to new versions when it's convenient for them.
The original Zencoder API (V1), used for the majority of API requests made to Zencoder, has been at https://app.zencoder.com/api/. It is now at https://app.zencoder.com/api/v1/.
The new Zencoder API (V2) is at https://app.zencoder.com/api/v2/.
Note the "v1" and "v2" in the URLs, indicating the version of the API used.
For the next 6 months, until June 1st, 2012, API requests to https://app.zencoder.com/api will continue to work as they do today (ie V1). Starting June 1st any requests that do not specify a version will use Zencoder's edge (under development) API, which will be discussed in a later post.
Additionally, on June 1st, 2012, API V1 will be removed. At this point all users will have to switch to API V2 or another version, if one is available.
The Flixcloud API will be removed at this time as well, on June 1st, 2012. Any Flixcloud users who migrated to Zencoder when it was shut down will need to switch over to use the Zencoder API now. As always you can contact support with any questions you have as you make the transition.
What's New in API V2?
There's a lot of great new features available in V2 that make working with Zencoder even better.
Rich Notifications
Rich notifications is one of the most common feature requests we get. In V2, notifications now include all metadata about the input, the output, and the job, in addition to the state that was sent in V1. Read more in the docs.
Backup Storage
Sometimes servers go down, or are unaccessible. This used to mean your job would fail, but now if we're unable to connect to your server we'll save the file on Amazon S3 for 24 hours instead. If this happens your POST notifications will contain an extra parameter called "backup_url_used", and it'll be set to true. Additionally, the URL for the output file will be changed to the S3 URL where your file is being held. You, or your application, can then download the file to your server at your convenience. Read more in the docs.
More Progress APIs
In V1 it was possible to use the API to request progress of outputs, but not inputs or jobs. We've now added progress for both of them, so you can return more information back to your users about the state of their files. Read more about input progress and jobs progress in the docs. Additionally, output progress has changed to include more information about what's happening.
Reporting and Grouping
Some users have a single Zencoder account handling their video encoding for multiple clients or departments and want to know how usage is spread across them. Grouping creates collections of jobs whose usage can be retrieved via the new reporting API. Read more in the docs.
Dependent and Transfer-only Outputs
Outputs can be created that won't run until another has finished, allowing you to create a single output and transfer it to multiple servers. Read more in the docs about dependent outputs and transfer-only outputs.
Aspera Transfers
Aspera supports high speed file transfer over UDP rather than HTTP, which means Zencoder can transfer larger files quickly from your Aspera server, getting your videos transcoded and back to you faster than before. Read more in the docs.
Conditional Outputs
Accepting user generated content means you never know what you might get. Converting a 320x240 video to 720p just leaves you with a poor video or multiple copies of your output at the same resolution. Conditional outputs let you skip an output if it the input file is too large, too small, too long, or too short, rather than going through the hassle of inspecting the file on your own or submitting multiple jobs. Read more in the docs.
If you've written your own code for interacting with Zencoder then switching to the versioned API is as easy as changing the URLs you use to make requests. If you are using a library to interact with Zencoder it's pretty easy to switch those too. Along with the new functionality in the Zencoder API we've updated our Ruby and PHP libraries, and some of our users have updated their libraries as well.
The Zencoder Ruby library has been updated to default to use V2. This update includes other significant changes, so check out the ReadMe for more information on what it does and how to implement it.
If you are unable to upgrade to the latest version of the Ruby library, you can add Zencoder.base_url = "https://app.zencoder.com/api/v2" in your initializer where you set your API key to start using V2.
The Zencoder PHP library has been updated to default to use V2. This update includes some significant changes, so check out the ReadMe for more information on what it does and how to implement it.
If you are unable to upgrade to the latest version of the PHP library you can make requests to any URL using the general API request method discussed in the ReadMe. You can also edit a single line in Zencoder.php and change it to https://app.zencoder.com/api/v2, which will make all requests use the V2 URL.
In the Zencoder Python library V2 is now the default in version 0.4 of the library.
As the Zencoder libraries created by some of our fantastic users are updated to support versioning and V2 we will add instructions on how to update them as well. If you have any questions about updating your library, contact us.
Versioning Makes Things Better
Versioning is going to let us move forward with new features more aggressively because we can add new features and options that aren't backwards compatible without worrying about impacting users who are currently relying on them. We will do our best to keep versions alive as long as it makes sense for us to support them and will give plenty of notice before removing any API version. This is our first step for versioning, and we're still figuring out some of the details as we go, but we plan to follow this convention as we release new versions of the API. We welcome your feedback as we continue making Zencoder better.
