Review: Vimeo API Update Provides Robust Access to Service's Ecosystem

Doron Katz,  Consultant | Analyst | Journalist | Socialite
Sep. 03 2014, 11:00AM EDT

Social video sharing network Vimeo, notable for its emphasis on non-commercial and unique user content, has released a brand-spanking new revision of its API, versioned at 3.2. Recently out of beta, the new version of the Vimeo API is notable for many capabilities--not least, robust access to the Vimeo ecosystem, from querying videos to users, channels and groups. Among the new features introduced in version 3.2 are access to Vimeo On Demand, thumbnail uploads, new response formats (and polishing of existing formats) and speedier response times.

Vimeo API at a glance

The main hub of Vimeo’s API documentation starts at http://developer.vimeo.com, where Vimeo has organized its API on its landing page:

  1. API - an exhaustive list of RESTful API endpoints;
  2. Vimeo Player - for either embedding the player or providing hooks into the player via Actionscript or Javascript
  3. oEmbed - an open-standard for embedding multimedia on websites

API architectural overview

To get started, your first task is to register your app with Vimeo. This allows you to obtain an API key (client ID and secret) for use in authenticating with Vimeo's choice of authentication mechanism, OAuth 2.

Vimeo provides its own libraries for OAuth 2, as well as for PHP, Python (Vimeo.py) and Node. However, if you are creating a mobile app or working with another language, you can seek out an appropriate OAuth library to use for your language platform. While I was happy to see Vimeo's release of a Node.JS client, it would have been nice to see iOS or Android libraries. Then again, YouTube doesn't provide official Objective-C samples, either. Hopefully, the community will fill the gap and keep up to date with the latest versions of Vimeo’s APIs.

Main API components

Once you have successfully authenticated your token, you get access to all of Vimeo’s public APIs. Vimeo offers a smorgasbord of API endpoints, all on a single, easy-to-find page segmented by Categories, Channels, Groups, Me (user), Videos, Users, and On-Demand. (You can find an exhaustive and detailed list at: http://developer.vimeo.com/api/endpoints/.)
 

Vimeo follows a contemporary style of publicizing its endpoints, providing a centralized single page that is easily structured and categorized. In addition to referencing each endpoint, Vimeo provides a playground feature that allows developers to test each individual API live on a website, prior to getting into the nitty-gritty of implementing the code in a project. 

The playground shows the full GET or PUT API syntax, allowing you to input the {parameter} to complete the request.

Querying categories

The first set of Vimeo APIs we tested are targeted at querying the API for a list of categories and channels. To query a category, call the HTTP GET method categories passing a category you wish to search. 

Calling with Animation as the category parameter ( https://api.vimeo.com/categories/Animation), you will expect a JSON response containing the category and its associated metadata information, category image (various sizes and versions of the category image) and an array list of sub-categories belonging to that category. 

 

HTTP/1.1 200
Content-Type: application/vnd.vimeo.category+json
Host: api.vimeo.com

{
    "uri": "/categories/animation",
    "name": "Animation",
    "link": "https://vimeo.com/categories/animation",
    "top_level": true,
    "pictures": {
        "uri": "/videos/658158/pictures/25153220",
        "active": true,
        "sizes": [
            {
                "width": 100,
                "height": 75,
                "link": "https://i.vimeocdn.com/video/25153220_100x75.jpg"
            },
            {
                "width": 200,
                "height": 150,
                "link": "https://i.vimeocdn.com/video/25153220_200x150.jpg"
            },
            ...
        ]
    },
    "subcategories": [
        {
            "uri": "/categories/2d",
            "name": "2D",
            "link": "https://vimeo.com/categories/animation/2d"
        },
        {
            "uri": "/categories/3d",
            "name": "3D/CG",
            "link": "https://vimeo.com/categories/animation/3d"
        }  ...
    ],
    "metadata": {
        "connections": {
            "channels": {
                "uri": "/categories/animation/channels",
                "options": [
                    "GET"
                ],
                "total": 29755
            }
        }
    }
}

The results are straightforward to deconstruct, and we get the type of information we would expect, including category metadata information, category picture (in various size variations),  a list of sub-categories and related "channels" metadata. 

Similarly, to get a list of channels associated with a category, you append /channels to your previous call. You also have optional parameters you can pass, to filter the result by page number or how many items to show per page. You can also query to sub-filter by specific text, and you have the option to decide how to sort the results returned.  

The resulting JSON response is as follows:

…                           
        "connections": {
            "channels": {
                "uri": "/categories/animation/channels",
                "options": [
                    "GET"
                ],
                "total": 29755
            },
            "groups": {
                "uri": "/categories/animation/groups",
                "options": [
                    "GET"
                ],
                "total": 7830
            },
            "users": {
                "uri": "/categories/animation/users",
                "options": [
                    "GET"
                ],
                "total": 1819
            },
            "videos": {
                "uri": "/categories/animation/videos",
                "options": [
                    "GET"
                ],
                "total": 195455
            } 

Querying users

I next tested querying users, with Vimeo exposing end points that provided access to searching for users, as well as to getting a list of albums belonging to a user, the list of channels the user follows, groups the user belongs to, people the user is following, or the list of followers of that particular user. You get access to a list of videos uploaded and more.

We tested the endpoint using a random Vimeo staffer's profile:

HTTP/1.1 200
Content-Type: application/vnd.vimeo.user+json
Host: api.vimeo.com

{
    "uri": "/users/3200676",
    "name": "laura turner garrison",
    "link": "https://vimeo.com/lauraturnergarrison",
    "location": null,
    "bio": "Oh, hello there. I'm the Senior (Citizen) Writer/Producer on Vimeo's Production Team. What that means is I like big ideas and spreadsheets. I'm a huge hit at parties, trust me. Please? You seriously don't trust me? You're probably right. I'll let myself out. Unless?",
    "created_time": "2010-02-18T05:07:26+00:00",
    "account": "pro",
    "pictures": {
        "uri": "/users/3200676/pictures/7624816",
        "active": true,
        "sizes": [
            {
                "width": 30,
                "height": 30,
                "link": "https://i.vimeocdn.com/portrait/7624816_30x30.jpg"
            },
            {
                "width": 75,
                "height": 75,
                "link": "https://i.vimeocdn.com/portrait/7624816_75x75.jpg"
            },
            {
                "width": 100,
                "height": 100,
                "link": "https://i.vimeocdn.com/portrait/7624816_100x100.jpg"
            },
            {
                "width": 300,
                "height": 300,
                "link": "https://i.vimeocdn.com/portrait/7624816_300x300.jpg"
            }
        ]
    },
    "websites": [
        {
            "name": "Twat Me!",
            "link": "http://twitter.com/lturnergarrison",
            "description": "I love to tweet!"
        }
    ],
    "metadata": {
        "connections": {
            "activities": {
                "uri": "/users/3200676/activities",
                "options": [
                    "GET"
                ]
            },
            "albums": {
                "uri": "/users/3200676/albums",
                "options": [
                    "GET"
                ],
                "total": 2
            },
            "channels": {
                "uri": "/users/3200676/channels",
                "options": [
                    "GET"
                ],
                "total": 8
            },
            "feed": {
                "uri": "/users/3200676/feed",
                "options": [
                    "GET"
                ]
            },
            "followers": {
                "uri": "/users/3200676/followers",
                "options": [
                    "GET"
                ],
                "total": 244
            },
            "following": {
                "uri": "/users/3200676/following",
                "options": [
                    "GET"
                ],
                "total": 179
            },

I tested getting information on a specific user, Vimeo staffer Laura Turner Garrison, corresponding with the following user on the Vimeo site:

One can appreciate the elegance and utility of Vimeo’s API responses, which don’t only relay contextual information, but provide hints on various other possible data that could be extracted from related endpoints. The response above includes a JSON attribute following, which not only gives you the URI hint to call for that method, but a return count if we were to call that endpoint, so we can assert that Laura does indeed have a list of followers. The significance is that within the initial call, you can subsequently  decide whether to make other API calls or not, allowing you to be more efficient in the number of calls you need to make. 

 

COMMUNITY

In terms of community support, this is probably the one area that is limited. At the time of writing, the API community resides non-prominently within the Vimeo forums. The strength of the community support is based on the size of the community support, and with Vimeo’s API starting to gain traction, along with it’s product offering which offers a viable and more focused alternative to YouTube and DailyMotion, we would anticipate that this space will improve over time. Vimeo also have a Google User Group and StackOverflow tag, for other avenues of getting community-driven support.

PRICING AND PREMIUM SERVICES

As a premium member, the level of professional increases. Vimeo offer three packages that distinguish by the level of storage, video conversion rate, video player customization as well as human/professional support. 
 

The basic package which is free, provides users with 500MB per week of storage, or 26GB per year, with basic video conversion speeds, whereas the Vimeo Plus option, which costs $59.95 per year, option increases storage to 5GB, and 260GB per year, along with instant prioritized video conversions, and 24-hour weekday support SLA at under 4 hours. The Vimeo Pro premium package is priced at $199 per year, allows up to 20GB of video upload per week, and under 1-hour SLA email support. The good thing with Vimeo, for either plan, there are no duration or file-size restrictions, but YouTube’s restrictions are quite liberal as well. 

API Limitations

Whereas Vimeo don’t impose restrictions in terms of file-size or duration for uploads, they do impose a sort of API hit rate-limit. Whilst they don’t provide a hard cap value, they notify users if they are in danger of reaching that proverbial limit via response headers, which are accessible in all the API responses. 

  • X-RateLimit-Limit: 7500

  • X-RateLimit-Remaining: 7499

In order to avoid reaching that limit, Vimeo advocates caching API responses locally, to reduce the chances of redundant or unnecessary API calls being made, and limit API calls to only essential and meaningful calls. Additionally, Vimeo also help reduce unnecessary API calls, as previously mentioned, by exposing hints as to whether related API endpoints have potential results/counts, embedded within each API call, allowing you to further optimize and restrict calling APIs which may yield no results.
 

FINAL THOUGHTS ON THE API

Vimeo's 3.2 delivers a strong intent to the community that Vimeo is evolving, and in addition to cleaning up and polishing their previous API endpoints, they introduce additional functionalities, optimised endpoints that are fast and contextual. The documentation is structured in a clean, concise and succinct interface, for referencing, as well as playing around with, using playground, which means you can try-before-you-use their API. 

Their API is easy to understand and implement, with their functionality scope at the very minimum on parity with the best of the other social video networks, such as DailyMotion and YouTube. API sorting is robust, performance is now more optimised and you can achieve more with fewer API calls, as we have just tested. 

Although you still are not able to segment videos by region, that is a feature that will be in the pipeline. Speaking of pipelines, Vimeo promises to be more transparent with future feature implementations, publishing their intent in a roadmap, which can be found at https://developer.vimeo.com/api/roadmap

API support is satisfactory, and with the strength of it’s community-driven support based on the size of the community, we should expect the level of non-premium support to increase over time. The current estimated number of Vimeo users is over 100 million, including 400,000 paying members, and growing. Vimeo certainly provides a niche market for video producers looking for a more focused and specialised platform, and if you already host videos on Vimeo, or looking to provide an application that provides a portal to a specific set of content, Vimeo provides the tools at your disposal for just that. We are certainly happy with what we have seen in their latest public update, and look forward to seeing how the wider development community takes to their API. 

Doron Katz A keen passion for emerging technologies, practices and methodologies, Doron embraces the vision of lean development with continuous customer development. Consultant for various startups, as a Project and Product Manager, with a mobile engineering background in iOS, and over 10 years of professional web development experience.

Comments