This Saturday, May 9, Vimeo is sponsoring a brand-new API event, appropriately dubbed “Video Hack Day.” This all-day event takes place May 9 at General Assembly in NYC. Stop by to hear fascinating keynotes from members of the tech community. And when the talks stop, stick around and build some awesomely innovative video apps, websites, tools, and toys.

Should you attend, swing by the Vimeo table (a.k.a. the “cool” table). We’ll be giving out high-fives and three free months of Vimeo PRO to anyone who stops by to say “yo.” But that’s not the only thing we’re giving away — at the end of the night, the best Vimeo API integration made at the event will take home a video-enabled quadcopter.

Space is limited, so register now! We’re psyched to see what you build…

makingvimeo:

When we talk to filmmakers, we like to say that Vimeo “gives your work the power to amaze.”  We’ve since extended that metaphor to developers: give your app the power to amaze.  Today we’re announcing the release of four open-source iOS projects that help developers integrate core Vimeo services and technology into their own mobile apps. They’re all libraries that are both in active development and present in our own products, so fear not — no stale code here. We’re gonna keep this stuff fresh.

Why is Vimeo doing this?

We’re constantly dreaming and scheming up cool new things to try on mobile, but we’re not the only ones with brains and good ideas. We wish we could hire every badass mobile dev out there, but until that day comes, we’re set on empowering each of them to create more “Vimeo things.”

We’re pumped to see what you’ll develop around these open-source projects, and how Vimeo and the developer community at large can work together to build amazing experiences on mobile. We’re also committed to frequently rolling out improvements and optimizations, so don’t be shy about sharing feedback and making feature requests.

Got it, so what do they do?

There are four distinct projects.  Allow me to break them down, one by one.

VIMNetworking

Some call it an Objective-C library that enables interaction with the Vimeo API. Others know it as the Vimeo iOS SDK. It handles authentication, request submission and cancellation, video upload, and advanced features like caching and powerful model object parsing.

In non-README vernacular, that boils down to the ability to develop customized native experiences around Vimeo’s videos, users, and API features — of which there are MANY. It’s all about giving you, the developer, access to view and interact with Vimeo’s vast content catalog, user base, and feature set on your own terms.

Por ejemplo:

Let’s say you’ve got an amazing video-editing tool, and you want your users to be able to seamlessly send their creations straight to their Vimeo profile with easy authentication and file transfer — VIMNetworking has you covered. 

Let’s say you want to build an immersive viewing experience around a specific type of video category (maybe… Documentaries about Culture and Technology) — VIMNetworking’s got your back, and so does VIMVideoPlayer. Speaking of which…

VIMVideoPlayer

Even though we’re all Apple fanboys at heart (seriously, just stop denying it), sometimes their native video player doesn’t give you exactly what you want. We hit this roadblock whilst implementing what we thought was a best-in-class video player. We got around that roadblock by developing VIMVideoPlayer, which is a simple wrapper around the AVPlayer and AVPlayerLayer classes.

Use it to give your design and UX team complete control on how they present and manipulate videos.

VIMObjectMapper  

JSON is SO hot right now, but parsing it into a native model object is a hassle. Let us handle the hassle with VIMObjectMapper. You focus on building a sweet app.

Pegasus

Let’s be real — uploading multiple large video files on iOS can be annoying. Users might background their app, lose Internet connectivity, or simply attempt to do too many things at once. No one knows this better than us. We think about how to upload videos… a lot. We also find it equally as annoying when two developers write the same code to do the same thing. Our solution? Share the solution!  

Pegasus is a sample iOS app that leverages VIMNetworking to enable seriously badass background networking capabilities for apps and extensions alike. It can also be abstracted to perform other types of background tasks, such as downloads, content syncing, notification requests, etc.

Wanna queue up four HD videos for upload? Not a problem.  

Don’t want to force users to stare at a progress bar while their pizza cat documentary ascends to the cloud? S’all good, Pegasus will take care of that in the background so your peeps can grab another slice with their fav feline.

Not only are we giving you the raw ability to do this, we’re also giving you a shell UI on which you can build your own apps. Sure, it’s pretty bare bones… but that’s what a sample app should be. We know that you know an amazing designer who’s going to make it look like that crazy idea in your head. We’re just saving you the hassle of writing rock-solid upload code that’s already tested and in production.

Why should you care?

Bottom line: it saves time. Ask our product team, and they’ll tell you a little more (they always do, don’t they?). These libraries, when used in conjunction with our public-facing API, allow you to build apps on top of an infrastructure that’s well-maintained, tested, and free.  

Have an amazing video app idea but can’t afford to host the content or build an authentication system? We’ll fill in the blanks.  

Are you a badass UI developer that wants to prototype an app idea without shelling out major bones for developers? Pegasus is sounding mighty tasty right now… in’it?

Long story short — you can have your cake, and eat it too.  Just save some for us. We love cake.

What next?

Alright, enough with the verbal hyperbole and blue-sky ideas. Let’s write some damn code.

GitHub Repo

API Documentation

Send us your feedback!

Tweet at us: @vimeoapi

Post on Stackoverflow with the tag “vimeo-ios”

Are we speaking your (highly optimized and bug-free) language? Maybe there’s a job for you at Vimeo…here

(Source: makingvimeo)

For nearly six months now, our brand-new API has been sitting patiently in beta, waiting for the day it’d be released to the world. Today, we’re thrilled to metaphorically pick up those giant scissors and cut that red tape. Now, everyone has access to the newly designed developer site, and the extra-fresh Vimeo API.

What’s changed? In short: everything. We’ve improved every single aspect of our documentation to some degree. We cleaned up the spec, and have ensured that our endpoint documentation is absolutely accurate. You might also notice return of the API Playground you once knew and loved. We completely overhauled the playground to make it fit the new API, and we whole-heartedly encourage you to spend recess exploring all of our API’s new features.

The API has been updated to version 3.2, and is available immediately. To learn more about our version system, check out the docs. Thanks to our beta testers, we have cleaned up our response formats and have squashed many bugs. Keep an eye open for the new “connections” and “pictures” formats.

The beta hasn’t just been about polishing our existing features — there were some features we wanted to make available on day one. Our two most requested features have always been Vimeo On Demand and thumbnail uploads, both of which are now a part of the API. In the coming weeks, we will write more about these features, but for now, you can read up on things in our endpoint documentation

These aren’t the last of the new additions — we still have so much more to come. Keep an eye on our roadmap to learn about all the awesome new features we’re working on.

WARNING — None of the following will make any sense whatsoever unless you are aware that the open beta for for our new API has begun. Read all the details.

Some of our requests give you a TON of data. And while data is super fun, sometimes, you don’t need that much. We are working on a system that will allow you to limit the response fields we send, but what if you don’t need a response at all?

HTTP allows you make conditional GET requests. These requests let you tell our servers a little bit more about the request you want to make. Currently, we only support one conditional request: If-Modified-Since.

If-Modified-Since

Say you were building a tool to watch for new Staff Pick videos. Without the If-Modified-Since header, you would request all Staff Pick videos and loop through trying to find new videos.

curl -v -H "Authorization : bearer <ACCESS TOKEN>" https://api.vimeo.com/channels/staffpicks/videos

< HTTP/1.1 200 OK
< Date: Wed, 19 Mar 2014 19:31:53 GMT
* Server Apache is not blacklisted
< Server: Apache
< Cache-Control: no-cache, max-age=315360000
< Vary: Accept,Vimeo-Client-Id,Accept-Encoding
< Last-Modified: Wed, 19 Mar 2014 15:29:35 -0400
< Expires: Sat, 16 Mar 2024 19:31:53 GMT
< Content-Length: 5788
< Content-Type: application/vnd.vimeo.video+json
<
{
    total: 7670,
    page: 1,
    per_page: 25,
    paging:
    {
         next: '/channels/staffpicks/videos?page=2',
         previous: null,
         first: '/channels/staffpicks/videos?page=1',
         last: '/channels/staffpicks/videos?page=307'
    },
    data: [ … ] 
}

Notice the response headers. One of these headers is Last-Modified: Wed, 19 Mar 2014 15:29:35 -0400. This tells you the last time a video was added or removed from the Staff Picks Channel. Make a note of this date.

Next time you check for new videos, add the If-Modified-Since header with the current date.

curl -v -H "Authorization : bearer <ACCESS TOKEN>" -H “If-Modified-Since: <CURRENT-DATE>” https://api.vimeo.com/channels/staffpicks/videos

< HTTP/1.1 304 Not Modified
< Date: Wed, 19 Mar 2014 19:54:36 GMT
* Server Apache is not blacklisted
< Server: Apache
< Expires: Sat, 16 Mar 2024 19:54:36 GMT
< Cache-Control: no-cache, max-age=315360000
< Vary: Accept,Vimeo-Client-Id,Accept-Encoding

Notice there isn’t a response body at all, but there is a 304 status code. 304 Not Modified means that nothing has changed since the date you provided. If a video had been added since that date, you will see the full response body. Let’s make one more API request to see this in action. The following example checks for new additions since 1987, significantly predating Vimeo.

curl -v -H "Authorization : bearer <ACCESS TOKEN>" -H “If-Modified-Since: 04-27-1987” https://api.vimeo.com/videos/31436718

< HTTP/1.1 200 OK
< Date: Wed, 19 Mar 2014 19:31:53 GMT
* Server Apache is not blacklisted
< Server: Apache
< Cache-Control: no-cache, max-age=315360000
< Vary: Accept,Vimeo-Client-Id,Accept-Encoding
< Last-Modified: Wed, 19 Mar 2014 15:29:35 -0400
< Expires: Sat, 16 Mar 2024 19:31:53 GMT
< Content-Length: 5788
< Content-Type: application/vnd.vimeo.video+json
<
{
    total: 7670,
    page: 1,
    per_page: 25,
    paging:
    {
         next: '/channels/staffpicks/videos?page=2',
         previous: null,
         first: '/channels/staffpicks/videos?page=1',
         last: '/channels/staffpicks/videos?page=307'
    },
    data: [ … ] 
}

There have definitely been videos added since this date, so the response is identical to a request without the If-Modified-Since header.

If-Modified-Since lets you speed up your app significantly, so you should probably use it whenever you possibly can! Not all collections support these headers just yet, so look for the Last-Modified header. If you need this feature added anywhere, please do let us know.

Next up: Video credits

This feature requires a User Access Token.

Now that you can make authenticated requests, you can interact with a video.

We provide resource interactions that allow users to easily interact with Vimeo resources via the API. These interactions allow you to like a video, join a group, follow a channel, and more. Below, I’ll describe how to interact with a video (for one, never look it in the eye).

Interacting with a Video

First, make an authenticated request for a video. The response will contain the information you need.

curl -H "Authorization : bearer <ACCESS TOKEN>" https://api.vimeo.com/videos/31436718
...
"interactions": {
    "watchlater":{
        "added":false,
        "added_time":null,
        "uri":"\/users\/8607249\/watchlater\/31436718"
    },
    "like":{
        "added":true,
        "added_time":null,
         "uri":"\/users\/8607249\/likes\/31436718"
    }
}, 
….

Notice the field interactions. This describes some of the common actions a user might perform with this resource. The two we currently provide are “like” and “watchlater”. These two interactions behave identically, so let’s focus on “like”.

Within the like object, there will be three parameters: added, added_on, and uri.

• added - boolean - This field describes the current state of the interaction. “true” means you have already performed this interaction (e.g., you have liked this video) and “false” means the interaction has not yet happened.

• added_on - date - This field will be null if added is false, and a date if added is true. This field tells you at what date the interaction was performed (e.g., at what date you liked this video).

• uri - string - This field contains the API endpoint that allows you to perform the interaction. If added is false, you should make a PUT request to this URI to perform the interaction. If added is true, you should make a DELETE request to this uri to undo the interaction.

If you have not yet liked the Bug Report video, you can like it by making the following PUT request.

curl -H "Authorization : bearer <ACCESS TOKEN>" -XPUT https://api.vimeo.com/me/likes/31436718

If you have already liked the Bug Report video, you can unlike it by making the following DELETE request.

curl -H "Authorization : bearer <ACCESS TOKEN>" -XDELETE https://api.vimeo.com/me/likes/31436718

If you are not allowed to interact with this video, you will receive a 400 or 500-level status code. These errors are always accompanied by a description of the problem — if it’s not clear, check out our help section.

Developing with interactions

When developing your API integration, we recommend that you call the URL directly from the video response instead of trying to build it yourself. In the PHP library, this looks like the following example:

$video = $lib->request(‘/videos/31436718’);

if ($action === ‘unlike’) {
    $method = ‘DELETE’;
} else if ($action === ‘like’) {
    $method = ‘PUT’;
}

$like = $lib->request($video[‘interactions’][‘like’][‘uri’], $method);

NEXT TIME : Conditional HTTP Requests.

Get excited — the open beta for our new API has begun.

Ready to take it for a test drive? Let’s talk about your first API request.

Create your API app

Go to https://developer.vimeo.com/apps/new, fill out the necessary information and click “Create App”. You will be redirected to your app details page; click the “OAuth 2” tab to find the following authentication information:

• Client ID - A unique identifier for your application
• Client Secret - A secret identifier for your application, this should never be shared with anyone
• Client Access Token - A token that allows your app to make unauthenticated requests
• User Access Token - A token that allows you to make API requests authenticated as yourself (the app owner)

Make a request

Once you have your tokens, you are ready to make a request. We use OAuth 2.0 and bearer tokens to authenticate your requests. OAuth 2.0 requires you to pass tokens through the Authorization header.

Authorization : bearer <TOKEN>

Try this now by adding your User Access Token to the following example, and entering it into your terminal.

curl -H "Authorization : bearer <ACCESS TOKEN>" https://api.vimeo.com/me

The response will include all the information related to your user account. In this response, you can see your entire profile, including your current upload quota.

If you receive an error, you may have entered the wrong token. The Client Access Token won’t work for private data, so make sure any “https://api.vimeo.com/me” requests use a User Access Token.

But — you don’t have to use the tokens we provide you. In fact, the tokens we give you are limited, and cannot access the whole API. To learn more about authentication and generating access tokens, read our full Authentication Documentation.

Vimeo’s first API was launched on Mar 26, 2007. We’ve added tons of features since then, but have always been stuck with two APIs. The Simple API was super easy to use, but didn’t allow authentication. The Advanced API had tons of features, but was more difficult to implement. We always knew, deep down, we could build a better system. We dreamt of one API to rule them all — one API that a developer could get up and running in minutes, instead of days. After many months of research and development, we are proud to announce the start of the open beta for our brand new API.

This singular, unified API replaces both the Advanced and Simple APIs. Just like the Simple API, all features are accessible within an easy to understand URL structure. This URL structure follows many of REST’s best practices, and has been carefully considered in every step of development.

That shouldn’t actually matter, though, because we also provide this information to you as often as possible. We’ve created resources that provide URLs or URL templates to guide you through our data. Should you ever forget what features are available, start with “https://api.vimeo.com/me” and start following links. Watch out, though. It’s addictive.

Over the next couple of weeks, we’ll tell you more about some of the new features supported by the API. If you’d like to be notified when we post something new, join our Google group.

Questions? Bug reports or feature requests? Contact us through our Help Center.

And to see the new API in action, take a look at the Vimeo apps for iOS and Xbox, which already have it integrated (I mean, we said this was beta. Not alpha…).

• Documentation
• Google Group
• Help
  
  

Aaron Hedges heads up all things API at Vimeo. He’s worked tirelessly on the new API for the past year and has managed not to crack (yet).

We’ve been hard at work building a brand new version of the Vimeo API (dubbed API 3.0) and we’d like to invite you to join us at Vimeo HQ to try it out!

We’ll be here May 4th from 11am to 7pm to help you build apps on the new API. The best creations will be featured on our blog and dev site.

Some of the new features your app can take advantage of are:

• Register for push notifications
• Create albums and groups
• Simplified video upload
• Easy access to a large collection of Creative Commons videos

As well as all the features of the Advanced API, including:

• Access a user’s Feed and Watch Later queue
• Interact with the Vimeo community
• Interact with the video player via JavaScript

Come check it out!

When: May 4, 2013 from 11am to 7pm
Where: 555 W 18th St, New York, NY
RSVP: http://vimeo-hackday-1.eventbrite.com

Would you be totally flabbergasted if we told you that in addition to rebuilding Vimeo from the ground up, we’ve ALSO constructed a brand new site for developers who want to rock the Vimeo APIs? Well, start flabbering your gasts* — because it’s true.

We’re happy to announce our brand new developer site: http://developer.vimeo.com! Our API is all grown up and ready to move into its own 1 bed / 1.5 bath subdomain. Laundry is just around the corner.

Right now you’re probably staring incredulously at your screen while yelling, “Whoa!!! Tell me some of the amazing features of this new dev site so I can continue my quest to conquer all technology!!!” You got it. Check our techniques:

OAuth Tokens provided

We now generate an OAuth token for you when you create an app — this way you don’t have to set up a temporary page to authorize when you only want to interact with your account. Just copy and paste into your app. OAuth awesomeness!

Simplified documentation and navigation

Life is complicated enough, so we’ve tried to streamline our documentation wherever possible. Now, instead of having to look at multiple pages of docs, you’ll find what you need on one page, reducing the need to jump around. And just like your favorite library book about deep sea creatures that somehow survive in complete darkness, our documentation now has a table of contents. Just flip to the section you’re looking for!

Clearer upload requests

Upload requests now take the form of a more straightforward questionnaire. This enables us to get right down to bizness and reduce the back and forth involved in approving your app for uploading. Because time is money, people.

Integrated Playground

The Advanced API method list now has the playground baked right into it, so you can easily get involved in some hot call-and-response action.

A suave new look

Night time is the right time for accessing data via the API. Turn the lights down, pour yourself a beverage, and kick back with some stone cold support from us.

Enjoy the new site!

*We have no idea what this means, but it feels good to say it out loud.

To be consistent with how it is handled on-site, we will be requiring read permissions for vimeo.videos.getSubscriptions starting on April 2. You will need to pass a user token to the call or you’ll receive an error.