API v1 to v2 Migration Guide

This guide will help you upgrade from API v1 to the more modern API v2. See our  vzaar Developer docs for full documentation.

If you need your vzaar integration to continue working once we have retired API v1 you'll need to update it to API v2. We recommend starting this process immediately because while it should be a relatively simple change, there may be complications in your integration that are difficult to anticipate — remember we are always here to help!

API v2 includes many improvements over API v1 and will be the only version receiving support and new features. It also uses JSON rather than XML so it is much easier to work with.

Migration Checklist

  1. Check you have access to API v2
    1. Go to API Settings and if the green button says "Generate API Token" then you have access
    2. If it simply says "Generate" then you don't
    3. Get in touch with us and we'll give you access to API v2
  2. Familiarise yourself with JSONREST and the vzaar API docs
  3. Determine which API endpoints your integration is using and find the equivalent endpoint below
  4. Update your integration to use API v2 or an API v2 SDK
  5. Let us know if there's anything you need in API v2 that is not available
  6. Update the error handling and rate limiting in your integration
We always recommend using a  vzaar SDK over a custom integration, firstly because it is less work for you to implement and secondly because updates are as simple as updating a dependency and will rarely require any changes to your integration.

Authentication

API v1 uses OAuth for authentication whereas API v2 uses Client ID and Client Token to authenticate. These can be provided in request headers or in the path/querystring.

See the  API Authentication docs for full details.

Errors & Status Codes

API v1 uses  HTTP Status Codes for error reporting and v2 is no different. In v1 only 200 OK, 401 Not Authorized and 500 Internal Server Error are commonly returned, however, v2 has a few additional success responses that provide more context (such as 201 for when a resource was created).

Read more about API v2 Status Codes.

What's important is that you can continue to consider 2xx responses successful, 4xx responses indicating there was something wrong with the request and 5xx responses indicating there's something wrong with the API's ability to respond to the request.

Endpoint Mapping

The Base URL for API v2 is  https://api.vzaar.com/api/v2 — v2 endpoints are prefaced with /v2 as opposed to /v1 so you can use that to check whether which version of the API you are using.

In many cases the parameter names have changed and additional parameters have become available so it's always recommended to view the full documentation for reference.

Videos

Endpoint v1 v2
Get Videos /{username}/videos.xml
/v2/videos
Lookup Video /videos/{video}.{format}
/v2/videos/{video}

Uploading

Endpoint v1 v2
Sign /videos/signature
/v2/signature/single/2
Process /videos /v2/videos
Link Upload /upload/link.xml
/v2/link_uploads

Managing

Endpoint v1 v2
Edit Video /videos/{video}.xml
/v2/videos/{video}
Delete Video /videos/{video}.xml
/v2/videos/{video}
Generate Thumbnail /videos/{video}/generate_thumb.xml
/v2/videos/{video}/poster
Upload Thumbnail /videos/{video}/upload_thumb.xml
/v2/videos/{video}/poster
Add Subtitle /subtitle/upload.xml
/v2/videos/{video}/subtitles

API v1 Retirement

API v1 will become unavailable mid-2019 and we strongly recommend switching to API v2 as soon as possible to avoid problems with your integration.

We're able to support you through this transition and you can always contact us to let us know if you're ready to switch or are having trouble doing so.

For further reading, we'd recommend the full  API v2 documentation.

Still need help? Contact Us Contact Us