Web Service API Reference

The Web Service API allows developers to interact securely with their Vuzit account. You can easily upload, download, remove, and retrieve attributes about documents. All you need is a Vuzit account!

Please note that these are the raw Web Service APIs. For most common functions we have already created client libraries in your language of choice (e.g. .NET, PHP, Python, etc). Please check the developer page for the latest details on these client libraries.

• Introduction
• Documents API
• create - Upload a document
• index - Retrieve or search all documents in your account (i.e. repository search)
• show - Download and retrieve attributes about a document
• destroy - Delete a document
• Pages API
• index - Download the text of a page or set of pages.
• show - Download an image (jpg) of a page at a variety of different sizes.
• Events API
• index - Search the document analytics and behaviorial tracking database
• Authentication
• Public and Private Keys
• Generating a Timestamp
• Generating a Signature
• Example Authentication Code

Introduction

The Web Service APIs conform as much as possible to the design principles of REpresentational State Transfer (REST) using the HTTP 1.1 protocol. Each Method (e.g. create, show, and destroy). uses a corresponding HTTP Verb (e.g. GET, POST, DELETE) that is passed in with the request.

Requests

The URL of the request determines the output format (JSON or XML), and whether or not to use SSL transport layer security. All requests return a 3-character HTTP response code, and optionally return additional attributes in either XML or JSON formats.

Failure Responses

Requests to the API may fail due to an invalid signature, expired timestamp, or a number of other reasons. The format of the error response is the same for all methods, where the Vuzit error code and a description of the error are returned.

Example XML Response

412Access is denied. Invalid signature

Example JSON Response

{"err":{"code":"412","msg":"Access is denied. Invalid signature"}}

Access Control

Every document you upload to Vuzit can be displayed on a web page using your Public Key, but only on the Sites that are authorized to use your Public Key. Documents are stored with either Public or Private access control permissions. Public documents have their content stored in a public storage area that can be accessed and downloaded by anyone on the internet. Private documents can only be accessed by securely authenticating each request with a signature and timestamp [optionally] over an encrypted connection.

Documents API Methods

For all methods, the URL of the request determines the output format (JSON or XML), and whether or not to use SSL transport layer security.

create

This method will upload a new document to your Vuzit account.

Response

A successful interaction returns an HTTP response code of 201, and an XML or JSON response with the web_id of the newly created document. The web_id is a unique Vuzit identifier string that is the primary identifier for the document. The web_id is required in order to interact with the document

oc

{"document":{"web_id":"oc"}}

Responses that return errors are covered in the Failure Responses section.

Viewing Your Uploaded Documents

Uploaded documents can be managed in your Dashboard, and are ready to be integrated into web pages using the JavaScript API. The Viewer::fromId() function is used to display the document using the web_id that was returned by the create method. Example JavaScript code is available to illustrate this method to display a public document. For documents that are secure, you must send the signature and timestamp authentication parameters into the Viewer constructer.

index

This method will retrieve or search all documents in your account (i.e. repository search). A query string may be sent with the request, along with desired formatting (minimal or summary). This interface requires the authentication parameters to be specified.

Responses

A successful interaction returns an HTTP response code of 200. The XML or JSON response contains a number of attributes about the document. Responses that return errors are covered in the Failure Responses section.

Example XML Request

This returns all documents stored in the account.

<?xml version="1.0" encoding="UTF-8"?>

   
    e
  
   
    d
   
    b
  
   
    3
  
 

Example JSON Request with Search

This returns all documents stored in the account that contain the string "Vuzit ROCKS"

{
  "documents": {
    "document": [
      {
        "web_id": "e"
      }, 
      {
        "web_id": "d"
      }
    ], 
    "length": "2", 
    "output": "minimal"
  }
}

show

This method will download a document in your account, or retrieve associated information about that document.

Responses

A successful interaction returns an HTTP response code of 200. The XML or JSON response contains a number of attributes about the document, and downloaded documents return a binary stream. Responses that return errors are covered in the Failure Responses section.

Example XML Request

Note that documents where the secure flag is set require the authentication parameters.

<?xml version="1.0" encoding="UTF-8" ?>

  http://diglib.org/forums/fall2007/presentations/Payette1.pdf 
  <title>PowerPoint Presentation</title>
  8
  720
  540
  1322267
  
  1194374255
  oc
  jpg
  3

Example JSON Request

Note that documents where the secure flag is set require the authentication parameters.

{
  "document": {
    "url":"http://diglib.org/forums/fall2007/presentations/Payette1.pdf",
    "title":"PowerPoint Presentation",
    "page_count":"8",
    "width":"720",
    "height":"540",
    "file_size":"1322267",
    "subject":"",
    "modified_at":"1194374255",
    "web_id":"oc",
    "image_type":"jpg",
    "zoom_count":"3"
}

Example Download Request (Microsoft Word Document)

This is an example where a Microsoft Word document was uploaded via create, and the download_document parameter was specified as a 1 so it is available for download.

Note that documents where the secure flag is set require the authentication parameters.

Example Download Request (Generated PDF Document)

This is an example where a Microsoft Word document was uploaded via create, and the download_pdf parameter was specified as a 1 so a PDF is generated and available for download. Alternatively this will work if a PDF is uploaded via create and the download_document parameter was specified as a 1.

Note that documents where the secure flag is set require the authentication parameters. If the watermark parameter is specified, then you must specify the authentication parameters regardless of whether or not the secure flag is set.

destroy

This method will remove a document from your Vuzit account.

Responses

A successful interaction returns an HTTP response code of 200. It does not return any XML or JSON. Responses that return errors are covered in the Failure Responses section.

Pages API

The URL of the request determines the output format (JPG, JSON, or XML), and whether or not to use SSL transport layer security. Examples are given below, and more examples can be found in our Javascript code samples. This API does not contain a create or destroy method and can only be performed on the entire document using the Documents API.

index

This method returns the text that is contained on a page, and is ideal for online marketing purposes (SEO and SEM). Note that documents where the secure flag is set require the authentication parameters.

Responses

A successful interaction returns an HTTP response code of 200 with the JPEG file in the body of the message. Errors are returned as an HTTP 403 Forbidden message.

Example

show

We typically refer to the process of downloading an image from the Pages API collectively as the Image API. This method will download a page of a document at a particular zoom level. Currently Vuzit uses the JPEG file format. One of the major benefits of the Image API is that it can be used directly in an HTML <img> tag. Note that documents where the secure flag is set require the authentication parameters.

Responses

A successful interaction returns an HTTP response code of 200 with the JPEG file in the body of the message. Errors are returned as an HTTP 403 Forbidden message.

Example JPEG Requests

Examples of downloading thumbnail and a particular zoom level are given below. More examples can be found in our Javascript code samples.

Example JPEG Request for Thumbnail

Example JPEG Request for Smallest Zoom Level

Events API

The URL of the request determines the output format (JSON or XML), and whether or not to use SSL transport layer security. The Events API does not contain a show, create, or destroy method.

index

This method provides a search interface where the search results are returned as either XML or JSON. You can query for each event type that is supported by the viewer, and the custom attributes that may have been applied (e.g. typically used for a username in your application).

Event Types

The following events are currently tracked by the standard Vuzit viewer, and have a number of attributes associated with them:

• document_loaded: returns the IP address, user agent, referer, time requested (since EPOCH), and any custom attributes when the document is opened.
• document_unload: returns the IP address, user agent, referer, time requested (since EPOCH), and any custom attributes when the document is closed.
• page_view: returns the IP address, user agent, agent, referer, time requested (since EPOCH), seconds-on-page, and any custom attributes for each page view within a document
• download_original_click: returns the IP address, user agent, referer, time requested (since EPOCH), and any custom attributes when the Download button is clicked.
• download_pdf_click: returns the IP address, user agent, referer, time requested (since EPOCH), and any custom attributes when the Print PDF button is clicked.
• zoom_in: returns the page number, IP address, user agent, referer, time requested (since EPOCH), and any custom attributes when the reader zooms-in on a particular page.
• zoom_out: returns the page number, IP address, user agent, referer, time requested (since EPOCH), and any custom attributes when the reader zooms-out on a particular page.

Responses

A successful interaction returns an HTTP response code of 200. The XML or JSON response contains all of the attributes described above. Responses that return errors are covered in the Failure Responses section.

Example XML Request (document_loaded)

Note that documents where the secure flag is set require the authentication parameters.

  
    76.124.109.32
    document_loaded
    767814
    1oto
    https://ssl.vuzit.com/user/view/1oto?oid=3
    Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.9.1.5) Gecko/20091102 Firefox/3.5.5
    
    1260307295
    
    
  

Example JSON Request (page_view)

Note that documents where the secure flag is set require the authentication parameters.

{
  "event": {
    "remote_host": "79.252.112.122",
    "event": "page_view",
    "web_id": "1oto",
    "referer": "https://ssl.vuzit.com/user/view/1oto?oid=3",
    "user_agent": "Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.9.1.5) Gecko/20091102 Firefox/3.5.5",
    "value": "",
    "requested_at": "1260307293",
    "page": 1,
    "duration": 30
  }
}

Authentication

Most requests require authentication which protects you from unauthorized and malicious use of your account. This is achieved by passing in your public key, a specially constructed signature, and a timestamp. You may be able to skim the remainder of this section and jump right to the Example Authentication Code.

The Vuzit REST API uses an HTTP authentication scheme based on a keyed-HMAC (Hashing for Message Authentication) signature for authentication as defined by RFC 2104. This scheme should be familiar to developers of the popular Amazon S3 web service.

Public and Private Keys

1. Go to the Settings page to retrieve your keys (requires login).
2. Note your Public and Private Key values.

Generating a TimeStamp

The timestamp is represented as the number of seconds since the epoch in the UTC timezone.

The timestamp is used as part of the authentication process and ensures that a request is only valid for a limited amount of time. The intention of these restrictions is to limit the possibility that intercepted requests could be replayed by an adversary. For even stronger protection against eavesdropping, we offer an encrypted connection using SSL.

Generating a Signature

To authenticate a request, you first concatenate several parameters into a string, and then apply the HMAC-SHA1 algorithm using your Private Key to get the signature. This is informally called signing the request, and we call the output the signature because it simulates the security properties of a real signature.

1. Produce the string_to_sign by concatenating the following parameters together into a single string without spaces:
• Method name (e.g. create, show, destroy)
• web_id (required for show and destroy)
• Public Key
• Timestamp (see above)
• Watermark (optional: for downloading documents that contain digital watermarks via the show method)
2. Apply the HMAC algorithm with the SHA-1 digest algorithm (HMAC-SHA1) to the string_to_sign, using your Private Key as the key for the SHA-1 algorithm.
3. Apply the base64 encoding algorithm to the result of the previous step.
4. If using the show and destroy methods, then the signature must get URL encoded (ie. CGI escaped).

Example Authentication Code

Web Service APIs, in general, are language-agnostic so we have provided some example code you can use in different server-side systems. These examples will only generate the signature and timestamp for you, and are not complete examples.

Web Services Libraries

• .NET Framework - C#, Visual Basic.NET (VB.NET), JavaScript (JScript.NET), LUA, Pascal or Python
• Java
• PHP
• Ruby
• Command-line

Please Contact Us if you would like to contribute code to this section, need samples for other languages, or have any other questions.