CACAOWEB HTTP API REFERENCE
The cacaoweb API allows you to get control over your cacaoweb instance through HTTP calls. These calls can be made from the command line, a program, or even a webpage through the html
HOW TO CALL THE API FUNCTIONS
The API is called through http calls on the cacaoweb http server.
For example, to get the current version of the running cacaoweb instance:
$ curl http://localhost:4001/version
“curl” can be replaced by “wget” or any http-aware client. You can install curl on debian linux or derivatives by typing
apt-get install curlat a command prompt.
It can also be called within a browser by pasting the url in the address bar. We give the command on a Unix-like system, you need to adapt it if your operating system is Windows.
Throughout the API, files hosted on the cacaoweb network are referenced by an unique identifier, which is simply the MD5 digest of the file being hosted. Links are build with this ID, and every API function dealing with a particular file refers to this ID.
API functions can be called through a url like the following:
cacaoweb is the default port where it is listening to. It can be changed, see below in “Startup Parameters For Cacaoweb Instance”.
UPLOADING FILES TO CACAOWEB NETWORK
Any file can be uploaded to the cacaoweb P2P network.
Once a file is uploaded, it cannot be deleted.
There are essentially two ways to upload content on cacaoweb network:
“Direct upload” means that the file is directly uploaded from your computer to the cacaoweb network without any intermediary.
It is uploaded in p2p fashion to the cacaoweb network and thus the progress is not linear like with a standard upload to a ftp or http server.
It also takes a longer time to upload a file in p2p (twice or 3 times as long). However downloads are usually a lot faster in p2p.
Functions for Basic Usage
where [PATH_TO_THE_FILE] is the full path to the local file you want to upload
To upload a local file.
this gives you a list of current uploads in XML format
To get the current list of uploads and their progress:
remove an upload:
where [MD5_OF_THE_FILE] is the md5 of the file, given by the /uploads function.
It just stops the cacaoweb client from uploading this file and removes it from the list of current uploads.
If the file is already on the cacaoweb network (if the progress has reach 100%), the file will reachable on cacaoweb network.
Functions for Paid Files upload
To upload a local file for pay-per-download
this allows to upload a file for pay-per-view:
– you can specify “true” for the parameter “restricted” to make it a paid file
– you can specifiy “true” for the parameter “previewallowed” if you still want people to watch the first few minutes of the file for free (after that, they need to buy the file in order to continue with viewing the file)
Files uploaded as free files cannot be converted to paid files later on.
Once the file is uploaded, you need to set up the price (in the cacaoweb credits unit) people will have to pay to get it.
By default the price is 0, which means the file can be downloaded for free.
You can set up any price you want. Once a price > 0 is set up, users have to pay to access the content. You can change the price at any time.
To upload the price of your file, you need to upload it to the cacaoweb central metadata repository. The price is part of the metadata of the file, which also include the title of the file and other optional fields such as the year of release, season, episode, language, subtitles, etc.
To get the metadata of the file (XML format). This can be used to see if a link exists on the cacaoweb network, or to get the title of a file. If the file doesn’t exist on the cacaoweb network, this call returns after a few seconds and the result is empty.
To get the list of current downloads in XML format
To get the md5 of the cacaoweb executable
To get the version of the cacaoweb instance
To shut down the cacaoweb instance
UPLOADING FILES METADATA TO CACAOWEB CENTRAL REPOSITORY
You can add your files to your files manager on http://user.cacaoweb.org manually. You will presumably have uploaded these files on the cacaoweb network beforehand. Files added in the files manager but not missing in the cacaoweb network are purged on a regular basis. Use the following http call to add your files to the file manager:
Once a file has been added to your files manager, you can add more metadata within your files manager.