Skip to content

Latest commit

 

History

History
242 lines (153 loc) · 10.2 KB

index.md

File metadata and controls

242 lines (153 loc) · 10.2 KB
Raw
layout title
default

Greetings, programs

Spacecat
1) Videos!
Read and write videos to VHX accounts, including sharing, liking, queueing and more.
2) Make Playlists
Organize videos into fun, continous-play video mixtapes, with support for animated GIF album art. [Here's an example](http://community.vhx.tv/casey/music-videos)
3) Embeddable Player
Just send our player a list of URLs for back-to-back playback experience. [Try it out](/video-player.html)
 

The VHX API and this documentation are currently in BETA. Please contact us via email or through our contact form with any issues or suggestions. OAuth2 support coming soon.

For some demos of what you can do with the VHX embeddable player and API visit Music Video Genome or showmenonstop.com

Let's get started

Demo apps and code samples

Just show me the 'curl' examples

Get all the videos shared by @staff:

curl http://api.vhx.tv/staff/shared.json

Get queued videos for the current user, authenticating as @jamiew -- api_token is available at vhx.tv/settings

curl http://api.vhx.tv/queue.json?login=jamiew&api_token=[SECRET]

Add http://vimeo.com/123456 to my queue, authenticating as @jamiew:

curl -d url=http://vimeo.com/123456 \
  -d login=jamiew \
  -d api_token=[SECRET] \
  http://api.vhx.tv/videos/queue.json

Share that same video, with a simple urlencoded comment. First video posted on Vimeo!:

curl -d url=http://vimeo.com/2 \
    -d login=jamiew \
    -d api_token=SECRET \
    -d comment=First+video+posted+on+Vimeo \
    http://api.vhx.tv/videos/share.json

General API info

  • Response formats: .json and .xml

  • We follow REST conventions as much as possible, using nested resource URLs and HTTP verbs for actions:

    • GET → fetch things
    • POST → create things
    • PUT → update things
    • DELETE → remove things

  • Common (but optional) parameters:

    • url -- all video-adding methods (share, queue, like, etc.) accept either an ?id parameter or a ?url paramter. This lets you easily specify a native VHX video ID or an arbitrary YouTube or Vimeo URL
    • page -- currently all paged result sets contain 50 results
    • callback -- optional parameter for JSON requests to wrap the data in a javascript callback (JSONp)
    • app_id -- a simple string identifying your application, e.g. "my_new_vidrecommender"

  • Authentication parameters:

User Authentication

We currently use simple API tokens to authenticate you as a user. Just specify "login" and "api_token" parameters with your requests:

We plan to add full OAuth2 support soon.

App Registration

We don't currently require you to formally register your app, but request that you pass an identifying string as an app_id parameter, especially if you are on a shared IP (e.g. a hackathon). In the future this will grant you increased rate limits as well.

curl http://api.vhx.tv/jamiew.json?app_id=testbed_app

API Methods

Video Actions

auth required

  POST http://api.vhx.tv/videos/queue.json?url=http://vimeo.com/2
DELETE http://api.vhx.tv/videos/unqueue.json?url=http://vimeo.com/2

  POST http://api.vhx.tv/videos/share.json?url=http://vimeo.com/2&comment=Yay+this+is+great
DELETE http://api.vhx.tv/videos/unshare.json?url=http://vimeo.com/2

  POST http://api.vhx.tv/videos/like.json?url=http://vimeo.com/2
DELETE http://api.vhx.tv/videos/unlike.json?url=http://vimeo.com/2

Your Videos

auth required

GET http://api.vhx.tv/shared.json
GET http://api.vhx.tv/queued.json
GET http://api.vhx.tv/liked.json
GET http://api.vhx.tv/watched.json

Other People's Videos

public

GET http://api.vhx.tv/jamiew.json
GET http://api.vhx.tv/jamiew/shared.json
GET http://api.vhx.tv/jamiew/queued.json
GET http://api.vhx.tv/jamiew/liked.json

(everything except 'watched')

Playlists

A video mixtape, composed of a list of videos with "position" attributes. Yes, we support animated GIFs!

public

GET http://api.vhx.tv/playlists.json        -- all playlists
GET http://api.vhx.tv/playlists/:id.json    -- playlist details
GET http://api.vhx.tv/:user_id/:id.json     -- alternate URL for above (e.g. /jamiew/turntablism.json)

auth required

POST http://api.vhx.tv/playlists.json       -- create playlist. attributes: title, description, image, color (ff00ff)
PUT http://api.vhx.tv/playlists/:id.json    -- update playlist's attributes

POST http://api.vhx.tv/playlists/:id/videos                 -- add a video to specified playlist (pass :url or :video_id)
DELETE http://api.vhx.tv/playlists/:id/videos/:video_id     -- remove video from playlist
PUT http://api.vhx.tv/playlists/:id/videos/:video_id/move   -- specify :position argument (starts at index 0) to change video's order

GET http://api.vhx.tv/playlists/mine.json             -- authenticating user's playlists
GET http://api.vhx.tv/videos/:id/playlists.json       -- playlists said video is present in
GET http://api.vhx.tv/videos/:id/playlists/mine.json  -- playlists by the authenticating user's that said video is in

Basic playlist API example

The rough order of operations to create a playlist are:

  • POST /playlists -- with title and optional description and image
    • store the returned id (e.g. 123) and slug (url chunk parsed from title, e.g. "my-new-playlist")
  • POST video URLs to /playlists/123
    • store the returned ids for these as well, since you can use them to delete or move the videos later
  • PUT /playlists/123/videos/456789/move -- with a 'position' parameter
  • DELETE /playlists/123/videos/456789 -- to remove it completely

The playlist is visible on vhx.tv at http://community.vhx.tv/{USERNAME}/{PLAYLIST_SLUG}

http://community.vhx.tv/playlists/123 is still a valid API resource endpoint, and if you visit it on the live site it will 301 Redirect to semantic URL.

User info & Followers

public

GET http://api.vhx.tv/jamiew.json
GET http://api.vhx.tv/jamiew/followers.json
GET http://api.vhx.tv/jamiew/following.json

auth required

  POST http://api.vhx.tv/jamiew/follow.json
DELETE http://api.vhx.tv/jamiew/unfollow.json

Service Streams

If user has linked their Facebook, Tumblr or Twitter accounts VHX will import videos shared by their friends:

auth required

GET http://api.vhx.tv/facebook.json
GET http://api.vhx.tv/twitter.json
GET http://api.vhx.tv/tumblr.json

More info

Rate Limits

Currently we allow up to 86k API requests per IP per day (approximately 1 request per second). We also throttle clients that are making requests too quickly -- more than 2 per second. The "day" windowexpires at midnight UTC each day.

If you've exceeded the rate limits you'll receive a 403 Forbidden response code.

Every API response contains the following HTTP headers to let you know about rate limits, following Twitter's API conventions:

  • X-RateLimit-Limit -- number of requests allowed during window
  • X-RateLimit-Remaining -- number of requests left in the current window
  • X-RateLimit-Reset -- unixtime when your request window we be reset

If you are rocking out and need your limits bumped don't hesitate to contact us.

Roadmap

  • OAuth2 support -- we will grandfather in apps using api_tokens
  • Client libraries: Ruby, Python, PHP, Javascript (node.js)
  • Interactive API demos, hurl-style
  • More sample code and example apps! Send us yours

Video support

  • YouTube
  • Vimeo
  • Raw video files (h264 or FLV)

We have near-term plans to add support for several other major video hosting sites. Contact us if you'd like us to support your site. Direct video file access preferred. Flash/AS3-friendly video player APIs also make us happy.

Legal

By using the VHX API, you agree to the VHX API Terms of Service.