Application Programming Interface (API)

This manual contains developer documentation for Bitcache.

To get the most of the available material, you should already be familiar with the concepts Bitcache is based upon, as well as the various frequently asked questions.

Some conventions used in this manual:

Symbol	Description
<id>	A digital fingerprint that uniquely identifies a bitstream.
<str>	An arbitrary text string.

For questions concerning the developer documentation, please write to the mailing list.

REST API

There are currently two existing open-source server implementations of the Bitcache REST API: one, bitcached, is written in Ruby and is included in the Bitcache reference implementation; the other is written in PHP and available as an add-on module for the Drupal content management framework.

Note that the question of authentication is entirely orthogonal to this API; authentication would typically be implemented using standard HTTP methods, but a cookie-based session, or indeed a publicly-available repository, is equally compatible with the REST API.

Method	Purpose
`OPTIONS /`	Discover set of valid HTTP methods for the bitstream index.
`OPTIONS /<id>`	Discover set of valid HTTP methods for a bitstream resource.
`INDEX /`	Retrieve full index of available bitstreams.
`INDEX /<str>`	Retrieve partial index of bitstreams based on `<str>`.
`GET /`	Equivalent to `INDEX /`.
`GET /<id>`	Download bitstream identified by `<id>`.
`HEAD /`	Like `GET /` but omit the response body.
`HEAD /<id>`	Like `GET /<id>` but omit the response body.
`POST /`	Upload bitstream.
`PUT /<id>`	Upload bitstream, with `<id>` verification.
`DELETE /<id>`	Delete bitstream identified by `<id>`.

INDEX

`INDEX /`

Retrieve full index of available bitstreams.

Not defined in RFC 2616

Header	Value
Request
Accept	MIME content type
Response
Content-Type	...

`INDEX /<str>`

Retrieve partial index of bitstreams based on <str>.

Not defined in RFC 2616

Header	Value
Request
No request headers.
Response
Accept	"OPTIONS, GET, HEAD, PUT, DELETE"

Software support

Application	Status
Drupal server	Supported.

OPTIONS

`OPTIONS /`

Discover set of valid HTTP methods for the bitstream index.

Defined in RFC 2616 §9.2

Header	Value
Request
No request headers.
Response
Accept	"OPTIONS, GET, POST"

`OPTIONS /<id>`

Discover set of valid HTTP methods for a bitstream resource identified by <id>.

Defined in RFC 2616 §9.2

Header	Value
Request
No request headers.
Response
Accept	"OPTIONS, GET, HEAD, PUT, DELETE"

Software support

Application	Status
Drupal server	Supported.

HEAD

`HEAD /`

Like INDEX /, but omit the response body.

Defined in RFC 2616 §9.4

`HEAD /<id>`

Like GET /<id> but omit the response body.

Defined in RFC 2616 §9.4

Header	Value
Request
Response
Accept-Ranges	"bytes"
ETag
Content-SHA1
Content-Type
Content-Length

Software support

Application	Status
Drupal server	Supported.

GET

`GET /`

Equivalent to INDEX /.

Defined in RFC 2616 §9.3

`GET /<id>`

Download bitstream identified by <id>.

Defined in RFC 2616 §9.3

Header	Value
Request
Response
Accept-Ranges	"bytes"
ETag
Content-SHA1
Content-Type
Content-Length

Software support

Application	Status
Drupal server	Supported.

POST

`POST /`

Upload bitstream.

Defined in RFC 2616 §9.5

Header	Value
Request
Response

Software support

Application	Status
Drupal server	Supported.

PUT

`PUT /<id>`

Upload bitstream, with <id> verification.

Defined in RFC 2616 §9.6

Header	Value
Request
Response

Software support

Application	Status
Drupal server	Supported.

DELETE

`DELETE /<id>`

Delete bitstream identified by <id>.

Defined in RFC 2616 §9.6

Header	Value
Request
Response

Software support

Application	Status
Drupal server	Supported.

PHP API

The PHP API is developed as part of the Bitcache for Drupal implementation.

PHP 5.2 with SPL is required to use this API.

Bitcache_Repository

Definition:

interface Bitcache_Repository extends Countable

File:

bitcache.inc

Bitcache_Server

Definition:

class Bitcache_Server

Implements a Bitcache REST API-compliant HTTP server.

File:

bitcache.inc

Bitcache_Stream

Definition:

class Bitcache_Stream

File:

bitcache.inc

Drupal bitstream API

Note that any functions that are not documented here should be considered to be internal and subject to change without notice.

Additional developer documentation may also be available in the Drupal Handbook.

bitcache_delete()

Definition:

bitcache_delete(string $id)

File:

modules/bitcache/bitcache.module

bitcache_exists()

Definition:

bitcache_exists(string $id)

File:

modules/bitcache/bitcache.module

bitcache_get()

Definition:

bitcache_get(string $id)

File:

modules/bitcache/bitcache.module

bitcache_get_contents()

Definition:

bitcache_get_contents(string $id)

File:

modules/bitcache/bitcache.module

bitcache_get_path()

Definition:

bitcache_get_path(string $id)

File:

modules/bitcache/bitcache.module

bitcache_get_size()

Definition:

bitcache_get_size(string $id)

File:

modules/bitcache/bitcache.module

bitcache_get_stream()

Definition:

bitcache_get_stream(string $id)

File:

modules/bitcache/bitcache.module

bitcache_get_type()

Definition:

bitcache_get_type(string $id)

File:

modules/bitcache/bitcache.module

bitcache_id()

Definition:

bitcache_id(mixed $data)

File:

modules/bitcache/bitcache.module

bitcache_l()

Definition:

bitcache_l($text, $id, array $options = array('absolute' => TRUE))

File:

modules/bitcache/bitcache.module

bitcache_put()

Definition:

bitcache_put(string $id, mixed $data)

File:

modules/bitcache/bitcache.module

bitcache_put_file()

Definition:

bitcache_put_file(string $id, string $filepath, bool $move = FALSE)

File:

modules/bitcache/bitcache.module

bitcache_resolve_id()

Definition:

bitcache_resolve_id(string $id, array $options = array('absolute' => TRUE))

File:

modules/bitcache/bitcache.module

bitcache_resolve_uri()

Definition:

bitcache_resolve_uri(string $uri, array $options = array('absolute' => TRUE))

File:

modules/bitcache/bitcache.module

bitcache_uri()

Definition:

bitcache_uri(string $id)

File:

modules/bitcache/bitcache.module

bitcache_uri_to_id()

Definition:

bitcache_uri_to_id(string $uri)

File:

modules/bitcache/bitcache.module

Drupal repository API

Note that any functions that are not documented here should be considered to be internal and subject to change without notice.

Additional developer documentation may also be available in the Drupal Handbook.

bitcache_create_repository()

Definition:

bitcache_create_repository(string $name, array $options = array())

File:

modules/bitcache/bitcache.module

bitcache_delete_repository()

Definition:

bitcache_delete_repository(string $name, array $options = array())

File:

modules/bitcache/bitcache.module

bitcache_get_adapter()

Definition:

bitcache_get_adapter(string $name)

File:

modules/bitcache/bitcache.module

bitcache_get_adapters()

Definition:

bitcache_get_adapters()

Returns information on the available storage adapters (repository backends).

File:

modules/bitcache/bitcache.module

bitcache_get_algorithms()

Definition:

bitcache_get_algorithms(string $function)

Returns information on available cryptographic algorithms.

File:

modules/bitcache/bitcache.module

bitcache_get_modules()

Definition:

bitcache_get_modules(string $op = NULL)

Returns information about modules that implement hook_bitcache().

File:

modules/bitcache/bitcache.module

bitcache_get_repositories()

Definition:

bitcache_get_repositories(string $op = 'settings')

File:

modules/bitcache/bitcache.module

bitcache_get_repository()

Definition:

Bitcache_Repository bitcache_get_repository(string $name = 'bitcache')

File:

modules/bitcache/bitcache.module

bitcache_get_repository_count()

Definition:

int bitcache_get_repository_count(string $name = NULL)

File:

modules/bitcache/bitcache.module

bitcache_get_repository_size()

Definition:

int bitcache_get_repository_size(string $name = NULL)

File:

modules/bitcache/bitcache.module

bitcache_get_schema()

Definition:

bitcache_get_schema(string $table = BITCACHE_TABLE_DEFAULT, bool $rebuild = FALSE)

File:

modules/bitcache/bitcache.module

bitcache_get_tables()

Definition:

bitcache_get_tables()

File:

modules/bitcache/bitcache.module

bitcache_rename_repository()

Definition:

bitcache_rename_repository(string $old_name, string $new_name, array $options = array())

File:

modules/bitcache/bitcache.module

bitcache_update_repository()

Definition:

bitcache_update_repository(string $name, array $options = array())

File:

modules/bitcache/bitcache.module

bitcache_use_repository()

Definition:

bitcache_use_repository(string $name = NULL)

Limits future queries and operations to a particular repository.

File:

modules/bitcache/bitcache.module

Drupal hooks

The Bitcache module exposes a hook_bitcache() hook that third-party extension modules can implement to provide extended functionality.

For an example of implementing this hook, see the File Framework module.

Additional developer documentation may also be available in the Drupal Handbook.

hook_bitcache()

Definition:

hook_bitcache($op, $id, &$stream = NULL)

Allows modules to take action when bitstreams are created or deleted, to determine fine-grained bitstream download access rights for individual users, and to define additional HTTP headers for bitstream downloads.

This is essentially an extended analog of the hook_file_download() core hook.

Example of usage:

/**
 * Implementation of hook_bitcache().
 */
function mymodule_bitcache($op, $id, &$stream = NULL) {
  switch ($op) {
    case 'insert':
      // A new bitstream was uploaded
      break;

    case 'delete':
      // An existing bitstream was deleted
      break;

    case 'access':
      // Should the current user be allowed to access the given bitstream?
      return node_access('view', node_load($_GET['nid']));

    case 'download':
      // Determine additional HTTP headers for the bitstream download
      $node = node_load($_GET['nid']);
      return array(
        'Content-Disposition' => 'attachment; filename='. $node->title,
        'Last-Modified' => gmdate('D, d M Y H:i:s', $node->changed) .' GMT',
      );
  }
}

File:

modules/bitcache/bitcache.module

hook_bitcache_adapters()

Definition:

hook_bitcache_adapters()

File:

modules/bitcache/bitcache.module

hook_bitcache_algorithms()

Definition:

hook_bitcache_algorithms(string $op)

File:

modules/bitcache/bitcache.module