We (will) speak many languages
Our programmers love to interact with people, but our service prefers to interact with machines! We will soon offer a RESTful API that is useful if you want to develop other plugins or simply if you want to have fun surfing over the HTTP layer.
Our servers will be glad to respond to your requests. You can have the answer packed using one of the following application formats: YAML, JSON, XML, and Pickle.
Notice
A full-fledged API will be released soon: please consider this as a beta release!
The beta API
- Handlers
- Variables
- Example: retrieving the full list of services
- Parameters accepted in GET or POST requests
- Example: squeezing a given (long) URL
- Example: expanding a given short URL
- Example: analyze a given short URL
- Example: sending asynchronous requests via JavaScript
Handlers
The handlers exposed can be invoked by sending an HTTP request to the following URLs:
/api/{auth?}/{handler}[/format/(json|xml|yaml|pickle)/]
At the moment we support the following handlers:
- retrieving the full list of services: {handler} = services
- squeezing a given URL : {handler} = squeeze
- expanding a given short URL : {handler} = expand
- analyzing a given short URL : {handler} = analyze
Variables
- {auth?} (optional)
- Just put auth as a value if you want to go through a basic HTTP authentication. You need an account, of course: please contact us
- {handler}
- The handler that you want to invoke. Valid values are services, expand, and analyze
Example: retrieving the full list of services
To retrieve the full list of services in JSON, make a GET request to:
http://long-shore.com/api/services/format/json/
By default responses will be emitted in JSON, thus you can use the following shortcut:
http://long-shore.com/api/services/
You can easily test this handler with cURL (or your favorite browser):
$ curl -i http://long-shore.com/api/services/
Date: Sun, 28 Mar 2010 21:41:10 GMT
Vary: Authorization, Accept-Language, Accept-Encoding
Content-Type: application/json; charset=utf-8
Content-Language: en-US
[
{
"regexp": "([a-zA-Z0-9\-_]+)$",
"domain": "0rz.tw"
},
{
"regexp": "([a-zA-Z0-9\-_]+)$",
"domain": "2tu.us"
},
{
"regexp": "([a-zA-Z0-9\-_]+)$",
"domain": "3.ly"
},
{
"regexp": "([a-zA-Z0-9\-_]+)$",
"domain": "301url.com"
...]
Parameters accepted in GET or POST requests
Our handlers accept the following parameters. In case you submit invalid values, we make an effort to fail gracefully.
- url (required, optional only if {handler} = services)
- Must be sent via GET and indicates the URL that you want to expand or analyze.
- long_url (required for {handler} = squeeze)
- Must be sent via POST and indicates the URL that you want to squeeze.
- abuse (optional)
- Set this parameter to any value to report that a certain short URL is suspicious.
- client (optional)
- Set this parameter to one of the following values: firefox, chrome, other, api-client.
- referrer (optional)
- You may want to tell us the page you found the short URL in. This is useful if you are developing a plugin that sends AJAX requests as they normally do not propagate the referrer.
If no client is specified, the default api-client will be applied. Thus, if you have developed, say, an add-on for Firefox, you would like to tell this to us so, if needed, we can tune the response accordingly. This flag is not really used at the moment and it's there just for future enhancement.
Example: squeezing a given (long) URL
To squeeze a given (long) URL, make a POST request to:
http://long-shore.com/api/squeeze/format/json/
Remember to pass the URL as POST! If the response status code is 200 OK, the response body will contain:
$ curl -i -d "long_url=http://www.google.com" http://long-shore.com/api/squeeze/
HTTP/1.0 200 OK
Date: Fri, 26 Mar 2010 15:25:15 GMT
Vary: Authorization, Accept-Language, Cookie
Content-Type: application/json; charset=utf-8
Content-Language: en-US
{
"url": "http://sqze.it/uIQAX",
"long_url": "http://www.google.com/"
}
And if you don't like the default JSON format, just use xml, pickle, or yaml.
$ curl -i -d "long_url=http://www.google.com" http://long-shore.com/api/squeeze/format/xml/
HTTP/1.0 200 OK
Date: Fri, 26 Mar 2010 15:26:35 GMT
Vary: Authorization, Accept-Language, Cookie
Content-Type: text/xml; charset=utf-8
Content-Language: en-US
<?xml version="1.0" encoding="utf-8"?>
<response>
<url>http://sqze.it/ahY44</url>
<long_url>http://www.google.com/</long_url>
</response>
An invalid URL or a bad request will result in the following output:
$ curl -i -d "long_url=http://www.google.c" /api/squeeze/
HTTP/1.0 400 BAD REQUEST
Date: Fri, 26 Mar 2010 15:23:17 GMT
Vary: Authorization, Accept-Language, Cookie
Content-Type: text/html; charset=utf-8
Content-Language: en-US
The response body may contain some more verbose explanation of the error in HTML but this is not guaranteed.
Example: expanding a given short URL
To expand a given short URL, make a POST request to:
http://long-shore.com/api/expand/
If the response status code is 200 OK, the response will contain the expnaded URL.
$ curl -i -d 'url=http://bit.ly/dunno' 'http://long-shore.com/api/expand'
HTTP/1.0 200 OK
Date: Sun, 28 Mar 2010 22:15:32 GMT
Vary: Authorization, Accept-Language
Content-Type: application/json; charset=utf-8
Content-Language: en-US
{
"url": "http://bit.ly/dunno",
"long_url": "http://shorttext.com/tfd2t81u5"
}
This expands the short URL without going any further (i.e., we will not follow more than one redirect).
Example: analyze a given short URL
Should you want a deeper expansion, you really want to run an analysis. This takes more time than a regular expansion, altough it's pretty fast.
$ curl -i -d 'url=http://bit.ly/dunno' 'http://long-shore.com/api/analyze'
HTTP/1.0 200 OK
Date: Sun, 28 Mar 2010 22:19:16 GMT
Vary: Authorization, Accept-Language, Accept-Encoding
Content-Type: application/json; charset=utf-8
Content-Language: en-US
{
"content_length": 15296,
"title": "Flachküste An einer Flachküste geht das - shortText.com",
"url": "http://bit.ly/dunno",
"destination": "http://shorttext.com/tfd2t81u5",
"long_url": "http://shorttext.com/tfd2t81u5",
"content_type": "text/html"
}
Example: sending asynchronous requests via JavaScript
Clearly, any HTTP client will be able to talk to our API. Here is a very quick example that uses JavaScript.
<html>
<head>
<!-- let's use Google's bandwidth and storage ;) -->
<script src="http://www.google.com/jsapi"></script>
<!-- here is the core -->
<script>
/* load jQuery */
google.load("jquery");
/* when the DOM is fully loaded */
$(document).ready(function(){
$.post(
/* this is the API URL */
'http://long-shore.com/api/squeeze/',
/* POST parameters go here */
{long_url: 'http://www.google.com'}
/* the callback function go here */
function(data) {
alert(data);
},
/* this is the expected format */
'json'
);
});
</script>
</head>
<head>
<body>
<p>longSHORE - The missing URL service</p>
</body>
</html>
You can use pretty much any HTTP library. Read more details about how this can be done with jQuery.
Encoding and content type
Responses will be always encoded in UTF-8. Our API tries to comply to the emitted format's natural content type. More precisely:
| Response format | Content type |
|---|---|
| JSON | application/json |
| XML | text/xml |
| YAML | application/x-yaml |
| Pickle | application/python-pickle |
Response codes
When calling these handlers, your client will return 200 OK only if everyghing worked fine. Otherwise, you should expect the following statuses:
| Status code | Description |
|---|---|
| 400 Bad Request | Request was malformed/not understood. |
| 401 Forbidden | Permission denied. |
| 404 Not found | Request to an unknown handler. |
| 409 Conflict/Duplicate | Object already exists. |
| 410 Gone | Object does not exist. |
| 501 Not Implemented | Action not available. |
| 503 Throttled | Request was throttled. |
Throttling
Anonymous (i.e., non-authenticated requests) may be throttled to avoid overloading. If you need an account please contact us.