The Cligs API

Introduction

This page documents the Cigs API. The API will evolve over time to expose more of the service’s functionality to programs and this page will be updated to reflect the changes.

Versioning

The Cligs API is versioned, meaning that changes are contained to different versions of the API. New versions will be triggered when an API change will trigger an incompatibility with the current existing versions.

The API versions are:

  • Version 1 rolled out on 2008-10-06.

API Endpoint

The API end point is at http://cli.gs/api/vx where x is the version number. So for version 1 of the API, the end point is:

http://cli.gs/api/v1

Within each version, there are API functions that you can call.

The API works over HTTP GET only, not POST. Parameters are sent via the query string, as illustrated with the examples below.

API Keys & Authentication

Some functions of the Cligs API will require authentication to be used. The Cligs API supports authentication using API keys, with keys associated with a user account.

For functions that can work either with or without authentication, the presentation of a valid API key will trigger the authenticated mode. A blank or no API key will trigger the Public (unauthenticated) mode.

For the API functions that do not require authentication, no key is required.

Interesting Pages

  • API Documentation (this page).
  • API Google Group and Mailing List. Please join the mailing list to discuss the API with fellow developers and to talk about code libraries and other development topics.
  • Get/view/edit your own API keys, and also the link to provide to your app’s users for them to get their own Cligs API keys.

The last link is important: On that page, users will be able to create, enable/disable, delete API keys, and they will be able to get an overview of the API usage. These features and more are under development. The philosophy is to give the users complete control over their account.

The AppID

For tracking and promotion purposes (yes, to promote your app), an AppID is sometimes required. It is imagined to be a simple string to help uniquely identify your app. It will be used in the user’s control panel. Eventually, I’d like to have a public list of the most popular applications that use Cligs, so an HTML link here will be a link back to your app.

API Version 1 Functions

The following API functions are available in Version 1 of the API.

/cligs/create

The end point of http://cli.gs/api/v1/cligs/create allows you to create new cligs. The parameter are:

http://cli.gs/api/v1/cligs/create?url=1&title=2&key=3&appid=4

Where:

  1. The URL to be shortened. It should be URL encoded; required.
  2. Title of the URL to be used in the cligs list; optional. The user can edit this later in their control panel.
  3. The API key. If given it associates the new clig with a user account so that they can view the traffic statistics. If not given, then a Public clig is created. See below for more details.
  4. The AppID is a simple string, HTML allowed, that identifies your App when the API usage is listed in the user’s control panel. Keep it short and simple please.
  5. v1 is the version of the API. The current version will always work as described here.

The return is an just a URL on success or an error message on failure. HTTP headers will also be set on success and failure. On success, the standard HTTP 200 is returned. The following HTTP 40x and 50x errors will be returned if something goes wrong:

HTTP Header Message What it Means
HTTP 200 New Clig URL Enjoy :)
HTTP/1.0 404 Not Found Please specify a valid URL to shorten. The url parameter is missing, meaning you did not tell Cligs which URL you would like to shorten.
HTTP/1.0 403 Forbidden Please provide a valid application name to help Cligs users identify their usage. A valid appid is required if you are using the authenticated mode, i.e., if you provide an API key, you also need to provide an appid.
HTTP/1.0 404 Not Found Please provide a valid API key. If you want the clig to be public, simply do not specify a key. You provided an API key but it’s not valid. It might be disabled or deleted.
HTTP/1.0 500 Internal Server Error There was a server problem creating the clig. You broke Cligs! Seriously, something is wrong on the server. Try again just once, and if that also fails, please back off.

/cligs/expand

The expand function enables to get the destination URL of a clig, i.e., the long URL version of the clig short URL. It takes only one parameter, namely the clig you’d like to expand:

http://cli.gs/api/v1/cligs/expand?clig=1

Where:

  1. The clig to expand. This can be any of the following:
    • A valid clig ID, like Ts8p6Y
    • A clig URL, like http://cli.gs/Ts8p6Y
    • A URL-encoded clig URL like http%3A%2F%2Fcli.gs%2FTs8p6Y

On success, it return an HTTP 200 header with the long destination URL in the body. On error, it returns the following header-message combinations:

HTTP Header Message What it Means
HTTP/1.0 404 Not Found Please specify a valid clig ID to expand. Either specify a clig to expand as explained above, or the specified clig is invalid. This is most likely a mistyped clig.
HTTP/1.0 404 Not Found Unknown clig ID. Don’t know what you’re talking about. The clig is not in the database or it was deleted.
HTTP/1.x 500 Internal Server Error There was a server problem retrieving the clig’s URL. Something is wrong on the server. Try again just once, and if that also fails, please back off.

Leave a Reply