aws3.link URL Shortener API
Table of Content
Subscribe on AWS Marketplace
Code samples
API endpoint: Shorten
API endpoint: Remove
API endpoint: Track
API endpoint: Usage
Custom Domain Integration
Troubleshooting
Subscribe on AWS Marketplace
Navigate to our product listing on the AWS Marketplace. Select the "View purchase options" button to proceed.
On the following page, click the "Subscribe" button to initiate the subscription process.
After subscribing, you will need to set up your account on our platform. Do this by clicking the "Set up your account" link provided.
You will be directed to the registration page. Here, fill in your account details in the provided fields. Once you have entered all necessary information, click the 'Subscribe' button to proceed.
Upon successful registration, your unique API key will be displayed. It is crucial to store this key in a secure location for future use.
Code samples
The following code samples creates a short URL with a random key. The link gets expired after 24 hours. Replace <YourApiKey> with the actual API Key you received during the sign-up process:
var client = new RestClient("https://api.aws3.link/shorten");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("x-api-key", "<YourApiKey>");
request.AddHeader("Content-Type", "application/json");
var body = @"{" + "\n" +
@" ""longUrl"": ""https://www.silverlining.cloud/docs/aws/aws3""," + "\n" +
@" ""expireHours"": 24" + "\n" +
@"}";
request.AddParameter("application/json", body, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);URL Shortener Playground
This API Playground for our URL shortener enables you to interact with the API directly from your browser. Whether you're a developer aiming to integrate URL shortening into your application or simply exploring its functionality, the playground offers a hands-on experience to send real API requests and view responses instantly.
By default, the demo environment allows access to the aws3-demo.link domain. If you're already subscribed, you can pass your API key to access additional public domains such as aws3.link, azr.link, goog.link, and an.si, or even integrate your own custom domain with our shortener service.
Experiment with various parameters and explore how the API responds to different scenarios!
"To see the result, please send a request to the API."
API endpoint: Shorten
URL endpoint: https://api.aws3.link/shorten
Method: POST
"header": {
"x-api-key": STRING,
"Content-Type": "application/json"
}
"body": {
"longUrl": STRING,
"customSlug": STRING,
"expireHours": NUMBER,
"expireClicks": NUMBER
"slugLength": STRING,
"customDomain": STRING
}
Required
"longUrl": The destination URL to which you want to redirect. The protocol (e.g., http, https) must be included. The maximum supported length is 2000 characters.
Optional
"customSlug": Define a custom slug ("aws3.link/customSlug"). Passing no customSlug will generate a random string as slug.
"expireHours": Define after how many hours the shortened URL will expire. Needs to be between 1 and 8760 (= 1 year). Default is 0, which means non-expiring link.
"expireClicks": Define after how many clicks the shortened URL will expire. Needs to be between 1 and 100. Default is 0, which means non-expiring link.
"slugLength": This parameter allows you to define the length of the randomly generated slug. It can be set to any value between 4 and 8. If not specified, the default length is set to 6 characters.
"customDomain": Pass the domain name you want to shorten your URL. Please see paragraph 'Custom domain integration' below before using it.
Public facing custom domain: an.si - Try it out by passing 'an.si' to customDomain parameter.
Response:
"body": {
"shortUrl": STRING,
"metadata": {
"longUrl": STRING,
"domain": STRING,
"slug": STRING,
"expiration": DATE,
}
}API endpoint: Remove
URL endpoint: https://api.aws3.link/remove
Method: POST
"header": {
"x-api-key": STRING,
"Content-Type": "application/json"
}
"body": {
"slug": STRING,
"customDomain": STRING
}
Required
"slug": The slug of the short URL you want to delete. 'mySlug' for aws3.link/mySlug e.g.
Optional
"customDomain": If you are using a custom domain, specify to which domain the provided key belongs to.
Response:
"body": {
"message": "Provided key has been removed",
"metadata": {
"longUrl": STRING,
"domain": STRING,
"slug": STRING
}
}API endpoint: Track
URL endpoint: https://api.aws3.link/track
Method: POST
"header": {
"x-api-key": STRING,
"Content-Type": "application/json"
}
"body": {
"slug": STRING,
"customDomain": STRING
}Required
"slug": The slug of the short URL you want to track. 'mySlug' for aws3.link/mySlug e.g.
Optional
"customDomain": If you are using a custom domain, specify to which domain the provided slug belongs to.
Response:
"body": {
"totalHits": NUMBER,
"hits": [{
"date": DATE,
"time": TIME,
"ip": STRING,
"method": STRING,
"resource": STRING,
"referrer": STRING,
"user": {
"platform": {
"name": STRING,
"version": STRING,
},
"os": {
"name": STRING,
},
"bot": BOOLEAN,
"flavour": {
"name": STRING,
"version": STRING,
},
"browser": {
"name": STRING,
"version": STRING
}
},
"rawUserAgent": STRING,
"timeTaken": FLOAT
}],
"metadata": {
"longUrl": STRING,
"domain": STRING,
"slug": STRING
}
}"totalHits": Number of successfully registered clicks
"hits: List of actual click. Consists of: date and time that URL was clicked, IP address click, referring URL and detailed information of the users device.
"metadata": Long URL, (custom) domain and key of the request
API endpoint: Usage
URL endpoint: https://api.aws3.link/usage
Method: POST
"header": {
"x-api-key": STRING,
"Content-Type": "application/json"
}Required
You must include the API key in the x-api-key header. The body parameters can be left empty.
Response:
"body": {
"reportUrl": STRING,
"downloadLink": STRING,
"description": STRING
}"reportUrl": A URL linking to a web-based report that displays all requests made to the API. Note that this report is only accessible if the total number of requests is below 100,000.
"downloadLink": A URL to download a .CSV file containing all requests made to our API using the specified API key.
"description": You can access usage statistics either by visiting the website using the 'reportUrl' or by downloading the usage data as a .csv file using the 'downloadLink'. Please note that, depending on the number of requests you have previously sent to our API, these links may become available up to 10 minutes after the request is made.
Custom Domain Integration
Leverage the full potential of our URL shortener service by utilizing your own domain, offering you a personalized and branded shortening experience. To begin this seamless integration, please ensure you follow these steps:
Subscription Requirement: Ensure you are enrolled in our "Pay-Per-Use" subscription plan, a prerequisite for accessing the custom domain functionality.
Custom Domain Acquisition: Visit the AWS Marketplace and subscribe to our "Custom Domain Add-On". This crucial step enables the custom domain feature for your account.
DNS Configuration: Upon successful subscription, we will contact you via email with the necessary DNS records. Adding these records to your domain's DNS settings is essential for linking your domain with our URL shortener and validating an SSL certificate to support HTTPS traffic.
API Endpoint Usage: After configuring your domain, you can make API calls with the customDomain parameter to our /shorten, /remove, and /tracking endpoints. This allows for smooth operations using your own domain.
Important Note: The responsibility of purchasing and maintaining the domain rests solely with the customer. Ensure your domain is active and properly configured to prevent any service disruptions.
By following these steps, you can enhance your URL shortening service with a custom domain, providing a more branded and professional appearance for your short links. Should you encounter any issues or have questions during the setup process, our support team is here to assist you.
Troubleshooting
"message": "Invalid Input: The request contains incorrectly formatted parameters"
This error message means that the body parameters you have passed are malformed. Please follow the instructions given in the endpoint descriptions. Common issues include forgetting to add a comma (',') after every parameter line or missing a parenthesis somewhere.
"message": "Endpoint request timed out"
You receive this error message when the code execution exceeds the maximum timeout (usually 29 seconds).
Batch Import of Shortened URLs
If you are currently using another URL shortening service and wish to import your existing shortened URLs to our platform, we offer support for batch imports. Please contact us at support@silverlining.cloud, and one of our engineers will assist you throughout the process.
Setting Up CNAME or A Record for the Apex of a Domain
When integrating your base domain (e.g., example.com) with our service, you may need to set a CNAME or A record to redirect to a URL at the apex of the domain. This step is not necessary if you only intend to integrate a subdomain (e.g., link.example.com) with our service.
Most domain registries (such as GoDaddy) do not allow setting a URL as the destination for the apex of a domain. However, there are workarounds to address this issue. We recommend using AWS Route 53, a DNS hosting service that allows you to configure the records as required by our setup. It offers a way to keep your domain registered with your current registry while managing the DNS through AWS. For guidance on integrating AWS Route 53 with your domain, please refer to this blog post: https://jryancanty.medium.com/domain-by-godaddy-dns-by-route53-fc7acf2f5580.
Alternatively, you can set up a redirection to our backend for the "www" subdomain and then redirect from the apex domain to the "www" subdomain. This approach can be implemented using a service like http://wwwizer.com.
How can I see my API usage and associated costs?
To view your past API usage, refer to the chapter about the /usage endpoint. This endpoint provides a CSV export of all API requests made.
To check the associated costs of your API usage, use the AWS Billing dashboard:
- Navigate to AWS Cost Management.
- In the left panel, select Cost Explorer.
- Use the cost filters on the right side. Under Legal entity, filter for SilverLining.Cloud.
How can I cancel my subscription?
To cancel your subscription, follow these steps:
- Go to the AWS Marketplace Console at https://aws.amazon.com/marketplace/library. Ensure that you are logged into the account that is subscribed to the product you want to cancel.
- Find the product you want to cancel and click on 'Manage.'
- Click on 'Actions' and then select 'Cancel subscription.'
For more detailed instructions, visit the AWS Marketplace Buyer Guide at https://docs.aws.amazon.com/marketplace/latest/buyerguide/cancel-subscription.html.