{"id":18006759,"url":"https://github.com/jamesridgway/aws-lambda-short-url","last_synced_at":"2025-09-04T05:16:41.422Z","repository":{"id":93081236,"uuid":"132476054","full_name":"jamesridgway/aws-lambda-short-url","owner":"jamesridgway","description":"Use terraform to quickly setup your own Short URL generator using a custom domain with AWS API Gateway, CloudFront, Lambda, Route 53 and S3.","archived":false,"fork":false,"pushed_at":"2022-04-30T18:47:56.000Z","size":33,"stargazers_count":23,"open_issues_count":1,"forks_count":12,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-21T18:21:20.659Z","etag":null,"topics":["api-gateway","aws","cloudfront","lambda","route53","terraform"],"latest_commit_sha":null,"homepage":null,"language":"HCL","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jamesridgway.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGE.md","contributing":null,"funding":".github/funding.yml","license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"security_headers.tf","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"jamesridgway"}},"created_at":"2018-05-07T14:54:10.000Z","updated_at":"2025-03-03T11:26:50.000Z","dependencies_parsed_at":"2023-06-04T17:00:13.854Z","dependency_job_id":null,"html_url":"https://github.com/jamesridgway/aws-lambda-short-url","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamesridgway%2Faws-lambda-short-url","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamesridgway%2Faws-lambda-short-url/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamesridgway%2Faws-lambda-short-url/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamesridgway%2Faws-lambda-short-url/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jamesridgway","download_url":"https://codeload.github.com/jamesridgway/aws-lambda-short-url/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245653883,"owners_count":20650767,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-gateway","aws","cloudfront","lambda","route53","terraform"],"created_at":"2024-10-30T01:09:52.806Z","updated_at":"2025-03-26T12:30:56.686Z","avatar_url":"https://github.com/jamesridgway.png","language":"HCL","funding_links":["https://github.com/sponsors/jamesridgway"],"categories":[],"sub_categories":[],"readme":"# AWS Lambda Short URL Generator\n\nUse terraform to quickly setup your own Short URL generator using a custom domain with AWS API Gateway, CloudFront, Lambda, Route 53 and S3.\n\n## Approach\n\nThe plan is to use CloudFront to cache redirecting web pages at the edge of the CloudFront network that will redirect form the short URL to the full URL.\n\nThe redirecting web pages will be served up from S3. With S3 you can create an object with a meta data entry called `Website Redirect Location`. When an S3 bucket is configured to host a static website objects (with a `Website Redirect Location` metadata entry) will be served up over HTTP as a redirecting webpage.\n\n![AWS Lambda Short URL Generator - Approach Overview](https://www.jamesridgway.co.uk/content/images/2020/03/short-urls-approach.png)\n\nAPI Gateway and AWS Lambda will be used to create and delete shortlinks via HTTP API calls. The API will be protected with an API key, and will be served up via the same CloudFront distrubtion.\n\nFinally Route 53 will alias the custom domain name to the domain name of the CloudFront distribution.\n\n## Prerequisites\nSetup the domain that you want to use for your short URLs as a Hosted Zone in Route 53. Details of how to do this can be found [here](https://www.jamesridgway.co.uk/build-your-own-custom-short-url-generator-using-aws/).\n\n## Deploy\nInitialise the backend to use an S3 bucket to store the state (this only needs to be done once):\n```\n$ terraform init -backend-config \"bucket=terraform-states.example.com\"\n```\nAlternatively you can remove `terraform.tf` which defines the backend store - this will cause terraform to default to local file storage.\n\nUse terraform to apply the infrastructure change needed to run this short URL generator:\n\n```\n$ terraform apply\n```\n\nYou'll be prompted for:\n\n* The short URL domain you want to use (e.g. `example.com`)\n* Your AWS account number\n\nOnce the infrastrucutre has been created it will be given an output similar to the following:\n\n```\nOutputs:\n\nadmin_api_key          = uWyv6B1NPI0vWxVPeQD46ctlmWd6l7x3YLSYCRf0\ncloudfront_domain_name = d111111abcdef8.cloudfront.net\nshort_url_domain       = example.com\n```\n\n## Using the API\nDeploying the infrastructure with terraform will take only a few minutes and once the CloudFront distribution has been fully initialised you'll be ready to start creating URLs.\n\nThe following sections provide examples using `curl`. There is also a python-based CLI/library that you can use for interacting with the API:\n\n* [short-urls-client](https://github.com/jamesridgway/short-urls-client)\n\n### Creating a Short URL\n\nCreating a URL is done with a `POST` request to the `/admin` endpoint. The `x-api-key` header should be set to the `Admin API Key` value that was generated in the output of the terraform setup:\n\n```\ncurl -X POST \\\n\t-d '{\"url\": \"https://www.james-ridgway.co.uk/blog/build-your-own-custom-short-url-generator-using-aws\"}' \\\n\t-H \"x-api-key: XXXXX\" \\\n\thttp://exmple.com/admin\n```\n\nThe response will provide you with the full short URL and token value in JSON output:\n\n```\n{\n\t\"short_url\": \"https://example.com/cwM1iQ\",\n\t\"url\": \"https://www.james-ridgway.co.uk/blog/build-your-own-custom-short-url-generator-using-aws\",\n\t\"token\": \"cwM1iQ\"\n}\n```\n\n### Visit a Short URL\nSo here's an example of one of my short URL: [https://jmsr.io/cwM1iQ](https://jmsr.io/cwM1iQ). This link is a short link to my [Build your own custom Short URL generator using AWS](https://www.jamesridgway.co.uk/build-your-own-custom-short-url-generator-using-aws/) blog post.\n\nCloudFront serves up the empty S3 object as shown below using CURL with the vebose flag. You get a `301 Moved Permanently` response with the `Location` header set to the full URL.\n\n```\n$ curl -v https://jmsr.io/cwM1iQ\n*   Trying 54.192.197.16...\n* Connected to jmsr.io (54.192.197.16) port 443 (#0)\n* found 148 certificates in /etc/ssl/certs/ca-certificates.crt\n* found 597 certificates in /etc/ssl/certs\n* ALPN, offering http/1.1\n* SSL connection using TLS1.2 / ECDHE_RSA_AES_128_GCM_SHA256\n*        server certificate verification OK\n*        server certificate status verification SKIPPED\n*        common name: jmsr.io (matched)\n*        server certificate expiration date OK\n*        server certificate activation date OK\n*        certificate public key: RSA\n*        certificate version: #3\n*        subject: CN=jmsr.io\n*        start date: Mon, 07 May 2018 00:00:00 GMT\n*        expire date: Fri, 07 Jun 2019 12:00:00 GMT\n*        issuer: C=US,O=Amazon,OU=Server CA 1B,CN=Amazon\n*        compression: NULL\n* ALPN, server accepted to use http/1.1\n\u003e GET /cwM1iQ HTTP/1.1\n\u003e Host: jmsr.io\n\u003e User-Agent: curl/7.47.0\n\u003e Accept: */*\n\u003e \n\u003c HTTP/1.1 301 Moved Permanently\n\u003c Content-Length: 0\n\u003c Connection: keep-alive\n\u003c Date: Sat, 12 May 2018 08:36:48 GMT\n\u003c Location: https://www.james-ridgway.co.uk/blog/build-your-own-custom-short-url-generator-using-aws\n\u003c Server: AmazonS3\n\u003c X-Cache: Miss from cloudfront\n\u003c Via: 1.1 95a4581bed116b6338fc42595fee6f43.cloudfront.net (CloudFront)\n\u003c X-Amz-Cf-Id: s4q4k2DkWwc6jxNvA2XWQYK_wJC51_QDag2CucX-a67aq3si78_9Gw==\n\u003c \n* Connection #0 to host jmsr.io left intact\n```\n\n### Deleting a Short URL\n\nDeleting an endpoint is also done via a `DELETE` request to `/admin/\u003ctoken\u003e`, for example:\n\n```\ncurl -X DELETE -H \"x-api-key: XXXXX\" http://example.com/admin/cwM1iQ\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjamesridgway%2Faws-lambda-short-url","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjamesridgway%2Faws-lambda-short-url","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjamesridgway%2Faws-lambda-short-url/lists"}