Write API

You are able to create and update your content via the API from any page on your site. Typically Write APIs are secured by username and password or an API key, but in the case of using Interface, the API is used by clients browsing on your public website which, by its nature, can’t be protected with a username and password or API key. Doing so would expose your write API credentials for anyone to exploit.

To be able to write to the API from your website, you must include a Javascript file to generate a special token. This token is only valid for the user who requested the token, can only be used once, and is only valid for a small window of time (usually up to 20 minutes). To do this, put the following at the end of your HTML page:

  <script type="text/javascript" src="/interface/javascripts/i.js"></script>

Or using the ERB helper:

  <%= token_javascript %>

By default this will do nothing. To activate a token for a form on your HTML page, you must add a class called “tok” to the form:

  <form action="/api/blog" method="post" class="tok">

This will activate a token for your form, and place hidden form fields in the form automatically. When the user submits the form, Interface validates the token and processes the request if the token is valid.

Once your form has been submitted successfully, the token is invalidated. Typically when submitting a form, the page will refresh, reloading the page and creating a new token. However if you are using an AJAX call to submit the form, the page will typically not refresh, and your token will be stale. If you want to be able to submit multiple Writes without refreshing the page, you must regenerate a token for the next form submission. This can be done with a Javascript call:

  tok.r();

Which will refresh the token, and place them in all forms with the “tok” class. Note that if you have multiple forms on the page, they will all have the same token. If you want to submit multiple forms in succession, you must refresh the token before you can post next form.

In addition to the Interface token, there is another token which protects against cross-domain forgery attacks, called the “authenticity_token”. This must be sent in with the rest of the API request, and can be accomplished with another hidden field:

  <input type="hidden" name="authenticity_token" value="<%= @params.authenticity_token %>" />

Data Format

Data you are submitting to the Write API, whether it’s in a form or built using Javascript, must be an associative array, denoted by the model name. For example if you wanted to submit a Comment with name, url and body fields, your form would look like this:

  Name: <input type="text" name="comment[name]" />
  URL: <input type="text" name="comment[url]" />
  Comment: <textarea name="comment[comment]"></textarea>

Create vs. Update

To create a new content item in Interface, you must POST data to the specific API URL for the desired model. For example if you want to create a new Comment, POST your data to:

/api/comment

If you would like to update a content item, you must specify the id of the item in the API URL, and also make sure to use an HTTP ‘put’ rather than a ‘post’. In forms, this can be accomplished by creating a hidden field by the name ‘_method’ with the value ‘PUT’. To update a Comment with id 17, PUT your data to:

/api/comment/17

What Happens After a Create or Update?

By default, when submitting an HTML form, Interface will redirect you back to the page that submitted the request. If you would like to redirect to another page, send in a redirect_to parameter with the desired URL to redirect to:

/api/comment/17?redirect_to="/home"

If you are using Javascript to submit to the API, you can add .json or .xml to the end of your URL, and Interface will return the object you created or updated in the requested format, instead of redirecting:

/api/comment.json

Writing to the API Using Flash

If you would like to write to the API using Flash, you must still make use of the Javascript token system and pass in the token key/value pair with your requests.

Writing to the API from any other programming language

Currently we do not support writing to the API from another programming language (such as PHP, Python, Ruby, etc). We are working on an API key system that allows programmers to authenticate to the API to be able to Read and Write data, with integrated roles and permissions support.