General
The <apu.sh> API offers third parties a way to programmatic interact with our service.
Prerequisites
The only thing you will need to access the API is a valid and active user account at <apu.sh>.
You can get one here: Sign Up Now!
API URL
The main URL of the API is:
https://api.apu.sh/
NOTE: Please notice that we only offer API access through SSL secured HTTPS connections!
We are using a SSL certificate from COMODO:
Authentication
The <apu.sh> API uses HTTP Basic Authentication
To access the API it is mandatory to always supply your username and password as query parameter
'uid=<your username>&pwd=<your password>'
Methods
Currently we offer two methods of creating pushed URLs using our API!
The first one is using the simple API interface at:
https://api.apu.sh/push_simple.ashx
The second one is using the JSON API interface at:
https://api.apu.sh/push_json.ashx
Simple Method
The simple API method is best suited if your client application cannot handle the JSON format.
If everything goes right you get the HTTP Status 200 together with the newly created pushed URL as plain text back.
If something goes wrong you get the HTTP Status 500 together with some details as plain text back.
JSON Method
The JSON API method is best suited if your client application can handle the JSON format because you will get additional information about your push request.
If everything goes right you get the HTTP Status 200 together with the newly created pushed URL as a JSON object back.
If something goes wrong you get the HTTP Status 500 together with some details as a JSON object back.
JSON Data Structure
The general JSON structure looks like that:
{
"ResultCode":0,
"ResultMessage":"Url was successfully pushed!",
"Push": {
"TargetUrl":"http://www.google.de",
"ShortUrl":"tm"
}
}
Name |
Description |
Type |
| ResultCode |
Defines the result of the operation (see section Status/Error Codes) |
Integer |
| ResultMessage |
Additional text for the result of the operation |
String |
| Push |
The push object containing the details about the orignal and the shortened URL |
Object |
| TargetURL |
The original URL which was supplied via the 'url' parameter |
string |
| ShortURL |
The generated short URL |
string |
NOTE: If the operation fails, the structure will NOT contain any Push object data!
Sample for failed method call:
{
"ResultCode":-32,
"ResultMessage":"Credentials invalid",
"Push": {}
}
Parameters
Both API methods share the same parameters.
| Name |
Description |
Optional |
Restrictions |
| uid |
Your apu.sh account username |
No |
|
| pwd |
Your apu.sh account password |
No |
|
| url |
The long URL to push |
No |
URL encoded string, Max. 4000 characters |
| custom |
If provided, we will try to use this custom URL when creating the pushed URL |
Yes |
Max. 20 characters |
| pass |
If provided, vistors of the pushed URL will have to provide this secret passcode to access the target URL |
Yes |
Max. 10 characters |
| period |
If provided this parameter defines the period the new pushed URL will be active |
Yes |
Valid values are:
0 = Always
1 = 1 hour
2 = 12 hours
3 = 24 hours
4 = 7 days
5 = 28 days
|
Status/Error Codes
All API Operations will return one of the following result codes:
| Code |
Description |
| 0 |
Success |
| 1 |
Success, but Target URL was already shortened! |
| -1 |
Failed! System error |
| -2 |
Failed! Custom URL already in use |
| -3 |
Failed! Custom URL already in use |
| -4 |
Failed! Invalid URL |
| -5 |
Failed! Invalid custom URL |
| -6 |
Failed! Invalid passcode |
| -20 |
Failed! Domain on Spam-List |
| -21 |
Failed! URL on Spam-List |
| -30 |
Failed! Username missing |
| -31 |
Failed! Password missing |
| -32 |
Failed! Credentials invalid |
Samples:
The minimum Simple API call:
https://api.apu.sh/push_simple.ashx?uid=username&pwd=pwd&url=www.loooongurl.com
The full featured Simple API call:
https://api.apu.sh/push_simple.ashx?uid=username&pwd=pwd&url=www.loooongurl.com&custom=longurl&pass=secret1234&period=3
The minimum JSON API call:
https://api.apu.sh/push_json.ashx?uid=username&pwd=pwd&url=www.loooongurl.com
The full featured JSON API call:
https://api.apu.sh/push_json.ashx?uid=username&pwd=pwd&url=www.loooongurl.com&custom=longurl&pass=secret1234&period=3