Shortener API

Shorten long URLs and deliver a great reading view with a single, unique URL using the Shortener API.
samson@readability:~/developers/api/shortener
#

Authentication

No Authentication is required.

Quick Start

Here's how to create a new shortened URL:

Request

POST /api/shortener/v1/urls
Content-Type: application/x-www-form-urlencoded

url=http://blog.arc90.com/2010/11/30/silence-is-golden/

Response

HTTP/1.0 200 OK

{
    "meta": {
        "url": "/api/shortener/v1/urls/tg8if9uj",
        "rdd_url": "http://rdd.me/tg8if9uj",
        "id": "tg8if9uj"
    },
    "messages": [
        "URL shortened."
    ],
    "success": true
}

Data Formats

All requests are provided as JSON.

Resources, Representations & Errors

Resources

/

Methods

GET

Retrieve the base API URI - information about subresources.

available response representations:

/urls?url

Methods

POST

Create a new Shortened URL.
request query parameters
parametervaluedescription

url

string (required)

The article URL to shorten.

available response representations:

potential faults:

/urls/{url_id}

Methods

GET

Retrieve a single shortened URL.

available response representations:

potential faults:

Representations

Example root representation. (application/json)

{
    "resources": {
        "urls": {
            "href": "/api/shortener/v1/urls",
            "description": "The URLs endpoint. POST a URL to add it to the shortener"
        }
    }
}
            

Example Successful URL creation response. (application/json)

{
    "meta": {
        "url": "/api/shortener/v1/urls/tg8if9uj",
        "rdd_url": "http://rdd.me/tg8if9uj",
        "id": "tg8if9uj"
    },
    "messages": [
        "URL shortened."
    ],
    "success": true

Example URL representation. (application/json)

{
    "meta": {
        "article": {
            "url": "http://blog.arc90.com/2010/11/30/silence-is-golden/",
            "author": "Tim Meaney",
            "excerpt": "It is a mostly well-known fact, yet nearly...",
            "word_count": 1126,
            "title": "Silence is Golden"
        },
        "rdd_url": "http://rdd.me/tg8if9uj",
        "id": "tg8if9uj",
        "full_url": "http://readability.com/articles/tg8if9uj"
    },
    "messages": [
        "Article found."
    ],
    "success": true
}

Errors

500 Internal Server Error (application/json)

An unknown error has occurred.

404 Not Found (application/json)

The resource that you requested does not exist.