Getting Started

Welcome to our RESTful API!

Thank you for choosing our service. We are at the beginning of a long journey and if you choose to believe it, you are among of our first fellow travelers. So let’s make it together!

In this document, you get introduced how to create requests and process them in a very easy manner. We would strongly recommend you to read this document carefully and completely and, follow it. Thus you will understand this document easily.

First, it is discussed in general how to create requests and how to retrieve responses. In brief, we do accept ONLY JSON formatting using UTF-8 encoding and responses will have the same structures. Then the available methods are shown and finally, we will tell you our limitations. Please feel free to contact us at any time at [email protected]. We will be glad to hear your feedback.

Get API Keys

Please go and visit my account and get your API Keys. Please ensure that your email address has been confirmed. Otherwise, please confirm it here. API keys consist of a “client id” and a “client secret”. All methods except “add” require having API keys.

Please protect your API keys and NEVER share them with anyone. If you make requests using a wrong client secret, your API keys will be deactivated after 5 times and you need to change your API secret at my account.

Methods

All methods are HTTP POST methods and must have UTF-8 encoding. The base URL for all request is:

Property

Value

Base URL

https://api.ud.ht/v1

Type

POST

Encoding

UTF-8

The following methods are relative to the base URL:

Name

Complete URL

Functionality

/add

https://api.ud.ht/v1/add

Create a shortened URL

/list

https://api.ud.ht/v1/list

Get your shortened URLs

/hide

https://api.ud.ht/v1/hide

Discharge yourself from a shortened URL

/add

This method creates shortened URLs and work for both anonymous and signed users. If you provide your API keys correctly, the shortened URLs will be shown to you on the website. Here is the base request that should be created:

Property

Value

Base URL

https://api.ud.ht/v1/add

Type

POST

/add Request Variables

Variable

Type

Optional

Description

client_id

String

Your client id

client_secret

String

Your client secret

my_url

String

URL that needs to be shortened

Sample of “/add” method successful response

  • current_length” and “start” are always equal to 1.
  • Total length
    • If API keys provided the number of all shortened urls by the user considering the request.
    • If API keys NOT provided It would be always equal to 1.

{  
   "success":true,
   "error":null,
   "data":{  
      "total_length":1,
       "current_length":1,
      "start":1,
      "items":[  
         {  
            "id":"gLlK",
            "url_text":"https://github.com/UDight/api",
            "shortened_url":"http://ud.ht/gLlK",
            "clicks":0,
            "date":"2017-02-18 08:30:28 UTC"
         }
       ]
   }

/list

This method lists shortened URLs of signed users based on the result start number and length. The base request that should be created as following:

Property

Value

Base URL

https://api.ud.ht/v1/list

Type

POST

/list Request Variables

Variable

Type

Optional

Default value

Description

Limitation

client_id

String

-

Your client id

-

client_secret

String

-

Your client secret

-

start

Integer

1

The starting number of results

Minimum is 1 and should not be more than the number of shortened URLs by the user.

length

Integer

5

The result length

Minimum: 1

Maximum: 10

Sample of Successful Response of “/list” Method

{  
   "success":true,
   "error":null,
   "data":{  
      "total_length":12,
      "current_length":2,
      "start":1,
      "items":[  
         {  
            "id":"gLlK",
            "url_text":"https://github.com/UDight/api",
            "shortened_url":"http://ud.ht/gLlK",
            "clicks":0,
            "date":"2017-02-18 08:30:28 UTC"
         },
         {  
            "id":"ud",
            "url_text":"http://udight.com/",
            "shortened_url":"http://ud.ht/ud",
            "clicks":2,
            "date":"2017-02-18 08:27:42 UTC"
         }
       ]
   }
}

/hide

The “/hide” method discharge you from shortened URLs that you submitted into the system. After disengaging from a shortened URL, it will be still available and working. However, it will be hidden from your shortened list FOREVER.

/hide Request Variables

 Variable

Type

Optional

Description

client_id

String

Your client id

client_secret

String

Your client secret

url_id

String

The URL id which is indeed the constructor of the corresponding shortened URL (e.g. the id of http://ud.ht/abcd is “abcd”).

Sample of Successful Response of “/hide” Method

  • data” is always null.

{  
   "success":true,
   "error":null,
   "data":null

}

Responses

Despite request variables which are subject to vary, UDight provides the same structure of responses for all methods regardless of the method action.

The response format is:

Variable

Type

Nullable

Description

success

Boolean

Indicating whether the method result is
successful or not

data

Array of object

Click here to see the complete format

error

Object

Click here to see the complete format

The data format is:

Variable

Type

Nullable

Description

total_length

Integer

Total number of results available for the user. If API keys are provided, it would be total number of shortened URLs.

current_length

Integer

Current number of items available in this response (Equals to number of items)

start

Integer

Start number of the current response

items

Array of URL objects

Click here to see the complete format

The format of an “item” in array of items is:

Variable

Type

Nullable

Description

id

String

Shortened URL id

url_text

String

Original URL that was shortened

shortened_url

Integer

Complete shortened URL

clicks

Integer

Number of clicks

date

datetime

Added date in UTC format

The “error” format is:

Variable

Type

Nullable

Description

code

Integer

Error code (Please see the list of errors)

description

String

The description of the error

And errors are:

Code

Description

401

The API keys are invalid.

403

Your account has been locked by the administrator. Contact [email protected].

404

This URL does not exist.

450

Maximum requests reached.

451

The provided id is not valid.

452

Your account has been confirmed yet. Confirm it at http://udight.com/confirm.

453

Your API keys are locked out because of several failed attempts. Change your API secret at http://udight.com/myaccount/api.

454

This is not a valid URL.

500

An internal error occurred.

Sample of Successful Response

{  
   "success":true,
   "error":null,
   "data":{  
      "total_length":12,
      "current_length":2,
      "start":1,
      "items":[  
         {  
            "id":"gLlK",
            "url_text":"https://github.com/UDight/api",
            "shortened_url":"http://ud.ht/gLlK",
            "clicks":0,
            "date":"2017-02-18 08:30:28 UTC"
         },
         {  
            "id":"ud",
            "url_text":"http://udight.com/",
            "shortened_url":"http://ud.ht/ud",
            "clicks":2,
            "date":"2017-02-18 08:27:42 UTC"
         }

      ]
   }
}


Sample of Error Response

{  
   "success":false,
   "error":{  
     "code":414,
      "description":"This is not a valid url."
   },
   "data":null
}

API Restrictions

Due to our limited resources, we have imposed some restrictions to incoming requests. We hope that you understand our conditions and we are making our best to keep our service running all the time.

Those restrictions are assgined to IPs and API Keys:

Type

Maximum number of requests

Time period

Anonymous requests

5

1 minute

Signed in requests

100

15 minutes

Requests from an IP

100

15 minutes

Udight reservers the rights to change them and as soon as we change them, we will make an announcement. If you have any issues with the API, please contact us at [email protected]. We will be glad to respond you as soon as possible.

Copied!