This is a simple Node.js library for interacting with the Vimeo API.
There is a lot of information about the Vimeo API at https://developer.vimeo.com/api/start. Most of your questions are answered there!
npm install juicymedialtd/vimeo.js#master
All API requests and examples in this file must create a Vimeo object. Your CLIENT_ID
and CLIENT_SECRET
can be found on your app page under the Authentication tab. If you have not yet created an API app with Vimeo, you can create one at https://developer.vimeo.com/apps.
You can optionally provide an ACCESS_TOKEN
to the constructor. Access tokens are required only to make requests, and you can set them later through the setAccessToken
method.
You can generate acces tokens on your Vimeo app page or through the API.
var Vimeo = require('vimeo').Vimeo;
var client = new Vimeo(CLIENT_ID, CLIENT_SECRET, ACCESS_TOKEN);
All requests require access tokens. There are two types of access tokens:
- Unauthenticated: Access tokens without a user. These tokens can view only public data.
- Authenticated: Access tokens with a user. These tokens interact on behalf of the authenticated user.
Unauthenticated API requests must generate an access token. You should not generate a new access token for each request. Instead, request an access token once and use it forever.
// `scope` is an array of permissions your token needs to access. You
// can read more at https://developer.vimeo.com/api/authentication#supported-scopes
client.generateClientCredentials(scope, function (err, response) {
if (err) {
throw err;
}
var token = response.access_token;
// Other useful information is included alongside the access token,
// which you can dump out to see, or visit our API documentation.
//
// We include the final scopes granted to the token. This is
// important because the user, or API, might revoke scopes during
// the authentication process.
var scopes = response.scope;
});
- Build a link to Vimeo so your users can authorize your app.
var url = client.buildAuthorizationEndpoint(redirect_uri, scopes, state)
Name | Type | Description |
---|---|---|
redirect_uri |
string | The URI the user is redirected to in Step 3. This value must be provided to every step of the authorization process, including creating your app, building your authorization endpoint, and exchanging your authorization code for an access token. |
scope |
array | An array of permissions your token needs to access. You can read more at https://developer.vimeo.com/api/authentication#supported-scopes. |
state |
string | A value unique to this authorization request. You should generate it randomly and validate it in Step 3. |
-
Your user needs to access the authorization endpoint (either by clicking the link or through a redirect). On the authorization endpoint, the user has the option to deny your app any scopes you have requested. If they deny your app, they are redirected back to your
redirect_url
with anerror
parameter. -
If the user accepts your app, they are redirected back to your
redirect_uri
with acode
andstate
query parameter (eg. http://yourredirect.com?code=abc&state=xyz).- You must validate that the
state
matches your state from Step 1. - If the state is valid, you can exchange your code and
redirect_uri
for an access token.
- You must validate that the
// `redirect_uri` must be provided, and must match your configured URI.
client.accessToken(code, redirect_uri, function (err, response) {
if (err) {
return response.end("error\n" + err);
}
if (response.access_token) {
// At this state the code has been successfully exchanged for an
// access token
client.setAccessToken(response.access_token);
// Other useful information is included alongside the access token,
// which you can dump out to see, or visit our API documentation.
//
// We include the final scopes granted to the token. This is
// important because the user, or API, might revoke scopes during
// the authentication process.
var scopes = response.scope;
// We also include the full user response of the newly
// authenticated user.
var user = response.user;
}
});
The API library has a request
method that takes two parameters.
This object contains your request information in key/value pairs.
Name | Type | Description |
---|---|---|
method |
string | The HTTP method (e.g.: GET ) |
path |
string | The URL path (e.g.: /users/dashron ) |
query |
string | An object containing all of your parameters (for example, {"per_page": 5, "filter": "featured"} . ) |
headers |
object | An object containing all additional headers (for example, {"If-Modified-Since": "Mon, 03 Mar 2014 16:29:37 -0500"} |
This function is called once the upload process is complete.
Name | Type | Description |
---|---|---|
error |
error | If this is provided, it means the request failed. The other parameters may or may not contain additional information. Check the status code to understand exactly what error you have encountered. |
body |
object | The parsed request body. All responses are JSON, so we parse this for you and give you the result. |
status_code |
number | The HTTP status code of the response. This partially informs you about the success of your API request. |
headers |
object | An object containing all of the response headers. |
client.request(/*options*/{
// This is the path for the videos contained within the staff picks
// channels
path: '/channels/staffpicks/videos',
// This adds the parameters to request page two, and 10 items per
// page
query: {
page: 2,
per_page: 10,
fields: 'uri,name,description,duration,created_time,modified_time'
}
}, /*callback*/function (error, body, status_code, headers) {
if (error) {
console.log('error');
console.log(error);
} else {
console.log('body');
console.log(body);
}
console.log('status code');
console.log(status_code);
console.log('headers');
console.log(headers);
});
You should ensure to set JSON filter fields on all requests to ensure a steady and higher X-RateLimit-Limit
.
There is an open issue#51 to reflect that the current documentation states that POST, PUT, DELETE, and PATCH requests must provide parameters in the body, but this doesn't work with the JSON filter request. Here is an example of a properly formed DELETE request:
client.request(/*options*/{
method: 'DELETE',
path: '/channels/12345?fields=uri'
}, /*callback*/function (error, body, status_code, headers) {
if (error) {
console.log('error');
console.log(error);
} else {
console.log('body');
console.log(body);
}
console.log('status code');
console.log(status_code);
console.log('headers');
console.log(headers);
});
The API library has an upload
method that takes five parameters.
Internally, this library executes a tus
upload approach and sends a file to the server with the tus upload protocol and tus-js-client.
Name | Type | Description |
---|---|---|
path |
string | Full path to the upload file on the local system. |
params |
object (optional) | Parameters to send when creating a new video (name, privacy restrictions, and so on). See the /me/videos documentation for supported parameters. |
completeCallback |
function | A callback that is executed when the upload is complete. It has one argument, uri , that is the /videos/:id URI for your uploaded video. |
progressCallback |
function | A callback that is executed periodically during file uploading. This callback receives two parameters, bytesUploaded and bytesTotal . You can use this to determine how much of a percentage has been uploaded to the Vimeo servers. |
errorCallback |
function | A callback that is executed when any errors happen during the upload process. It has one argument, err , that is a string error message. |
client.upload(
'/home/aaron/Downloads/ada.mp4',
function (uri) {
console.log('File upload completed. Your Vimeo URI is:', uri)
},
function (bytesUploaded, bytesTotal) {
var percentage = (bytesUploaded / bytesTotal * 100).toFixed(2)
console.log(bytesUploaded, bytesTotal, percentage + '%')
},
function (error) {
console.log('Failed because: ' + error)
}
)
To replace the source file of a video, call the replace
method. It accepts five parameters:
Name | Type | Description |
---|---|---|
path |
string | Full path to the upload file on the local system. |
videoUri |
string | Video URI of the video file to replace. |
completeCallback |
function | A callback that is executed when the upload is complete. It has one argument, uri , that is the /videos/:id URI for your uploaded video. |
progressCallback |
function | A callback that is executed periodically during file uploading. This callback receives two parameters, bytesUploaded and bytesTotal . You can use this to determine how much of a percentage has been uploaded to the Vimeo servers. |
errorCallback |
function | A callback that is executed when any errors happen during the upload process. It has one argument, err , that will be a string error message. |
client.upload(
'/home/aaron/Downloads/ada-v2.mp4',
'/videos/15'
function (uri) {
console.log('File upload completed. Your Vimeo URI is:', uri)
},
function (bytesUploaded, bytesTotal) {
var percentage = (bytesUploaded / bytesTotal * 100).toFixed(2)
console.log(bytesUploaded, bytesTotal, percentage + '%')
},
function (error) {
console.log('Failed because: ' + error)
}
)
If you have any questions or problems, create a ticket or contact us.
To see the contributors, please visit the contributors graph.