REST API

A JSON REST API (JavaScript Object Notation REpresentational State Transfer Application Programming Interface) is a mouthful, but it's also the standard way to move data around on the web. Having your data accessible through a REST API means you can use it on your websites, mobile apps, desktop apps, through IoT devices, just about everywhere.

Our REST API is as straight forward as we could make it. Every document in your database has a unique URL made up of:

Reading a Document

To read a document, just use your favorite method to "GET" the document by it's URL.

In our favorite language, JavaScript, that would look like:

and will return a document from our Wiki-Wiki-Wikipedia database of turntables, from the Turntables collection, the document called Rotato (that's the one with the potato on it).

Reading a Collections

To read a collection, just "GET" the collection by its URL.

For example:

will return an array of all the Turntables in our Wiki-Wiki-Wikipedia database.

Filtering Results

Filters are formatted as a standard URL search string:

Filter by Field Values

The field can be any field id in the collection's documents, and the value can be anything at all.

Filtering a collection by fields will only return documents that match ALL the filters you apply.

For example:

will return all Turntables that are Loud and Awesome!

Limits and Order

By default, querying a collection will return the whole collection with documents in the order you dragged them into on the collection screen. This might be great for small collections, but for larger datasets you'll want to limit the number of documents returned and do some automatic sorting.

You can do this with the limit, order, and direction filters.

For example:

will return 10 turntables in descending order by volume.

Select Document Fields

Often you don't want to load the entire document, especially if you're querying a collection. In this instance just select the fields you want to be returned. The select filter is a list of fields, separated by commas.

For example:

will return an array of all the Turntables in our Wiki-Wiki-Wikipedia database, but each document will only have the cover_image, name, and vibe fields.

JSON

Documents are returned as JSON objects that follow the structure you defined in the schema. The properties in the JSON object match the ids you set when creating the fields.

Reference fields will create nested objects that follow the schema of those documents, with any sub-field values merged into them.

Media fields are maped to the base URL pointing to that media item. Append media manipulations where you use it to format the media for your use case.

Adding a Document

Add documents through the API with a "POST" request to the collection where you'd like to add it. The payload should be a JSON encoded string that matches the schema of your collection.

For example:

will create a new document to Turntables for a second hand European Vespidae Acoustics Volume 2 and return an object with the new document's id.

Updating a Document

Update a document by sending a "POST" request to the document's URL.

The payload should include the fields, matching the document's schema, that you want to update.

For example:

will mark the European Vespidae Acoustics Volume 2 as sold. Who would actually buy it is another story...