Openomy API v2.0 Specification

Introduction

The Openomy API is a clean, REST-based API meant for you to create interesting applications. The APIs give you controlled access to users' data, including their files and tags.

We try to keep as many libraries up to date as we can. Currently, we have a Ruby library which is our reference implementation. You can download this and other open-source and free libraries at SourceForge.

In order to use the Openomy API, follow the specification below. You'll need to learn about creating applications, the operations you can perform, and the resources those operations return.

Getting Started | Operations | Resources | Error Codes | File Upload Example | File Download Example

Getting Started

In order to use our API, you must first create an application. This will provide you with an application key and private key. The application key is the equivalent of a username, and the private key is the equivalent of a password. Be sure to keep this information safe!

Signatures

Each request you send must be signed so we can ensure you are the application you say you are. Signing happens like so:
  1. Construct an HMAC-SHA1 of the following pattern:
    HTTP-VERB\n
relativeUri\n
date
    • HTTP-VERB: This is the verb of the request you are making (e.g. GET, POST, PUT, DELETE, etc).
    • relativeUri: This is the URI of the request you are making (e.g. /2.0/tags). This does not include any query string parameters.
    • date: This is the date of the request. This is a RFC2616 valid date, and is supplied via the X-Openomy-Date header. If you choose not to supply the X-Openomy-Date header, this will fall back to the Date header. If neither are supplied, the request will fail.
    • The key for the HMAC is the private key associated with your application.
  2. This signature will be used as part of the Authorization header. The Authorization header passed needs to be of the following form:
    Authorization: openomy {applicationKey}:{confirmedToken}:{signature}
    • Some calls (specifically those of acquiring a confirmed token or registering a user) do not require a confirmed token. In this case, simply pass an empty string for the confirmedToken parameter. All calls which deal with user data require a confirmed token (and they are described in more detail below).

Operations

Operations are the actions you can perform via the API. Each operation is an HTTP call to our servers at http://api.openomy.com.

You'll note that our URLs always begin with /2.0. The 2.0 is a version number and will allow us to make non-backwards compatible changes by moving this forward as necessary.

Making Requests To Operations

To perform an operation, simply make a standard HTTP call to the resource described. If the operation requires an Input, pass the input as the request body. If the operation does not require an Input, the body of the request should remain empty. Remember to pass the required Authorization header as well as any other additional headers that may be necessary (e.g. the Date header as described described above).

Reading Responses From Operations

Our responses follow standard HTTP responses. The first thing you should do when reading a response from our APIs is look at the HTTP response code. We try hard to ensure that our HTTP response codes are correct and will give you a good indication of the result of your operation.

If the response is successful, we will return the resource listed as the Output of the operation. If there is no Output, the HTTP response code is the determining factor. If there is an Output, you should read it and parse it.

If there is an error with your operation, we may return a standard error resource, which describes the error. This includes an error code which you may read and make decisions based upon. The error resource also contains a human-readable message if you'd like to pass that back to your users.

Authorization | Files | Tags

Authorization

Authorization is essential for the Openomy APIs to be successful. In order to access a user's data, the user must authorize your application. This can happen through an API call directly from your web site or application. This authorization returns a confirmed token. A confirmed token is what you use to identify which user you want to retrieve data for (you can think of this as a user ID).
Create Confirmed Token: POST /2.0/auth/confirmedtokens
Notes: Create a confirmed token by passing in a user's username and password.
Input: User
Output: Confirmed Token
Convert Legacy Confirmed Token: POST /2.0/auth/confirmedtokens/legacy
Notes: Converts a legacy (API v1.0) style confirmed token into a new confirmed token. This is only necessary if you're porting your application from the old APIs to these new APIs and want to seamlessly convert your users.
Input: Legacy Confirmed Token
Output: Confirmed Token
Register User: POST /2.0/auth/users
Notes: Register a user for Openomy and automatically create a confirmed token as well.
Input: User
Output: Confirmed Token

Files

At the core of Openomy is the files. The following operations allow you to view file metadata, upload files, download files, etc.
Get File: GET /2.0/files/{file_id}
Notes: Get the metadata for a file, as well as a link to the URL where you can actually download the file (see the File Download Example).
Input: None
Output: File
Add File: POST /2.0/files
Notes: Upload a file. The workflow for uploading a file is described in the File Upload Example.
Input: None
Output: File
Modify File: PUT /2.0/files/{file_id}
Notes: Modify a file's contents. The workflow for uploading a file is described in the File Upload Example.
Input: None
Output: File
Rename File: PUT /2.0/files/{file_id}/name
Notes: N/A
Input: File
Output: File
Delete File: DELETE /2.0/files/{file_id}
Notes: N/A
Input: None
Output: None
Get Viruses For File: GET /2.0/files/{file_id}/viruses
Notes: N/A
Input: None
Output: Viruses
Get Tags For File: GET /2.0/files/{file_id}/tags
Notes: N/A
Input: None
Output: Tags
Add Tag To File: POST /2.0/files/{file_id}/tags
Notes: N/A
Input: Tag
Output: Tag
Delete Tag From File: DELETE /2.0/files/{file_id}/tags/{tag_id}
Notes: N/A
Input: None
Output:None

Tags

In Openomy, files are not placed into folders. Rather, files are associated with tags. The following operations allow you to work with tags.
Get All Tags: GET /2.0/tags
Notes: N/A
Input: None
Output: Tags
Get A Tag: GET /2.0/tags/{tag_id}
Notes: N/A
Input: None
Output: Tag
Create A Tag: POST /2.0/tags
Notes: N/A
Input: Tag
Output: Tag
Delete A Tag: DELETE /2.0/tags/{tag_id}
Notes: N/A
Input: None
Output: None
Rename A Tag: PUT /2.0/tags/{tag_id}/name
Notes: N/A
Input: Tag
Output: Tag
Get Files On Tag: GET /2.0/tags/{tag_id}/files
Notes: N/A
Input: None
Output: Files
Get Users On Tag: GET /2.0/tags/{tag_id}/users
Notes: N/A
Input: None
Output: Users
Add User To Tag: POST /2.0/tags/{tag_id}/users
Notes: Add a user to a tag. This allows the user to have access to the tag.
Input: Tag User
Output: Tag Users
Modify A User On Tag: PUT /2.0/tags/{tag_id}/users/{username}
Notes: Modify a user associated with a tag. Typically this involves making or revoking admistrative privileges on this tag.
Input: Tag User
Output: Tag Users
Delete User From Tag: DELETE /2.0/tags/{tag_id}/users/{username}
Notes: N/A
Input: None
Output: None

Search

The search APIs allow you to easily and quickly find files and tags given a query.
Search: GET /2.0/search?query={query}
Notes: The search term you are looking for is passed as a query string parameter named query. Remember this is not part of the relative URL while constructing your signature.
Input: None
Output: Search Results

Resources

A resource is what is passed into and returned from an Operation. For instance, when calling the GET /2.0/tags operation, a Tags resource would be returned. Similarly, when calling the POST /2.0/tags/{tag_id}/users operation, a Tag User resource is passed and a Tag Users resource is returned.

File

<file>
  <id>1</id>
  <owner>iseff</owner>
  <created-at>2007-03-05 12:00:00 AM PST</created-at>
  <updated-at>2007-03-06 12:00:00 AM PST</updated-at>
  <name>test.txt</name>
  <mime-type>text/plain</mime-type>
  <size units="bytes">1234</size>
  <resource-url>http://files.openomy.com/api/2.0/resources/{resource}</resource-url>
  <public-url>http://files.openomy.com/public/iseff/test.txt</public-url>
</file>

Files

<files>
  <file>...</file>
  <file>...</file>
</files>

File Success

<success>
  <message>Some message if you want one, such as "File uploaded successfully"</message>
  <file-id>12345</file-id>
</success>

Tag

<tag>
  <id>1</id>
  <name>Test tag</name>
  <creator>iseff</creator>
  <created-at>2007-03-06 12:00:00 AM PST</created-at>
</tag>

Tags

<tags>
  <tag>...</tag>
  <tag>...</tag>
</files>

Virus

<virus>
  <name>MyBoom</name>
  <uploader>mcodik</uploader>
  <detected-at>2007-03-06 12:00:00 AM PST</detected-at>
</virus>

Viruses

<viruses>
  <virus>...</virus>
  <virus>...</virus>
</viruses>

Tag User

<tag-user>
  <user>iseff</user>
  <created-at>2007-03-06 12:00:00 AM PST</created-at>
  <admin>true</admin>
</tag-user>

Tag Users

<tag-users>
  <tag-user>...</tag-user>
  <tag-user>...</tag-user>
</tag-users>

Confirmed Token

<confirmed-token>abcdefghijklmnopqrstuvwxyz</confirmed-token>

Legacy Confirmed Token

<legacy-confirmed-token>abcdefghijklmnopqrstuvwxyz</legacy-confirmed-token>

User

<user>
  <username>iseff</username>
  <password>p455wd</password>
  <email-address>iseff@iseff.com</email-address>
</user>

Users

<users>
  <user>...</user>
  <user>...</user>
</users>

Search Results

<results>
  <tags>
    <tag>...</tag>
  </tags>
  <files>
    <file>...</file>
  </files>
</results>

Error

<error>
  <code>ResourceNotFound</code>
  <message>The tag you requested was not found.</message>
</error>

Error Codes

The following error codes may be possible:

File Download Example

We make the distinction between the metadata of a file and the actual data of a file. When you call the GET /2.0/files/{file_id} operation, you are actually retrieving the metadata (i.e. name, mime-type, size, owner, etc) of the file. This metadata also includes a resource-url property, which is an URL you would request to download the actual content of the file. This resource-url is only valid for 60 seconds, so you must make the request reasonably quickly. What follows is an example of pseudo HTTP requests/responses to download a file's contents: 
GET /2.0/files/1234 HTTP/1.0
--
<file>
  ...
  <resource-url>http://files.openomy.com/...</resource-url>
</file>
----
GET [resource-url] HTTP/1.0
--
302 Redirect
Location: http://s3.amazonaws.com/...
----
GET [location] HTTP/1.0
--
[binary data]

File Upload Example

Like downloading a file, we also separate the metadata and data for uploading a file. When using either the POST /2.0/files or the PUT /2.0/files/{file_id} operation, the following pseudo HTTP requests/responses occur: 
POST /2.0/files HTTP/1.0

filename=my%20filename.txt
--
<file>
  <resource-url>http://files.openomy.com/...</resource-url>
</file>
----
POST [resource-url] HTTP/1.0
[binary data is body]
--
<success>
  <message>...</message>
  <file-id>1234</file-id>
</success>


Home | About Openomy | Openomy API Documentation
(c) 2008. Openomy, LLC. Privacy Policy Terms of Use