URL Shortening API Documentation
Overview
The URL Shortening API enables authenticated users to convert long URLs into short, user-friendly links. It includes built-in rate limiting (100 requests per 24 hours per API key) and error handling to ensure smooth integration into your applications.
Base Production URL:
https://4n.eco
Authentication
All API requests must be authenticated using a valid API key.
Header Name:
x-api-key
Header Value: Your API key (e.g.,
<YOUR_API_KEY>
)
Keep your API key secure and do not expose it publicly.
Endpoint
GET /api/shorten-public
This endpoint shortens a provided URL. You may supply an optional custom alias; if omitted, an alias will be automatically generated.
Query Parameters
originalUrl (required) The long URL that you wish to shorten.
alias (optional) A custom alias for the shortened URL. Note: If the alias is already in use, the API returns an error.
Request Examples
1. Using a Custom Alias
cURL (Single Line - Windows/Unix):
curl -X GET "https://4n.eco/api/shorten-public?originalUrl=https://www.google.com&alias=mycustomalias" -H "x-api-key: <YOUR_API_KEY>"
Expected Response (HTTP 200):
{
"shortenedUrl": "https://4n.eco/mycustomalias"
}
2. Using an Auto-Generated Alias
cURL:
curl -X GET "https://4n.eco/api/shorten-public?originalUrl=https://www.google.com" -H "x-api-key: <YOUR_API_KEY>"
Expected Response (HTTP 200):
{
"shortenedUrl": "https://4n.eco/<generated_alias>"
}
Error Responses
Missing Required Parameter (originalUrl):
Response:
{ "error": "URL is required" }
HTTP Status: 400
Alias Already in Use:
Response:
{ "error": "Alias already in use. Try another alias." }
HTTP Status: 409
Invalid API Key:
Response:
{ "error": "Invalid API key" }
HTTP Status: 401
Rate Limit Exceeded:
Response:
{ "error": "API rate limit exceeded. Please try again later." }
HTTP Status: 429
Testing Scenarios
Below are sample cURL commands for testing various scenarios. Replace <YOUR_API_KEY>
with your actual API key when testing.
Valid Request with a Custom Alias
curl -X GET "https://4n.eco/api/shorten-public?originalUrl=https://www.google.com&alias=mycustomalias" -H "x-api-key: <YOUR_API_KEY>"
Valid Request Without Providing an Alias
curl -X GET "https://4n.eco/api/shorten-public?originalUrl=https://www.google.com" -H "x-api-key: <YOUR_API_KEY>"
Missing Required Parameter (originalUrl)
curl -X GET "https://4n.eco/api/shorten-public?alias=testalias" -H "x-api-key: <YOUR_API_KEY>"
Alias Already in Use
Step 1: Create a shortened URL
curl -X GET "https://4n.eco/api/shorten-public?originalUrl=https://www.google.com&alias=duplicatealias" -H "x-api-key: <YOUR_API_KEY>"
Step 2: Attempt to use the same alias again
curl -X GET "https://4n.eco/api/shorten-public?originalUrl=https://www.google.com&alias=duplicatealias" -H "x-api-key: <YOUR_API_KEY>"
Invalid API Key
curl -X GET "https://4n.eco/api/shorten-public?originalUrl=https://www.google.com&alias=invalidtest" -H "x-api-key: INVALID_API_KEY"
Rate Limiting (Optional Test)
Run this command repeatedly to simulate exceeding 100 requests in 24 hours:
curl -X GET "https://4n.eco/api/shorten-public?originalUrl=https://www.google.com&alias=ratelimittest" -H "x-api-key: <YOUR_API_KEY>"
Integration Examples
JavaScript (Using Fetch)
Integrate the API directly in your web application with a simple fetch request:
const shortenUrl = async (originalUrl, alias = '') => {
const url = new URL('https://4n.eco/api/shorten-public');
url.searchParams.append('originalUrl', originalUrl);
if (alias) {
url.searchParams.append('alias', alias);
}
try {
const response = await fetch(url.toString(), {
method: 'GET',
headers: {
'x-api-key': '<YOUR_API_KEY>'
}
});
if (!response.ok) {
const errorData = await response.json();
throw new Error(errorData.error);
}
const data = await response.json();
console.log('Shortened URL:', data.shortenedUrl);
return data.shortenedUrl;
} catch (error) {
console.error('Error shortening URL:', error.message);
}
};
// Example usage:
shortenUrl('https://www.google.com', 'mycustomalias');
Python (Using Requests)
Use Python's requests library to integrate the API into your backend application:
import requests
def shorten_url(original_url, alias=None):
base_url = 'https://4n.eco/api/shorten-public'
params = {'originalUrl': original_url}
if alias:
params['alias'] = alias
headers = {
'x-api-key': '<YOUR_API_KEY>'
}
response = requests.get(base_url, params=params, headers=headers)
if response.status_code == 200:
data = response.json()
print('Shortened URL:', data['shortenedUrl'])
return data['shortenedUrl']
else:
print('Error:', response.json()['error'])
return None
# Example usage:
shorten_url('https://www.google.com', 'mycustomalias')
Integration Notes
Error Handling: Check the HTTP status code and error messages in your integration code to handle errors gracefully.
Security: Never expose your API key in publicly accessible code. Use environment variables or secure storage.
Rate Limits: If your application might exceed 100 requests per day, implement retry logic or notify users of the limit.
Custom vs. Auto-Generated Alias: If you don’t require a specific alias, omitting the alias parameter allows the API to generate one automatically.
Conclusion
The URL Shortening API provides a straightforward and secure method to generate short URLs. With detailed error responses, built-in rate limiting, and flexible aliasing, developers can easily integrate this service into web or backend applications. For further assistance or to report issues, please contact our support team.
Last updated