shlink/data/docs/rest.md

REST API documentation

Error management

Statuses:

• 400 -> controlled error
• 401 -> authentication error
• 500 -> unexpected error

[TODO]

Authentication

[TODO]

Language

In order to set the application language, you have to pass it by using the Accept-Language header.

If not provided or provided language is not supported, english (en_US) will be used.

Endpoints

Authenticate

REQUEST

• POST -> /rest/authenticate
• Params:
  • username: string
  • password: string

SUCCESS RESPONSE

{
    "token": "9f741eb0-33d7-4c56-b8f7-3719e9929946"
}

ERROR RESPONSE

{
    "error": "INVALID_ARGUMENT",
    "message": "You have to provide both \"username\" and \"password\""
}

Posible errors:

• INVALID_ARGUMENT: Username or password were not provided.
• INVALID_CREDENTIALS: Username or password are incorrect.

Create shortcode

REQUEST

• POST -> /rest/short-codes
• Params:
  • longUrl: string -> The URL to shorten
• Headers:
  • X-Auth-Token: string -> The token provided in the authentication request

SUCCESS RESPONSE

{
    "longUrl": "https://www.facebook.com/something/something",
    "shortUrl": "https://doma.in/rY9Kr",
    "shortCode": "rY9Kr"
}

ERROR RESPONSE

{
    "error": "INVALID_URL",
    "message": "Provided URL \"wfwef\" is invalid. Try with a different one."
}

Posible errors:

• INVALID_ARGUMENT: The longUrl was not provided.
• INVALID_URL: Provided longUrl has an invalid format or does not resolve.
• UNKNOWN_ERROR: Something unexpected happened.

Resolve URL

REQUEST

• GET -> /rest/short-codes/{shortCode}
• Route params:
  • shortCode: string -> The short code we want to resolve
• Headers:
  • X-Auth-Token: string -> The token provided in the authentication request

SUCCESS RESPONSE

{
    "longUrl": "https://www.facebook.com/something/something"
}

ERROR RESPONSE

{
    "error": "INVALID_SHORTCODE",
    "message": "Provided short code \"abc123\" has an invalid format"
}

Posible errors:

• INVALID_ARGUMENT: No longUrl was found for provided shortCode.
• INVALID_SHORTCODE: Provided shortCode does not match the character set used by the app to generate short codes.
• UNKNOWN_ERROR: Something unexpected happened.

List shortened URLs

REQUEST

• GET -> /rest/short-codes
• Query params:
  • page: integer -> The page to list. Defaults to 1 if not provided.
• Headers:
  • X-Auth-Token: string -> The token provided in the authentication request

SUCCESS RESPONSE

{
    "shortUrls": {
        "data": [
            {
                "shortCode": "abc123",
                "originalUrl": "http://www.alejandrocelaya.com",
                "dateCreated": "2016-04-30T18:01:47+0200",
                "visitsCount": 4
            },
            {
                "shortCode": "def456",
                "originalUrl": "http://www.alejandrocelaya.com/en",
                "dateCreated": "2016-04-30T18:03:43+0200",
                "visitsCount": 0
            },
            {
                "shortCode": "ghi789",
                "originalUrl": "http://www.alejandrocelaya.com/es",
                "dateCreated": "2016-04-30T18:10:38+0200",
                "visitsCount": 0
            },
            {
                "shortCode": "jkl987",
                "originalUrl": "http://www.alejandrocelaya.com/es/",
                "dateCreated": "2016-04-30T18:10:57+0200",
                "visitsCount": 0
            },
            {
                "shortCode": "mno654",
                "originalUrl": "http://blog.alejandrocelaya.com/2016/04/09/improving-zend-service-manager-workflow-with-annotations/",
                "dateCreated": "2016-04-30T19:21:05+0200",
                "visitsCount": 1
            },
            {
                "shortCode": "pqr321",
                "originalUrl": "http://www.google.com",
                "dateCreated": "2016-05-01T11:19:53+0200",
                "visitsCount": 0
            },
            {
                "shortCode": "stv159",
                "originalUrl": "http://www.acelaya.com",
                "dateCreated": "2016-06-12T17:49:21+0200",
                "visitsCount": 0
            },
            {
                "shortCode": "wxy753",
                "originalUrl": "http://www.atomic-reader.com",
                "dateCreated": "2016-06-12T17:50:27+0200",
                "visitsCount": 0
            },
            {
                "shortCode": "zab852",
                "originalUrl": "http://foo.com",
                "dateCreated": "2016-07-03T09:07:36+0200",
                "visitsCount": 0
            },
            {
                "shortCode": "cde963",
                "originalUrl": "https://www.facebook.com.com",
                "dateCreated": "2016-07-03T09:12:35+0200",
                "visitsCount": 0
            }
        ],
        "pagination": {
            "currentPage": 4,
            "pagesCount": 15
        }
    }
}

ERROR RESPONSE

{
    "error": "UNKNOWN_ERROR",
    "message": "Unexpected error occured"
}

Posible errors:

• UNKNOWN_ERROR: Something unexpected happened.

Get visits

REQUEST

• GET -> /rest/short-codes/{shortCode}/visits
• Route params:
  • shortCode: string -> The shortCode from which we eant to get the visits.
• Query params:
  • startDate: string -> If provided, only visits older that this date will be returned
  • endDate: string -> If provided, only visits newer that this date will be returned
• Headers:
  • X-Auth-Token: string -> The token provided in the authentication request

SUCCESS RESPONSE

{
    "shortUrls": {
        "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"
}

Posible errors:

• INVALID_ARGUMENT: The shortcode does not belong to any short URL
• UNKNOWN_ERROR: Something unexpected happened.