API Documentation

Endpoints

POST

/rest/authenticate

Perform a new authentication and get a token.
Body params
  • apiKey: string
API keys are generated from the CLI interface, by running the api-key:generate command.
SUCCESSFUL RESPONSE
                        {
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJTaGxpbms6djEuMS4wIiwiaWF0IjoxNDcwNTg5ODg5LCJleHAiOjE0NzExOTcwNzEsInN1YiI6ImF1dGgiLCJrZXkiOiIxIn0.idGejxATFkHvJ5z8fld3b3BzvJcvCYnrG6w3YHrcI58"
}
                    
ERROR RESPONSE
                        {
    "error": "INVALID_ARGUMENT",
    "message": "You have to provide a valid API key under the \"apiKey\" param name"
}
                    
Code Desc. Status
INVALID_ARGUMENT API key was not provided 400
INVALID_API_KEY The API key is incorrect, is disabled or has expired. 401
POST

/rest/short-codes

Create a new shortened URL and get the generated short code and short URL.
Body params
  • longUrl: string
  • tags: array
  • The URL that will be shortened.
  • An optional array of tags to apply to generated short URL.
SUCCESSFUL RESPONSE
                        {
    "longUrl": "https://www.facebook.com/something/something",
    "shortUrl": "https://doma.in/rY9Kr",
    "shortCode": "rY9Kr"
}
                    
ERROR RESPONSE
                        {
    "error": "INVALID_URL",
    "message": "Provided URL \"http://foo.com\" is invalid. Try with a different one."
}
                    
Code Desc. Status
INVALID_ARGUMENT The longUrl was not provided 400
INVALID_URL Provided longUrl has an invalid format or can't be resolved 400
UNKNOWN_ERROR Something unexpected happened 500
GET

/rest/short-codes/{shortCode}

Get the long URL behind provided short code.
Route params
  • shortCode: string
The short code we want to resolve.
SUCCESSFUL RESPONSE
                        {
    "longUrl": "https://www.facebook.com/something/something"
}
                    
ERROR RESPONSE
                        {
    "error": "INVALID_SHORTCODE",
    "message": "Provided short code \"abc123\" has an invalid format"
}
                    
Code Desc. Status
INVALID_ARGUMENT No URL was found for provided shortCode 404
INVALID_SHORTCODE Provided shortCode does not match the character set currently used by the app to generate short codes 400
UNKNOWN_ERROR Something unexpected happened 500
GET

/rest/short-codes

Get a paginated list of all the shortened URLs. The list contains 10 elements per page.
Query params
  • page: string
The page to list. Defaults to 1 if not provided.
SUCCESSFUL RESPONSE
                        {
    "shortUrls": {
        "data": [
            {
                "shortCode": "abc123",
                "originalUrl": "https://www.alejandrocelaya.com",
                "dateCreated": "2016-04-30T18:01:47+0200",
                "visitsCount": 4,
                "tags": []
            },
            {
                "shortCode": "def456",
                "originalUrl": "https://www.alejandrocelaya.com/en",
                "dateCreated": "2016-04-30T18:03:43+0200",
                "visitsCount": 0,
                "tags": []
            },
            {
                "shortCode": "ghi789",
                "originalUrl": "https://www.alejandrocelaya.com/es",
                "dateCreated": "2016-04-30T18:10:38+0200",
                "visitsCount": 0,
                "tags": []
            },
            {
                "shortCode": "jkl987",
                "originalUrl": "https://www.alejandrocelaya.com/es/",
                "dateCreated": "2016-04-30T18:10:57+0200",
                "visitsCount": 0,
                "tags": ["foo", "bar"]
            },
            {
                "shortCode": "mno654",
                "originalUrl": "https://blog.alejandrocelaya.com/2016/04/09/improving-zend-service-manager-workflow-with-annotations/",
                "dateCreated": "2016-04-30T19:21:05+0200",
                "visitsCount": 1,
                "tags": []
            },
            {
                "shortCode": "pqr321",
                "originalUrl": "https://www.google.com",
                "dateCreated": "2016-05-01T11:19:53+0200",
                "visitsCount": 0,
                "tags": []
            },
            {
                "shortCode": "stv159",
                "originalUrl": "https://www.acelaya.com",
                "dateCreated": "2016-06-12T17:49:21+0200",
                "visitsCount": 0,
                "tags": ["baz"]
            },
            {
                "shortCode": "wxy753",
                "originalUrl": "https://www.atomic-reader.com",
                "dateCreated": "2016-06-12T17:50:27+0200",
                "visitsCount": 0,
                "tags": []
            },
            {
                "shortCode": "zab852",
                "originalUrl": "http://foo.com",
                "dateCreated": "2016-07-03T09:07:36+0200",
                "visitsCount": 0,
                "tags": []
            },
            {
                "shortCode": "cde963",
                "originalUrl": "https://www.facebook.com.com",
                "dateCreated": "2016-07-03T09:12:35+0200",
                "visitsCount": 0,
                "tags": []
            }
        ],
        "pagination": {
            "currentPage": 4,
            "pagesCount": 15
        }
    }
}
                    
ERROR RESPONSE
                        {
    "error": "UNKNOWN_ERROR",
    "message": "Unexpected error occurred"
}
                    
Code Desc. Status
UNKNOWN_ERROR Something unexpected happened 500
GET

/rest/short-codes/{shortCode}/visits

Get the list of visits on provided short code.
Route params
  • shortCode: string
The shortCode from which we want to get the visits.
Query params
  • startDate: string
  • endDate: string
  • If provided, only visits older that this date will be returned.
  • If provided, only visits newer that this date will be returned.
SUCCESSFUL RESPONSE
                        {
    "visits": {
        "data": [
            {
                "referer": null,
                "date": "2016-06-18T09:32:22+0200",
                "remoteAddr": "127.0.0.1",
                "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/49.0.2623.87 Safari/537.36"
            },
            {
                "referer": null,
                "date": "2016-04-30T19:20:06+0200",
                "remoteAddr": "127.0.0.1",
                "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/49.0.2623.87 Safari/537.36"
            },
            {
                "referer": "google.com",
                "date": "2016-04-30T19:19:57+0200",
                "remoteAddr": "1.2.3.4",
                "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/49.0.2623.87 Safari/537.36"
            },
            {
                "referer": null,
                "date": "2016-04-30T19:17:35+0200",
                "remoteAddr": "127.0.0.1",
                "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/49.0.2623.87 Safari/537.36"
            }
        ],
    }
}
                    
ERROR RESPONSE
                        {
    "error": "INVALID_ARGUMENT",
    "message": "Provided short code \"abc123\" is invalid"
}
                    
Code Desc. Status
INVALID_ARGUMENT The short code does not belong to any short URL 404
UNKNOWN_ERROR Something unexpected happened 500
PUT

/rest/short-codes/{shortCode}/tags

Edit the tags on provided short code.
Route params
  • shortCode: string
The shortCode in which we want to edit tags.
Body params
  • tags: array
  • The list of tags to set to the short URL.
SUCCESSFUL RESPONSE
                        {
    "tags": [
        "foo",
        "some-tag",
        "bar"
    ]
}
                    
ERROR RESPONSE
                        {
    "error": "INVALID_ARGUMENT",
    "message": "A list of tags was not provided"
}
                    
Code Desc. Status
INVALID_ARGUMENT The request body does not contain a "tags" param with array type. 400
INVALID_SHORTCODE No URL was found for provided shortCode 404