Public json-api to interface with videopong.net

1) General notes

this is all working draft and subject to changes

General Implementation Notes

implementation tries to follow mostly http://jsonapi.org/format/ (but not the required mime-type) and uses CORS https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS so you can use it cross-domain inside browser. no api-key is needed as the api just gives a json with metainformation plus the urls of the mp4 and thumbs/bigs that are public available on videopong.net anyway. so the movie.* are not full resolution but 640x480 or smaller if stated below. later when a login mechanism is implemented there might be a possiblity to get also the original file (but this might be of any format mov/avi/… as it was uploaded) or maybe a fullscale converted mp4, and is accounted on the share-ratio of the user (means user needs to have reviewed uploads and good share-ratio).

License and usage agreement:

on using this api you agree on:

  1. the application using this api must be public accessible for everyone free of charge and the link needs to be submitted to api@videopong.net so we can build up a registry of all tools using videopong. if you want to charge the users or freemium please get in contact with us first so we can discuss an exception.
  2. content must not be cached, as we need to be able to take copyright violating content offline. there might be still some situation where caching is mandatory but such cases need to be discussed with us first please: api@videopong.net

Sample Urls inside json answers like:

https://www.videopong.net/pics/0cijjx237ht/big1.jpg (big[1-3].jpg)

https://www.videopong.net/pics/0cijjx237ht/thumb1.jpg (thumb[1-3].jpg)

https://www.videopong.net/pics/0cijjx237ht/thumb.gif (gif animation of thumbs)

https://www.videopong.net/clip/view/0cijjx237ht/movie.mp4 (640x480 h264 preview)

https://www.videopong.net/clip/view/0cijjx237ht/movie.gif (320x240-12fps gif preview)

...

Support

support to this api is possibly given via api@videopong.net

please write your comments and ideas to this api to api@videopong.net and maybe join discussions on the videopong users group.


2) implemented API Calls

2.1) Error Numbers

0 : ok

1 : general error: use the errorstring

2 : not logged in: use the “login” api and check with “login/ami”

3 : upload failed: show the errorstring

2.2) Stats

use this to initialize your application, get some basic information, … generic and also videopong-specific

https://www.videopong.net/api/stats

{

    "status": {

            "error": 0,

            "errorstring": "ok"

    },

    "data": {

            "service_name": "videopong",

            "service_status": "0",

            "service_news": "web api to interact with videopong for applications",

            "service_description": "footage exchange platform for (live-)videoartists",

            "url_front": "http:\/\/www.videopong.net",

            "url_logo": "http:\/\/www.videopong.net\/customer\/vp\/media\/logo-beta.png",

            "url_help": "http:\/\/www.videopong.net\/static\/faq",

            "url_about": "http:\/\/www.videopong.net\/static\/concept",

            "videopong": {

                    "total_clips": "20389",

                    "total_users": "1789"

            }

    }

}

2.3) Cliplists:

https://www.videopong.net/api/clip/test                                   

returns a cliplist of: 1 testclip

https://www.videopong.net/api/clip/random/<number>                   

returns a cliplist of: get <number> random clips (max 50, default 1 if not specified)

https://www.videopong.net/api/clip/<clipid>                           

returns a cliplist of: 1 clip

https://www.videopong.net/api/clip/search/<needle>/<offset>/<number>    

returns a cliplist of: searches for <needle> and shows <number> clips starting with offset of <offset> clips

default <offset> is 0 and default <number> is 1 (maximum <number> is 50)

if you get OK with no results check your offset

https://www.videopong.net/api/clip/last                          

returns a cliplist of: get a maximum of 3 last viewed clips if user has been viewing clips before on
        videopong or any js-app that uses this api

https://www.videopong.net/api/user/uploads
        returns a cliplist of: only own uploads (if user is logged in: otherwise error=1)

https:/www./videopong.net/api/user/downloads
        returns a cliplist of: only own downloads (if user is logged in: otherwise error=1)

https://www.videopong.net/api/user/<userid>/uploads

        returns a cliplist of: only uploads of user <userid>. instead of setting own userid just use “me”

https://www.videopong.net/api/user/<userid>/downloads
        returns a cliplist of: only downloads of user <userid>. instead of setting own userid just use “me”

example answer for a cliplist (with 1 result,... the-data array would contain more when more results)

{

    "status": {

            "error": 0,

            "errorstring": "ok"

    },

    "data": [

            [{

                    "id": "0cijjx237ht",

                    "title": "test file",

                     "reputation": 1,

                    "thumbs_up": 1,

                    "thumbs_down": 0,

                    "views": "281",

                    "downloads": "19",

                    "duration": "10",

                    "framerate": "25",

                    "resolution": "640x480",

                    "upload_date": "2008-05-15 14:25:53",

                    "license": "byncsa",

                    "url_thumb": "http:\/\/www.videopong.net\/pics\/0cijjx237ht\/thumb1.jpg",

                    "url_thumb_gif": "http:\/\/www.videopong.net\/pics\/0cijjx237ht\/thumb.gif",

                    "url_big": "http:\/\/www.videopong.net\/pics\/0cijjx237ht\/big1.jpg",

                    "url_preview_mp4": "http:\/\/www.videopong.net\/clip\/view\/0cijjx237ht\/movie.mp4",

                    "url_preview_gif": "http:\/\/www.videopong.net\/clip\/view\/0cijjx237ht\/movie.gif",

                    "url_download": "http:\/\/www.videopong.net\/clip\/download\/0cijjx237ht\/vp-1-0cijjx237ht-bla.mov",

                    "url_videopong": "http:\/\/www.videopong.net\/clip\/detail\/0cijjx237ht"

            }, {

                    "name": "mr.shintla",

                    "userid": "1",

                    "url_videopong": "http:\/\/www.videopong.net\/user\/1\/mr.shintla",

                    "url_api": "http:\/\/www.videopong.net\/api\/user\/1"

            }]

    ],

    "count": 1

}

if status->error is not 0:

use status->errorstring as result to the user. might contain html-tags like <a> and <img>

<count> shows always the number of total results. important for searches where results are paginagted...

2.4) User Login & Detail

https://www.videopong.net/api/login

use it as popup/iframe that user can authenticate themself on videopong.net

window.open("https://www.videopong.net/api/login", "videopong login","status=0,menubar=0,titlebar=0,toolbar=0,width=350,height=350");

        additional GET-parameters to overwrite default-colors possible:

        example: .../api/login/?colorbg=ff0000&colorfg=00ff00&colorbg2=ff00ff

attention: colors are NOT saved in a session or such, so you need to set them on each call

https://www.videopong.net/api/login/ami

returns logged_in==true if a user is logged in. plus some more details

{

    "status": {

            "error": 0,

            "errorstring": "ok"

    },

    "data": {

            "logged_in": true,

            "userid": "<userid>",

             "unfinished_uploads": ["0f7kgcqx2mz", "0f7nypho6py"],

            "unread_messages": 0

    }

}

if “false” the userid is set to 0. please do redirect/open as popup the user to the login screen with this api call:

https://www.videopong.net/api/login

<userid> : integer

unfinished_uploads holds the ids of the clips that need to be finished to be public available. use the /api/clip/<clipid> to get information about this upload. or open an iframe/popup on /api/upload/finish/<clipid> to allow the user to finish his upload (see detail instructions in chapter 2.5 )

https://www.videopong.net/api/user/<userid>/detail

        returns detail information to a user of a given userid

{

    "status": {

            "error": 0,

            "errorstring": "ok"

    },

    "data": {

            "name": "mr.shintla",

            "url_videopong": "http:\/\/dev.videopong.net\/user\/1\/mr.shintla",

            "reputation": 36,

            "thumbs_up": 39,

            "thumsb_down": 3,

            "url": "http:\/\/www.videokultur.ch",

            "crew_name": "bildstörung \/ videokultur",

            "crew_url": "http:\/\/www.bildstoerung.ch",

            "social_facebook": "bildstoerung.vjs",

            "social_twitter": "videopong",

            "social_google": ""

    }

}

2.5) Uploads

first you need to check if the user is logged in (see /api/login/ami)

then post your file inside POST-var “files[0]” to

https://www.videopong.net/api/upload

answers with error = 2 mean the user is not logged in… use the api to do so

answers with error = 3 are failed uploads. show the errorstring to the user

example of html-form:

<form method="post" action="https://www.videopong.net/api/upload" enctype="multipart/form-data">

<input name="files[0]" type="file" />

<input type="submit" value="post clip to api" />

</form>

example of successful upload

{

    "status": {

            "error": 0,

            "errorstring": "ok"

    },

    "data": {

            "id": "0f7jcmi3tod",

            "url_videopong": "http:\/\/www.videopong.net\/clip\/detail\/0f7jcmi3tod",

            "url_edit": "http:\/\/www.videopong.net\/api\/upload\/finish\/0f7jcmi3tod"

    }

}

the clip is not published until all meta informations are entered (use url_edit from answer) :

https://www.videopong.net/api/upload/finish/<clipid>

so open this url in an iframe/window so the user can finalize the upload… see documentation below

        

optionaly the user sees all unfinished uploads on videopong.net and could get asked the number of unfinished uploads with /api/login/ami

https://www.videopong.net/api/upload/finish/<clipid>

        open in a popup/iframe to let users finish their uploads. this needs to be done to get a clip public available on videopong. the list of open ids is inside the /api/login/ami in unifinished_uploads

window.open("https://www.videopong.net/api/upload/finish/<clipid>", "videopong upload","status=0,menubar=0,titlebar=0,toolbar=0,width=1000,height=320");

        additional GET-parameters to overwrite default-colors possible:

        example: .../api/upload/finish/<clipid>/?colorbg=ff0000&colorfg=00ff00&colorbg2=ff00ff

attention: colors are NOT saved in a session or such, so you need to set them on each call

3) Upcoming Implementations / Planned Features

https://www.videopong.net/api/rate/<clipid>/up|down

up-/down-voting for logged-in users

https://www.videopong.net/api/playlist/….  (get/create/update|overwrite/add/publish/…)

people use it? maybe directly from vj-tools?

https://www.videopong.net/api/clip/newest/<offset>/<x>            

newest <x> clips starting with offset of <offset> clips

https://www.videopong.net/api/clip/toprated/<offset>/<x>           

toprated <x> clips starting with offset of <offset> clips

https://www.videopong.net/api/clip/lowestviews/<offset>/<x>    

clips with lowest views: <x> clips starting with offset of <offset> clips

4) who uses it

please let me know where you use it here: api@videopong.net

5) more ressources

some tutorials. let me know if you do something yourself: api@videopong.net

6) more Ideas & notes

proposed:

under consideration but declined:

own notes: