API Reference

Writing to Freebase from Acre

Writing to Freebase from Acre is as easy as calling acre.freebase.mqlwrite or acre.freebase.upload... however, the tricky part is actually making sure everything is in order for doing the write.

Setting up your app

The first order of business is making sure that your app is correctly set up to write to Freebase. There are two options for this which are managed in the Web Services tab of the App dialog (to access it, click on the name of your app at the top left part of the app editor)

  • Write as the user - Users will be prompted for a one-time authorization to allow your app to use their username. Writes will be attributed to the person making them. Usually this is the best choice.
  • Write as username - Writes made by all of your users will be attributed to you. If you have many users, you may exceed Freebase's daily single user write limit.

The App Editor will automatically register your app for the first option by default. You can change this setting at any time, though.

Managing the user's authorization state

Assuming you use the first option, you'll also need to manage whether the user is actually "signed in" and therefore able to do a write. The acre.freebase.get_user_info API is very useful for this purpose:

<acre:script> 
  var user = acre.freebase.get_user_info();
  var return_url = encodeURIComponent(acre.request.url);
</acre:script>
<span acre:if="user">
  Signed in as: <a href="http://freebase.com/view$user.id">$user.username</a> |
  <a href="/acre/account/signout?onsucceed=$return_url">Sign Out</a>
</span>
<span acre:else=""><a href="/acre/account/signin?onsucceed=$return_url">Sign In</a></span>

This markup contains links to a default /acre/account script that exists in every app.

Editing UI

The simplest edit UIs can be created using basic HTML forms. Here's an example where we do a mqlread to look up the current user's personal quote on their profile (if they've logged in) and then offer them the opportunity to change it:

<acre:block if="user">
  <acre:script>
    var query = acre.freebase.mqlread({"id":user.id, "type" : "/freebase/user_profile", "personal_quote" : null}).result;
    var quote = query.personal_quote || "";
  </acre:script>
  <form method="POST" action="/write_quote">
    <label for="quote" />Personal Quote: 
    <input name="quote" value="$quote"/>
    <input type="hidden" name="user" value="$user.id" />
    <input type="hidden" name="lang" value ="/lang/en" />
    <input type="submit" name="submit" value="Update Quote" />
  </form>
</acre:block>
<acre:block else="">
  <a href="/acre/account/signin?onsucceed=$return_url">Sign in</a> to change your personal quote...
</acre:block>

Doing the write

When the form is posted to write_quote, we need something that will turn the posted data into a mqlwrite (or upload) call. Since we just want to redirect back to the current page if the write is successful, this is most easily done with a script rather than a template.

var form = acre.request.body_params;

var write_query = {
  "id" : form.user,
  "type" : "/freebase/user_profile",
  "personal_quote" : {
    "value" : form.quote,
    "lang" : form.lang,
    "connect" : "replace"
  }
};

try {
  acre.freebase.mqlwrite(write_query);
  acre.response.status = 303;
  acre.response.set_header('location', acre.request.headers.referer);
} catch(e) {
  acre.response.status = 500;
  acre.write(JSON.stringify(e.response||e, null, 2));
}

Developer Tools: