cacaoweb HTTP API

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 script tag.

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 curl at 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:

    http://localhost:4001/[name_of_the_api_function]
    or
    http://127.0.0.1:4001/[name_of_the_api_function]

    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

“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

  • /upload?filepath=[PATH_TO_THE_FILE]

    where [PATH_TO_THE_FILE] is the full path to the local file you want to upload

    To upload a local file.

    Example:

    curl http://localhost:4001/upload?filepath=/home/robert/movies/Avatar.720p.BDRip.mp4

  • /uploads

    this gives you a list of current uploads in XML format

    To get the current list of uploads and their progress:

  • remove an upload:

    /removeupload?f=[MD5_OF_THE_FILE]

    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.

    Example:

    curl http://localhost:4001/removeupload?f=c9cd88165575ca8cb8da5b963e81e6ec

Functions for Paid Files upload

  • /upload?filepath=[PATH_TO_THE_FILE]&restricted=[RESTRICTED]&previewallowed=[PREVIEWALLOWED]

    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)

    Example:

    curl http://localhost:4001/upload?filepath=/home/robert/movies/Avatar.720p.BDRip.mp4&restricted=true&previewallowed=true

    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.

Other Functions

  • /filemetadata?f=[MD5_OF_THE_FILE]

    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.

  • /downloads

    To get the list of current downloads in XML format

  • /digest

    To get the md5 of the cacaoweb executable

  • /version

    To get the version of the cacaoweb instance

  • /exit

    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:

curl http://user.cacaoweb.org/upload?username=[YOUR_USERNAME]&password=[YOUR_PASSWORD]&fileid=[THE_FILE_MD5]&title=[THE_FILE_TITLE]

Once a file has been added to your files manager, you can add more metadata within your files manager.