{"id":48621161,"url":"https://github.com/zoph-io/url-shortener","last_synced_at":"2026-04-09T03:36:23.253Z","repository":{"id":153950997,"uuid":"507886011","full_name":"zoph-io/url-shortener","owner":"zoph-io","description":"serverless url-shortener","archived":false,"fork":false,"pushed_at":"2024-08-25T12:23:12.000Z","size":2223,"stargazers_count":8,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-08-25T18:25:05.730Z","etag":null,"topics":["aws","serverless","url-shortener"],"latest_commit_sha":null,"homepage":"https://zoph.io","language":"Python","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/zoph-io.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-06-27T11:45:18.000Z","updated_at":"2024-08-25T12:23:16.000Z","dependencies_parsed_at":null,"dependency_job_id":"6ec758c5-47b4-44e3-9e22-d40d068fe26b","html_url":"https://github.com/zoph-io/url-shortener","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/zoph-io/url-shortener","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zoph-io%2Furl-shortener","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zoph-io%2Furl-shortener/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zoph-io%2Furl-shortener/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zoph-io%2Furl-shortener/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zoph-io","download_url":"https://codeload.github.com/zoph-io/url-shortener/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zoph-io%2Furl-shortener/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31584809,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"online","status_checked_at":"2026-04-09T02:00:06.848Z","response_time":112,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["aws","serverless","url-shortener"],"created_at":"2026-04-09T03:36:22.142Z","updated_at":"2026-04-09T03:36:23.243Z","avatar_url":"https://github.com/zoph-io.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🔗 url-shortener\n\n## 🧠 Rationale\n\nThis _yet another url-shortener_, is the one I'm using for [AWS Security Digest Newsletter](https://awssecuritydigest.com) to track click rate from my readers.\n\nI wasn't able to find an existing solution that match my needs so I crafted my own version, another excuse to learn something new 🤓.\n\nTry out this AWS serverless url-shortener for your own usage and see the benefits it can bring.\n\nIt's perfect for shortening links and tracking analytics.\n\nPlus, contributions and pull requests are welcome.\n\n## 💡 Features\n\n1. `Create` API\n2. Companion static website (HTML + Javascript)\n - [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) and [CSP](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) compliant\n3. Hits counter + Analytics (Persisted in DynamoDB)\n\n## 🔋 Powered by\n\n- Lambda function (Python 🐍) + API Gateway\n- CloudFront + S3 + ACM\n- DynamoDB Table\n- CloudFormation + SAM\n\n## 📐 Schema\n\n![Architecture Schema](./assets/schema.drawio.png)\n\n## 🚀 Usage\n\n### Pre-requirements\n\n1. You will need to have an already issued AWS Certificate Manage (ACM) wildcard Certificate in `us-east-1` AWS region: `*.{your_domain}`\n2. Configure the proper parameters in the `Makefile` like the Route53 hosted zone Id (`HostedZoneId`)\n\n#### 🎛 Parameters\n\n| Parameters | Default Value | Description |\n| --------------- | ----------------- | --------------------------------------------------------------- |\n| Product | `url-shortener` | Product Name |\n| Project | `zophio` | Project Name |\n| Environment | `dev` | Environment Name |\n| MinChar | `3` | Minimum characters for the random shortened link id |\n| MaxChar | `3` | Maximum characters for the random shortened link id |\n| Domain | `zoph.io` | Desired Domain (must be linked to the `HostedZoneId` Parameter) |\n| SubDomain | `shortener` | Desired subdomain of the API |\n| HostedZoneId | `Required` | AWS Route53 `HostedZoneId` where your domain name belongs |\n| FallbackUrl | `https://zoph.io` | When the url does not exist, fallback url |\n| CertificateArn | `Required` | Arn of the Wildcard ACM Certificate (`us-east-1`) |\n| AWSRegion | `eu-west-1` | AWS Region |\n| AlertsRecipient | `Required` | Email of the recipient of CloudWatch Alarms |\n\n### Deployment\n\n $ make deploy\n $ make setup_front\n\n### How to shorten urls?\n\n#### Using Companion Static Website\n\nGo to the following website after the deployment (depends on your parameters :point_up_2:)\n\nDemo:\n\n[![DemoWebsite](assets/demo-website.png)](https://short.zph.app)\n\n- `https://short.{Domain}`\n\n#### Using the `Makefile`\n\n $ make url 'https://google.com'\n\n\u003e ℹī¸ Simple quotes are important\n\n#### Using `cURL`\n\n```bash\ncurl -X POST https://{subdomain}.{domain}/create/ \\\n--header \"Content-Type: application/json\" \\\n-d '{\"long_url\": \"https://google.com\"}'\n```\n\nOptionnaly, you can change the default TTL value (7 days), by using the `ttl_in_days` attribute in body request:\n```bash\ncurl -X POST https://{subdomain}.{domain}/create/ \\\n--header \"Content-Type: application/json\" \\\n-d '{\"long_url\": \"https://google.com\", \"ttl_in_days\": 365}'\n```\n\nOptionnaly, you can ask for a _human readable_ (`false` by default) short id, ie a suite of consonants/vowels, easier to read/remember.\n\n```bash\ncurl -X POST https://{subdomain}.{domain}/create/ \\\n--header \"Content-Type: application/json\" \\\n-d '{\"long_url\": \"https://google.com\", \"ttl_in_days\": 3, \"human_readable\": true}'\n\n```\n\nResponse:\n```json\n{\n \"short_id\": \"baho\", \n \"created_at\": \"2024-08-24T15:28:04\", \n \"ttl\": 1724772484, \n \"short_url\": \"https://{subdomain}.{domain}/baho\", \n \"long_url\": \"https://google.com\"\n}\n\n```\n\n\u003e **Note**: the generated short id is lowercase to avoid any human mistake.\n\n##### Response sample\n\n```json\n{\n \"created_at\": \"2023-01-17T13:37:00\",\n \"long_url\": \"https://zoph.io\",\n \"short_id\": \"dBC\",\n \"short_url\": \"https://{subdomain}.{domain}/dBC\",\n \"ttl\": 1674561936\n}\n```\n\n## 📖 Reference\n\n- [Blog post](https://blog.ruanbekker.com/blog/2018/11/30/how-to-setup-a-serverless-url-shortener-with-api-gateway-lambda-and-dynamodb-on-aws/)\n- [Makefile](https://itecnote.com/tecnote/r-how-to-pass-argument-to-makefile-from-command-line/)\n- [CloudFront stack](https://github.com/aws-samples/amazon-cloudfront-secure-static-site/tree/master)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzoph-io%2Furl-shortener","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzoph-io%2Furl-shortener","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzoph-io%2Furl-shortener/lists"}