The API

Despite her massive internal complexity, Laura has a fairly simple API. I'm going to edit further detail into this document later, but here's the basics.

Interacting with Laura will be mostly just inserting messages. Don't worry about internal details like fingerprints, that's all handled inside laura-robot. Each action has its own URL that you can send data to. Messages are in a threaded model, where messages with no parent are root messages, and messages can have at most one parent (although multiple messages can have the same parent). Conceptually, the parent is the message that a message is the response to.

http://laura-robot.appspot.com/api/insert

This URL is the one that you access from your own app to insert a message into the system. It accepts POST requests with the following variables:

• parent
• author
• text
• responseurl

The parent is the message that this message is a response to. For this variable, you need to use a key that Laura has already given you. Laura always returns a key after insertion operations, so be sure to use that, and not your own internal keys by mistake. The author is an email address that represents a user. It doesn't have to be real, just in email format ([email protected], for example, is valid). "text" is pretty obvious. For best results, strip out whitespace from the beginning and end, but leave it in in the middle.

The only optional variable is responseurl. Laura works slowly, and for that reason, asynchronously. When you want Laura to formulate a response to a message and send it to you, you need to give a URL where you want to receive it. This is that URL. Only provide the URL for messages where you want Laura to send you a response.

When inserting, Laura returns a JSON object. It will have an "inserted" variable, which is Laura's internal database key for the message you just inserted. If you set a responseurl, it will also include a "response" variable, which is Laura's internal database key for the response she's building.

When she finishes a response, she sends POST requests that have two variables: key, and reply. The "key" is the database key of the response, which you can match up with the "response" variable she returned during one of your earlier insertion requests. The "reply" is the actual text content of the response.

Once this data is sent to your app, it's destroyed/cleaned up in Laura. All memory of the response action is in the Appengine logs. She expects you to be responsible and insert the response with your app's email address. For example, laura-wavebot is a Google Wave Robot that connects Laura to Google Wave. When Laura sends a response to laura-wavebot, laura-wavebot forwards it to Wave, waits for server confirmation from Wave, and then inserts it back into Laura under the address "[email protected]".

http://laura-robot.appspot.com/api/purge

This page takes GET requests - you could visit it with your browser if you wanted. But don't, except on your own Laura clones, please. The URL is, at the moment, publicly accessible, and starts a chain-reaction process that deletes every instance of every type from the database. Handy for debugging, but dangerous on established Laura cores. This right here is the big reason I'm nervous about releasing my code to open source so early, before patching up security holes like this.

Go back Home