API Tutorial

This tutorial illustrates, at a high level, how to use the Lingr API. For low-level details, please see the API Reference.

Now let’s walk through a scenario where we use the API to enter a room with a nickname, say “Hello world”, then leave the room.

In this tutorial, we use curl as an HTTP client. In operating systems such as MacOSX or many distributions of Linux, curl is installed by default, and you don’t need to install anything to try out this tutorial.

0. Get an API key

Before you can use the Lingr API, you need an API key. Go to this page to get one.

To make sure your API is working, type the following address in your browser:

http://www.lingr.com/api/explore/get_new_rooms?api_key=[YOUR_API_KEY_HERE]

If you get an XML response in the browser, you are ready to go.

For the purposes of this tutorial, let’s assume we got the API key 0123456789abcdef0123456789abcdef.

1. Create a session

The first thing you need to do is create a session. You do this by calling the session.create.

From a terminal, you type commands as follows:

curl -d api_key=0123456789abcdef0123456789abcdef http://www.lingr.com/api/session/create

If you have received a response as follows, the request succeeded.

<?xml version="1.0" encoding="UTF-8"?>
<response>
 <session>9876543210</session>
 <status>ok</status>
</response>

The return value contains a session id which we’ll need to use later, so, parse and store the value. For the purposes of this tutorial, let’s assume we got the session id 9876543210.

Note that we must perform some API at least once every 10 minutes, or the session will time out. So let’s move on quickly.

2. Enter a chatroom

Now let’s enter our favorite chatroom. This room’s URL when accessed from a browser would be like http://www.lingr.com/room/MyFavoriteRoom, so we just extract the room id and use it in the API.

We enter the chatroom by calling the room.enter method.

From the terminal, you type commands as follows:

curl -d session=9876543210 -d id=MyFavoriteRoom -d nickname=api-dude http://www.lingr.com/api/room/enter

If you have received a response as follows, the request succeeded.

<?xml version="1.0" encoding="UTF-8"?>
<response>
 <ticket>my-room-ticket</ticket>
 <max_observe_time>80</max_observe_time>
 <occupant_id>my-chatter-id</occupant_id>
 <status>ok</status>
 <occupants>
  ...
 </occupants>
 <room>
  <url>http://www.lingr.com/room/MyFavoriteRoom</url>
  <description>This is really GREAT room!</description>
  <name>My Favorite Room</name>
  <counter>24</counter>
  <max_user_message_id>24</max_user_message_id>
  <id>abcdef12345</id>
  <icon_url>http://images.lingr.com/room/abcdef12345/16x16.gif</icon_url>
  <tags/>
 </room>
</response>

The return value contains a room ticket which we’ll need to use later, so, parse and store the value. For the purposes of this tutorial, let’s assume we got the ticket my-room-ticket.

Note that we must perform room.getMessages or room.observe at least once every 2 minutes, or the ticket will time out. So let’s move on quickly.

3. Say something!

Now let’s talk it up!

We speak in the chatroom by calling the room.say method.

From the terminal, you type commands as follows:

curl -d session=9876543210 -d ticket=my-room-ticket -d message=hello+world http://www.lingr.com/api/room/say

If you have received a response as follows, the request succeeded.

<?xml version="1.0" encoding="UTF-8"?>
<response>
 <status>ok</status>
 <counter>28</counter>
 <message>
  <text>hello world</text>
  <nickname>api-dude</nickname>
  <client_type>automaton</client_type>
  <timestamp>2007-01-16T16:52:44-08:00</timestamp>
  <icon_url>http://images.lingr.com/user/0/26x26.gif</icon_url>
  <id>28</id>
  <occupant_id>j4ROzTPY9ii</occupant_id>
  <type>user</type>
  <source>api</source>
 </message>
</response>

You can confirm the message is successfully delivered in your browser.

Note that since the ticket will be expired in 2 minutes after the room.enter method is called, we have to call the room.say method immediately in this tutorial.

4. Leave the room

OK, we’re all done now, so let’s leave the room.

We leave a chatroom by calling the room.exit method.

From the terminal, you type commands as follows:

curl -d session=9876543210 -d ticket=my-room-ticket http://www.lingr.com/api/room/exit

If you have received a response as follows, the request succeeded.

<?xml version="1.0" encoding="UTF-8"?>
<response>
 <status>ok</status>
</response>

When we exit the room, our ticket is invalidated, and cannot be used again. Any outstanding room observation calls that we have return immediately.

5. Destroy the session

When we’re finished using the API, we should destroy our session.

We destroy a session by calling the session.destroy method.

From the terminal, you type commands as follows:

curl -d session=9876543210 http://www.lingr.com/api/session/destroy

If you have received a response as follows, the request succeeded.

<?xml version="1.0" encoding="UTF-8"?>
<response>
 <status>ok</status>
</response>

When we destroy our session, any rooms that are currently occupied on behalf of that session are automatically exited, and any outstanding observation calls that we have return immediately.

That’s it!

Now we have seen how the Lingr API works.

There are other aspects to the Lingr API, such as authentication, user information query, etc. They all operate in a manner very similar to what we’ve illustrated here. Go explore the API Reference and let your imagination run wild!

And, when you’ve written your Lingr API application, please let the world know about it by listing it on the Showcase page.

If you want more, see more tutorial.