Methods

Available methods

Currently not used by any API calls!

  • blockhash using the algorithm defined in the (blockhash RFC)[https://github.com/commonsmachinery/blockhash-rfc] (for images)
  • x-bh-video using the experimental blockhash algorithm for videos from (the forked blockhash repository)[https://github.com/jonasob/blockhash] (or videos)

APIs

Registered APIs

Currently not used!

  • http://elog.io/ for works conforming to the (Elog.io API)[http://docs.cmcatalog.apiary.io/] using https://catalog.elog.io/ as its endpoint.

Response status codes

Success

Successes differ from errors in that their body may not be a simple response object with a code and a message. The headers however are consistent across all calls:

  • GET return 200 OK on success,

Redirect

The API calls that return a random work will return a redirect to a URL with the random work.

Status: 303 See Other Location: http://example.endpoint.io/works/28353

Error

Error responses are simply returning standard HTTP error codes along with some additional information:

  • The error code is sent back as a status header,
  • The body includes an object describing both the code and message (for debugging and/or display purposes),

For a call with an invalid hash format for instance:

Status: 400 Bad Request hash must be a 256-bit hexadecimal encoded value

GET /random Redirect to a random work record

To get a feel for the information in the Videorooter database, or to just get some random information for testing purposes, you can use this method to get a random work. The method will lookup a random work in the database and return a Location header to redirect the client to the random work.

Request

  • :type (string) either video or image (default: both)

Response

Status: 303 See Other ```Location: http://example.endpoint.io/work/3434’’’

For errors responses, see the response status codes documentation.

GET /works/<id> Get the metadata associated with a work

This is a compatibility call conforming to the http://docs.cmcatalog.apiary.io/. It queries the database for a particular work by its identifier and returns the known metadata about the work. This information will conform to the data package format which is based on the W3C Ontology for media resources.

Response

Sends back information with annotations.

Status: 200 OK { "public" : "true", "description" : "Script logo for athletics at Elon University.", "id" : 6968, "annotations" : [ { "language" : "en", "titleLabel" : "Elon Phoenix wordmark", "propertyName" : "title" }, { "identifierLink" : "https://commons.wikimedia.org/wiki/File:Elon Phoeni x wordmark.png", "propertyName" : "identifier" }, { "propertyName" : "locator", "locatorLink" : "https://upload.wikimedia.org/wikipedia/commons/3/31/El on_Phoenix_wordmark.png" }, { "propertName" : "policy", "typeLink" : "http://www.w3.org/1999/xhtml/vocab#license", "typeLabel" : "license", "statementLabel" : "Public domain" }, { "propertyName" : "collection", "collectionLink" : "http://commons.wikimedia.org" }, { "creatorLabel" : "Elon University Athletics", "propertyName" : "creator" }, { "holderLabel" : "Elon University Athletics", "propertyName" : "copyright" } ], "href" : "http://devc.commonsmachinery.se:8080/works/6968", "media" : [ { "id" : 6968, "href" : "http://devc.commonsmachinery.se:8080/works/6968/media" } : ], "added_at" : "2015-02-21T11:11:12.685Z", "owner" : { "org" : { "href" : "http://example.com", "id" : 1 } } }

For errors responses, see the response status codes documentation.

GET /works/<id>/media Get the media associated with a work

This is a compatibility call conforming to the http://docs.cmcatalog.apiary.io/. It queries the database for a particular work by its identifier and returns the media (source images) associated with it.

Response

Sends back information with a location annotation giving the link to the source work.

Status: 200 OK { "annotations": [{ "property": { "propertyName": "locator", "locatorLink": "https://example.image.io/image.png" } }], "href": "http://example.endpoint.io/works/3948734/media", "id": 3948734 }

For errors responses, see the response status codes documentation.

GET /videorooter/works/<id> Get the metadata associated with a work

This call queries the database for a particular work by its identifier and returns the known metadata about the work. This information is in a simplified W3C Ontology for media resources format and uses similar naming but different style of presenting the information.

Response

Sends back information with annotations.

Status: 200 OK { "description" : "Script logo for athletics at Elon University.", "id" : 6968, "annotations" : { "title" : "Elon Phoenix wordmark", "identifier" : "https://commons.wikimedia.org/wiki/File:Elon Phoenix wordmark.png", "locator" : "https://upload.wikimedia.org/wikipedia/commons/3/31/Elon_Phoenix_wordmark.png", "policy" : "http://creativecommons.org/by-sa/3.0", "collection" : "http://commons.wikimedia.org" "creator" : "Elon University Athletics", } "href" : "http://devc.commonsmachinery.se:8080/videorooter/works/6968", "media" : [ { "id" : 6968, "href" : "http://devc.commonsmachinery.se:8080/videorooter/works/6968/media" } : ] }

For errors responses, see the response status codes documentation.

GET /videorooter/works/<id>/media Get the media associated with a work

This call queries the database for a particular work by its identifier and returns the media (source images) associated with it.

Response

Sends back information with a location annotation giving the link to the source work.

Status: 200 OK { "locator": "https://example.image.io/image.png", "href": "http://example.endpoint.io/works/3948734/media", "id": 3948734, "identifiers": [ "http://sample/hash/2/38763q4420834", "http://sample/hash/1/23o34934", ] }

For errors responses, see the response status codes documentation.

POST /videorooter/video Submit a video to be processed / looked up

This is part of a set of API calls which are specific for the Videorooter project and used internally by its website. It’s possible to use these calls externally too, but the results may vary and change frequently.

This call sends a file to the Videorooter backend to be queried for in the database. The results are not immediately returned. Rather, this call returns a process identifier which is randomly selected. Subsequent calls shall be made to the /videorooter/results method to get the actual results once processing has completed. This may take several minutes.

If an email address is provided, an email will be generated and sent to this address once processing has completed.

Here’s an example of how you could manually invoke this method:

$ curl -F “email=youremail” \ -F “file=@/path/to/file.mp4” \ http://devc.commonsmachinery.se:8080/videorooter/video

Request

  • :email (string, optional) is the email address of the user
  • :file (file) is the contents of the file to query for

Response

Returns a process identifier which can be used for subsequent calls.

Status: 200 OK { "process_id": "c82b103606ba83a3c75819a6301a7417" }

For errors responses, see the response status codes documentation.

GET /videorooter/results/<process_id> Gets information about a previous search

This is part of a set of API calls which are specific for the Videorooter project and used internally by its website. It’s possible to use these calls externally too, but the results may vary and change frequently.

This call inquires about the status of a previous search which has been made. It returns either a status code of 202 if the search has not yet been completed, or a list of results.

Response

Sends back a collection of matching works. The reference returned is a URI which can be used to further query the resource for additional information about the work.

Status: 200 OK [ { "href": "http://example.endpoint.io/works/5396e592d7d163613d7321ee" "distance": 2 }, { "href": "http://example.endpoint.io/works/d7321ee5396e592d7d163613" "distance": 8 } ]

For errors responses, see the response status codes documentation.

GET /lookup/video Lookup a video by its calculated hash

This is an experimental call to look up a video by its blockhash. The call conforms to the same specification as /lookup/hash, namely the http://docs.cmcatalog.apiary.io/. It allows you to lookup videos based on an experimental https://github.com/commonsmachinery/blockhash-rfc algorithm which is implemented in https://github.com/jonasob/blockhash.

The maximum hash distance is controlled by the server and cannot be increased by the client. It may however be decreased. Currently the maximum hash distance is 40.

Request

  • :hash (string) is the calculated hash to lookup
  • :distance (number, optional) is the maximum hash distance (10 by default)

Response

Sends back a collection of matching works. The reference returned is a URI which can be used to further query the resource for additional information about the work.

Status: 200 OK [ { "href": "http://example.endpoint.io/works/5396e592d7d163613d7321ee" "distance": 2 }, { "href": "http://example.endpoint.io/works/d7321ee5396e592d7d163613" "distance": 8 } ]

For errors responses, see the response status codes documentation.

GET /lookup/uri Lookup a video by its URI

This is a dummy call to conform to the http://docs.cmcatalog.apiary.io/. It doesn’t return anything but an empty array regardless of what you give it.

Response

Status: 200 OK []

This call does not return any errors.

GET /lookup/text Lookup a work by full text search of key fields

This is an experimental call to look up a video by a full text search of title, description and credit. The call is so far using a natural language query, meaning that it interprets all fields as natural language fields and tries to do a best effort matching.

Commonly occuring words like “and”, “or”, “the”, “there”, and so on may be ignored, but more specific words like “tripod” or individual names will be acted upon.

Request

  • :q (string) is the search string

Response

Sends back a collection of matching works. The reference returned is a URI which can be used to further query the resource for additional information about the work.

Status: 200 OK [ { "href": "http://example.endpoint.io/works/5396e592d7d163613d7321ee" }, { "href": "http://example.endpoint.io/works/d7321ee5396e592d7d163613" } ]

For errors responses, see the response status codes documentation.

GET /lookup/blockhash Lookup a work by its calculated hash

This is a compatibility call conforming to the http://docs.cmcatalog.apiary.io/. It allows you to lookup images based on the https://github.com/commonsmachinery/blockhash-rfc.

The maximum hash distance is controlled by the server and cannot be increased by the client. It may however be decreased. Currently the maximum hash distance is 10.

Request

  • :hash (string) is the calculated hash to lookup
  • :distance (number, optional) is the maximum hash distance (10 by default)

Response

Sends back a collection of matching works. The reference returned is a URI which can be used to further query the resource for additional information about the work.

Status: 200 OK [ { "href": "http://example.endpoint.io/works/5396e592d7d163613d7321ee" "distance": 2 }, { "href": "http://example.endpoint.io/works/d7321ee5396e592d7d163613" "distance": 8 } ]

For errors responses, see the response status codes documentation.