Lingr API

Lingr API

(under construction)

Lingr offers a full set of API so that developers can build tools that interoperate with Lingr's functionality. This document is a reference for the API.

This API is experimental. All developers using this API must tolerate possible changes that are backward incompatible and unannounced unavailability. New features, resources and policies are being deployed on very little, if any, notice.

Basics

App Key

App Key is NOT required, however it gives you a bunch of benefit - relaxed rate limit, promotion in the app directory (under construction), and planned more.

To use App Key, add app_key=[your_app_key] in the request parameters when you create a session, and subsequent API calls with the session will automatically look for your App Key.

HTTP methods

The Lingr API allows both GET or POST. We recommend that you comply with the design principles of Representational State Transfer (REST) as long as it makes sense, but if you can't for some reason (e.g. JSONP), it's also fine that you simply use GET for everything.

Formats

Currently, Lingr only supports JSON as its data format.

All methods accept a callback parameter, which will pass the JSON object to a given function so that you can simply eval the response. For instance, when callback=myFunc is given, the response body will look like this:

myFunc({"status": "ok", "session": "2lA42FcLddH"})

Character Encoding

Lingr uses and expects UTF-8 encoding everywhere. That's the long and short of it.

Timestamps

All timestamps are given in the format of ISO 8601 standard with UTC timezone.

2008-04-16T22:53:20Z

Session and Authentication

There are two types of API methods: The ones that require authentication, and the ones that don't.

With an API that requires authentication, create an API session with authentication information. you'll find yourself doing the following steps all the time:

1. call session.create with username and password
2. call the API in question
3. call session.delete

Rate Limiting

The API does have a limit on the rate of erroneous observe loops. Since the Lingr API's comet nature can easily gives an infinite loop with no wait, you must handle errors on observe requests correctly, or your requests will be degraded as it persists. If you need help, ask me in the developers room.

API Methods

Session

• session/create
• session/verify
• session/destroy

Room

• room/show
• room/get_archives
• room/subscribe
• room/unsubscribe
• room/say

User

• user/get_rooms

Event

• event/observe (at port 8080)