API Documentation

StorageRoom is a service and platform to manage any kind of content online and to easily integrate that content into one or multiple mobile, web or desktop apps.

The StorageRoom Application Programming Interface (API) has been created to allow you to interact programmatically with StorageRoom. The StorageRoom API returns data in JSON, so that you can easily integrate the content into your application or web site. As a developer you can program a large variety of applications on top of the StorageRoom API. There are no thematic limitations, be creative and start developing for your favorite device or platform by using your programming language of choice.

API Summary

The StorageRoom API is designed in a RESTful fashion and is easy to use. It relies on simple unique tokens for access authorization and for the authentication of your application. All Resources support the JSON and JSONP Format. Open Source Libraries are available and make it even easier to use StorageRoom as the data backend for your application.

Almost all of StorageRoom's functionality can be used by your application. Some of the most important features are:

• Search all your Entries to only get the content you require.
• Create a new Collection that contains further Entries
• Add new Entries (Import)
• Update or delete any Entry
• Load associated Entries through Relationships
• Use Webhooks to respond to Entry modifications

Examples

Collections are the containers for your data. They are very flexible, a Collection might define the following Fields:

Restaurant

Editors will get a simple but powerful interface to manage all those restaurants and you can query this data and display the content in your applications.

Table of Contents

The API documentation was written to be read from top to bottom. The top parts build upon each other and provide a good understanding of the API essentials.

• Architecture: Explains the general architecture of the API and how the RESTful web service is modeled
• Authentication: How to authenticate your application
• Errors: HTTP Response Codes and error messages
• Formats: Description of the various formats (JSON, JSONP)
• Resources: What the various Resources do and what they look like
• Embedded Resources: Explains the nested Embedded Resources
• Search: How to find the Entries you are looking for
• Endpoints: List of exposed Endpoints
• Webhooks: Webhooks send a request to your own server and respond to changes
• Demo: Browse some demo data
• Libraries: Open Source StorageRoom libraries
• Sample Code: Open Source example code
• FAQ: Frequently asked questions
• Support: What to do when you encounter problems

Getting Help

We tried our best to make the usage of our API as simple as possible. But if the API doesn't behave like you think it should, if documentation is missing or incorrect or if you have any questions, comments or suggestions, please read the support section.

Architecture

The StorageRoom API is designed in a RESTful fashion. REST (Representational State Transfer) is a set of design principles that state how Web resources can be described and manipulated via the HTTP protocol and URIs. As REST is leveraging existing Web standards it is very easy to consume RESTful web services with any programming language that can make HTTP requests. REST is an architectural style and not a formal protocol. There is no "official" way to build a RESTful web service. Our implementation focuses on simplicity and applicability.

In the next paragraphs we will briefly describe what the four key REST principles are and how they apply to the StorageRoom API. If you want to find out more about REST you can find links for further reading at the bottom of the page.

1. Every "thing" is a Resource with a unique identifier

All the "things" on StorageRoom are RESTful Resources. Resources are the nouns of the web service, they are holding all the data and they can be created, modified or removed.

All Resources need a unique identifier, so that they can be read or modified. The identifier of a Resource is not only unique within the StorageRoom API, it is globally unique in the Web by using URIs.

All the Resources within the StorageRoom API are identifiable by their full URI. Associations also depend on the full URIs to reference other Entries.

Take a special look at the first two URIs, as it is not a single "thing", it is an Array of "things", but the Array is still represented as a Resource with a unique URI. Everything that is worth being identified within the web service has such an URI.

2. Resources are linked together

The Web is built out of pages, and all the pages contain links to other pages. The following is an HTML link to another page: Google's homepage. Resources in a REST web service contain links to other associated Resources, just like all the HTML pages in the Web contain links to other pages.

A link to another child Resource might look like this in the StorageRoom web service:

{
    "entry": {
        "@type": "Category",
        "@version": 3,
        "@updated_at": "2010-11-26T11:31:28Z",
        "@created_at": "2010-11-26T11:31:28Z",
        "@collection_url": "http://api.storageroomapp.com/accounts/:account_id/collections/:collection_id",
        "@url": "http://api.storageroomapp.com/accounts/:account_id/collections/:collection_id/entries/:entry_id",
        "name": "Music",          
    }
}

As you can see, the Resource contains a "@collection_url" to the Resource URI of the Collection of the Entry (http://api.storageroomapp.com/accounts/:account_id/collections/:collection_id). Associations also use Resource URIs to link to each other.

In general you should always follow the links within the documents that you receive via the API and not manually specify the appropriate URIs for Resources. This is in analogy to links that you follow on regular web pages instead of updating the address bar every time you want to surf somewhere else.

3. Resources have different Representations

The examples above showed some JSON markup, but JSON is only one kind of representation of a Resource. Each Resource can be accessed in multiple different Representations, as shown in the following table:

All of the above URIs represent the same data, but each time the Resource is shown in a different Format. Behind the curtain, it is always the same Resource. You can select the response format for each request that you make.

There's more information about the different Resource Types in the Formats section.

4. Resources can be accessed with a set of standard methods

Great, I understood the URIs and it is nice to have the data in multiple formats, but how can I create new stuff or delete existing stuff?

There are no new URIs to create, update or delete Resources. The action that is performed on the Resource at the given URI is determined by the HTTP method that is used. So far we only created GET requests. The HTTP protocol defines more HTTP methods/verbs that can be used in a request.

Change the HTTP method by specifying a request method parameter in your programming language and therefore update, delete or create Resources whenever you want to. Please note that for the first three Requests the action is performed on an individual Resource URI, while the last Request to create a new Resource is sent to the collection URI.

When you want to create or update a Resource you have to send a Representation of the Resource to the web service endpoint in the JSON format. If your Request is accepted the web service will return the Representation of the new or updated Resource with additional attributes (e.g. the time it was created and child associations). If things don't work out the web service will respond with a special error message.

The HTTP methods translate nicely into the basic CRUD database operations:

GET Requests are "safe" requests, they never change anything on the server, you cannot break anything by doing a GET Request.

Further Reading

This was a basic explanation of REST and how it applies to StorageRoom. Enough for you to start exploring the StorageRoom API. The websites below will be a good starting point if you want to learn more about REST.

• http://en.wikipedia.org/wiki/Representational_State_Transfer
• http://rest.blueoxen.net/cgi-bin/wiki.pl?FrontPage
• http://www.infoq.com/articles/rest-introduction

Authentication

Each application that you create contains a set of authentication credentials that you need to pass to our servers to authenticate yourself. A request to an Entry can only be made if the application has the corresponding access rights to the Collection. Access rights are defined through Roles in the web interface. You should keep your credentials secret, especially for Applications that have write-access to Collections.

There are two ways to pass the credentials, they are explained in the following.

Passing a query parameter

Just pass an additional query parameter called "auth_token" on all your requests to authenticate yourself. This comes in handy for situations where it is not possible to set HTTP headers.

curl "http://api.storageroomapp.com/accounts/:account_id/collections/:collection_id/entries?auth_token=YOUR_TOKEN"

Using HTTP Basic Auth

Another option is to use the same set of credentials with HTTP Basic Authentication. Just pass your token as the username and leave the password blank. This option might be easier to set up for all the HTTP requests in your HTTP library. Instead of a blank password it is possible to pass an "X".

curl --basic -u YOUR_TOKEN:X "http://api.storageroomapp.com/accounts/:account_id/collections/:collection_id/entries"

Error Handling and Error Codes

HTTP Status Codes

The HTTP protocol defines certain HTTP Status Codes that are used across the web. The table below provides an overview about the Status Codes used by the StorageRoom API. You can find a full list of all status codes on Wikipedia.

422 Unprocessable Entity

You wanted to create or update a Resource and received this error. This means, that the Request that you created was valid, but there were validation errors when the server tried to save the Resource. An example for this could be that you provided an invalid value for an attribute. You should show those messages to the user so that she can correct her Entry. You should not look into the elements and parse the error message, as the messages might change and they vary for different languages.

An example for an error message:

{
    "error": {
        "code": 422,
        "message": ["Name can't be empty", "Tags are not in a valid format"],
        "@type": "Error"
    }
}

Requests and Responses

All Requests to the StorageRoom API must be encoded in UTF-8. The server will return an UTF-8 encoded document.

Request Formats and how to select one is further described in the Formats section.

Optionally set the "Accept-Encoding" HTTP Header to "gzip, deflate" and we will return compressed Representations of all Resources. This is a trade-off, it requires more computing power on the client, but saves a lot of bandwidth. Your HTTP library of choice must support compression or you have to decompress the Request body manually.

Save processing power and bandwidth through caching by using HTTP ETags and the If-None-Match header.

Meta Prefix ("@")

You can change the meta data prefix for each request if you find that the "@" prefix is problematic when using your JSON or REST library of choice. An example for such a library is the excellent RestKit (Objective-C). It relies heavily on Apple's Key-Value-Coding (KVC), which doesn't allow the "@" in a key path.

Please be careful when changing the meta prefix and be certain that you use a prefix that doesn't cause collisions with the keys in your Entries. Good examples for alternative meta prefixes would be "meta_", "m_", "_" or "$".

It is possible to change the meta prefix in two ways. You should stick to one way and set this permanently in your code for all requests.

Add a Parameter to the Query String

To quickly change the meta prefix just append a parameter called "meta_prefix":

http://api.storageroomapp.com/accounts/4d13574cba05613d25000004.json?auth_token=DZHpRbsJ7VgFXhybKWmT&preview_api=1&meta_prefix=m_

Test this with our Demo Account

Set an HTTP Header

Another way to change the meta prefix is to send a custom HTTP header called "X-Meta-Prefix" with each request. An example with curl is shown below:

curl "http://api.storageroomapp.com/accounts/4d13574cba05613d25000004.json?auth_token=DZHpRbsJ7VgFXhybKWmT&preview_api=1" -H "X-Meta-Prefix: m_"

Formats

The StorageRoom API understands several different Formats, each useful in a variety of different programming contexts.

• JSON: Easily parsed in many languages, lightweight, can be evaluated in JavaScript.
• JSONP: Same structure as JSON, use it for cross-domain requests in older browsers
• XML: On roadmap (Screw that, we will stick to JSON)

Specifying the Format

It is possible to specify the Format in two different ways:

• Append the format to the URI
• Set HTTP Headers

Append the format to the URI

This is especially useful for tools where it is not possible to set your own HTTP Headers.

To quickly view different Formats within your browser you can just surf on the StorageRoom website and click on the "JSON" buttons.

Please notice that changing the extension just displays another Representation of the Resource. If you "delete" one Representation of the Resource all Representations will be deleted.

The format extensions can only be used to read data. If you want to modify Resources you have to set HTTP Headers as well, otherwise our Request Forgery Protection kicks in and will block your query, resulting in a returned HTML page with an HTTP Status Code of 400 (Bad Request).

Set HTTP Headers

The HTTP protocol uses HTTP Headers to specify which media type is used in a request and which media types are supported by the client for the response.

The StorageRoom web service uses the HTTP Headers to let you pick a Format. This is a translation of our Formats to the media types you should use in HTTP Headers:

HTTP Accept Header

The HTTP protocol uses the "Accept" Header to let the client specify which media types it supports and prefers. This can be used to specify the Format of the response without using a format extension. The command line tool curl, which is available and pre-installed on many platforms, can be used to test this.

# this will return the JavaScript Representation
curl "http://api.storageroomapp.com/accounts/:account_id/collections/:collection_id/entries/:entry_id?callback=test" -H "Accept: application/javascript" 

The server will always respond in the Format that you specify in the HTTP Accept Header. However, the format extension has a higher priority than the Accept Header.

The server will specify the current media type of the response in the HTTP Content-Type Header.

HTTP Content-Type Header

The HTTP Content-Type Header specifies which format the current request or response is in. The server will set the Content-Type header in response to your requests to show which Format is returned.

If you are sending data to the StorageRoom API with a POST or PUT Request you also have to specify the Content-Type of your current request, so that the server knows how to parse the data. If you don't set the Content-Type our Request Forgery Protection kicks in and will block your query, resulting in a returned HTML page with an HTTP Status Code of 400 (Bad Request).

Resources

Resources are all the "things" on StorageRoom that you can access and modify by using the StorageRoom API. Resources consist out of simple data types and other Embedded Resources (compound data types).

This section explains how a Resource is structured in general so that it is easier for you to parse the data. The individual Resource sections contain more information about each Resource and what it is used for.

Simple Data Types

On the lowest level Resources exist out of simple data types.

• Strings
• Integers
• Floating point numbers
• ISO8601 timestamps
• Booleans

Compound Data Types

All Resources in the StorageRoom API are compound data types. They exist of multiple simple data types and/or contain other compound data types. Compound data types always contain a "@type" attribute that describes which data type you are dealing with.

The table below shows all primary Resources that are used in the StorageRoom API.

Optimistic Locking

The API uses Optimistic Locking to prevent lost updates when two Users edit the same Resource simultaneously.

If you want to update an existing Resource through the API you must send the "@version" key back exactly as it was sent to you from the API, otherwise you will receive an HTTP 409 status code and the Resource won't be updated. If you sent the "@version" key and you still receive this error then the Resource was just updated by another user. You should show an error to the user of your application and reload the Resource.

Embedded Resources

Besides the primary Resources described above there are also embedded Resources. Those Resources don't have their own URL and are always part of one of the primary Resources. The embedded Resources are:

• Field
• Location
• File
• Image

Search Entries

Use the API's search functionality to construct your own queries to find Entries with many different filter criteria.

Endpoint

• http://api.storageroomapp.com/accounts/:account_id/collections/:collection_id/entries

Query Options

The following options don't change the results that are returned, but they change how the results are returned to you.

# 1000 Categories sorted by their name in descending order
/entries?sort=name&per_page=1000&order=desc

Array Parameters

Sometimes it is necessary to pass multiple values to one operator. Append the "[]" characters to the query key to define it as an array. Repeat the same query key multiple times to pass multiple values.

# All Articles tagged with "tag1"
/entries?tags=tag1

# All Articles tagged with "tag1", "tag2" and "tag3"
/entries?tags!all[]=tag1&tags!all[]=tag2&tags!all[]=tag3

Filter Options (Operators)

Get a subset of all available Entries with these filter options. You can combine the options in any way you want. Append a matcher to an identifier with the exclamation mark (!).

Examples

# All requests start with:
# http://api.storageroomapp.com/accounts/:account_id/collections/:collection_id...

# All Products where the price is between 10 and 50
/entries?price!gt=10&price!lt=50

# All Products that have been trashed
/entries?@trash=true

# All Restaurants around a location
/entries?location!within=((49.12,9.07),1)

# All Restaurants around a location (ordered by distance)
/entries?location!near=((49.12,9.07),1)

# All Articles where the description contains the word 'test'
/entries?description!match=/\btest\b/

# All Articles with a specific Category (Association)
/entries?category.url=:category_url

# All Articles tagged with "mobile" (ArrayField)
/entries?tags=mobile

# All Articles tagged with "mobile" AND "nokia" (ArrayField)
/entries?tags!all[]=mobile&tags!all[]=nokia

# All Articles tagged with "android" OR "iphone" (ArrayField)
/entries?tags!in[]=android&tags!in[]=iphone

# All Articles tagged where tags are *not* "android" OR "iphone" (ArrayField)
/entries?tags!nin[]=android&tags!nin[]=iphone

# All Articles with specific URLs
/entries?@url!in[]=article_url_1&@url!in[]=article_url_2&@url!in[]=article_url_3

# All Articles updated since a point of time (synchronization)
/entries?@updated_at!gt=2011-07-05T12:23:58

Endpoints

As all the Resources provide further links to other Resources you should not build URLs manually. Just follow the existing links. Building links manually is more effort and might break if we ever change our URL structure.

However, for a small script or widget it might be interesting to know what Endpoints are available.

This is an overview about all the available Endpoints. You should only use the Endpoints that are documented in this list. There might be some other undocumented Endpoints, but those might change without upfront notice.

Webhooks

StorageRoom supports Webhooks, so that a HTTP POST request is performed on a custom URL every time Entries are modified. You get notified about changes to your content when they happen and don't need to poll the API constantly to find out if a change occurred.

Use Webhooks to update certain Fields of an Entry on your server, create push notifications with a 3rd party service or use it to synchronize content with another CMS. The opportunities are endless, limited only by your imagination, as you can do anything you want with the data you receive.

Define up to 5 different Webhooks per Collection in our web interface and specify if you want to get notified on new, updated or deleted Entries. In addition, define if you want the callback to be triggered by all changes or only by changes through the web interface or the API.

For each change StorageRoom will send a POST request with a JSON Payload to your custom URL. Your service should respond with a HTTP Status Code of 200 or 201 when it processed the Webhook successfully. In case of failure StorageRoom will retry the request to your server multiple times after some delay. Your endpoint should be prepared for this and use the timestamps in the POST body, and not rely on the time the POST is executed.

Please be careful when updating content with a Webhook, as this could produce infinite loops, where your Webhook and the StorageRoom servers ping each other about changed content forever. Set the "skip_webhooks" parameter to "1" in the query string to prevent any Webhooks from being executed.

Configure a Postbin as your Webhook URL to test how Webhooks work and check out our Ruby on Rails Webhook Example.

Demo

Take a look at our demo account and browse the API with a read-only API key that we provide.

Use the following URL to start at the Account level:

• http://api.storageroomapp.com/accounts/4d13574cba05613d25000004.json?auth_token=DZHpRbsJ7VgFXhybKWmT&preview_api=1

Or take a direct look at a Collection:

• Restaurants: Shows many of the available Fields in action
• Wallpapers: Shows automatically generated thumbnail images
• Posts: Associations between Entries

Browser Extensions

To browse the JSON-API in your browser use one of the following plugins:

• JSONView for Firefox
• Pretty JSON for Chrome
• JSON Formatter for Safari

Libraries

It is not hard to consume the StorageRoom web service as soon as you have figured out how to use your HTTP library of choice. But it is even easier to use the StorageRoom API if you don't have to take care about stuff like parsing JSON responses yourself.

StorageRoomKit (iOS)

StorageRoomKit is a library for iOS and Mac OS that provides helper methods and classes that make it very simple to use the StorageRoom API.

Feature summary:

• Works with NSObjects and NSManagedObjects
• Supports the GET, POST, PUT and DELETE HTTP methods
• Comes with classes and mappings for all StorageRoom Resources
• Helper methods to generate StorageRoom paths
• ... and many more features that the underlying RestKit provides

You can find the code and usage examples on http://github.com/thriventures/StorageRoomKit.

Ruby Gem

To test our web service in every aspect we developed a Ruby Gem. We released it as an open source tool and everybody can use in their applications. It might also give you some inspiration on how to model a library for another programming language.

Importing content from another CMS or Excel sheet can be done in minutes with the Gem (Example).

Feature summary:

• ActiveRecord/ActiveModel like interface.
• Automatic creation of Entry Classes from a Collection, you don’t have to configure anything
• Supports lazy-loading of associations (e.g. post.category will fetch a category transparently if it has not yet been loaded)
• Supports caching through an identity map, so that Resources don’t have to be loaded multiple times
• File uploads and removals
• Model Callbacks
• Webhook Processing

Find the gem on http://github.com/thriventures/storage_room_gem.

sudo gem install storage_room

# Create an Entry
collection = StorageRoom::Collection.find('4ddaf68b4d085d374a000003')
Guidebook = collection.entry_class # the class is automagically configured from the Collection
entry = Guidebook.new(:name => 'Foo', :price => 1.23)

if entry.save
  puts "Guidebook created"
else
  puts "Guidebook could not be created: #{entry.errors.join(', ')}"
end

# Search for Entries
array = Guidebook.search(:name => 'Bar')

puts "Guidebooks with name 'Bar':"

array.resources.each do |g|
  puts "- #{g.name}"
end

# More examples on Github

JavaScript

It is very easy to use the RESTful JSON-API of our CMS in JavaScript (through cross-domain AJAX requests with CORS or JSONP). There is a plethora of great open-source JavaScript libraries for building web-based desktop & mobile applications that work great with our Content Management System (CMS) and make you even more productive:

• Backbone.js
• Ember.js
• Ext JS
• JavaScriptMVC
• jQTouch
• jQuery mobile
• Sencha Touch
• Spine.js
• SproutCore

Pick your weapon of choice and start building great content-based web applications!

Sample Code

To make using our API even easier we provide some sample code. Feel free to reuse parts of the examples.

iPhone

Restaurants are loaded from the StorageRoom CMS, saved locally with Core Data and displayed in a UITableView and a MKMapView. Details can be seen on a secondary page. The restaurants are cached for offline use until the user manually decides to load the Resources again from the web.

This example is kept simple on purpose and focuses on the downloading and parsing of the JSON data.

The code is on GitHub: https://github.com/thriventures/simple_iphone_example

Android

Restaurants and announcements are loaded from the CMS with the JSON API. They are saved locally in a SQLite database and displayed in an Activity with a ListView and an Activity with a MapView. Details can be accessed in a separate activity. The images in the ListView and in the DetailsView are downloaded in the background and cached locally for the application life-time. Special thanks go to Till Simon for providing the code.

The code is on GitHub: https://github.com/TillSimon/storage_room_android_example

Your code here

Please get in touch with us if you have an open-source project that's based on our API that you wish to see here.

FAQ

Is StorageRoom an application generator that spits out a templated mobile application?

Nope. You develop the app yourself or in cooperation with an agency. We only provide libraries to make your life easier. This is an advantage as you have the freedom to do whatever you want with the content in your app.

Can I use StorageRoom for Offline Content?

Yes. You can use StorageRoom to manage content, and then export the content and deliver it for offline use with your app. It is even possible to do delta-synchronization to keep the content up to date in your applications without releasing a new version.

How do I import content from my existing CMS?

There are so many different data formats that it would be hard for us to provide an universal importer. But content can be imported in a snap with our Ruby Gem.

How do I create relationships between my Entries?

If you have a "Posts" Collection and a "Category" Collection and you want to link each Post to a Category then you should create an AssociationField. You can model one-to-one and one-to-many relationships this way.

I have some content that doesn't fit into your Fields?

Use a JSON Field. You can add any custom deeply nested JSON data to this Field, there just won't be a nice interface to edit this content.

What is an Authenticity Token error?

Our servers have a protection against Cross-site request forgery. The protection is only activated for Requests that were made by a browser. Only the POST/PUT/DELETE HTTP Methods are checked.

If you receive this error in your application you probably forgot to set the correct HTTP Content-Type and Accept Header. See Formats for more information.

How do I use StorageRoom on iOS?

Give our StorageRoomKit library a try.

My JSON library doesn't like the "@meta_data" attributes?

Just change the default meta prefix to something else.

Support

We want your feedback! Did you find a bug or encounter a problem while using the API? Do you have feedback or suggestions that you would like to share? Did you find an error in the API documentation?

Maybe the answer to your question is already posted on our help & discussions page. If not, please post your question there.

If you want to contact us directly, send us an email: team@storageroomapp.com.