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.
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.
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 |
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 |
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 |
{
"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"
}
]
}
}
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 |
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 |
{
"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"
}
]
}
}
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.
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”). |
{
"success":true,
"error":null,
"data":null
}
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 |
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 | String | ✖ | 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. |
{
"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"
}
]
}
}
{
"success":false,
"error":{
"code":414,
"description":"This is not a valid url."
},
"data":null
}
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.