{"id":38536659,"url":"https://github.com/ross/octodns-api","last_synced_at":"2026-01-17T07:02:52.871Z","repository":{"id":319213986,"uuid":"1073955283","full_name":"ross/octodns-api","owner":"ross","description":"Prototype/Proof of concept API for octoDNS. Also a deep dive expiriment into AI coding and workflows","archived":false,"fork":false,"pushed_at":"2025-12-16T17:44:15.000Z","size":73,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-03T00:40:27.258Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ross.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-10T22:22:07.000Z","updated_at":"2025-12-16T17:44:13.000Z","dependencies_parsed_at":"2025-10-18T13:04:42.919Z","dependency_job_id":"832d6111-05f3-41a5-a807-ea073a7b080f","html_url":"https://github.com/ross/octodns-api","commit_stats":null,"previous_names":["ross/octodns-api"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ross/octodns-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ross%2Foctodns-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ross%2Foctodns-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ross%2Foctodns-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ross%2Foctodns-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ross","download_url":"https://codeload.github.com/ross/octodns-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ross%2Foctodns-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28503021,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T06:57:29.758Z","status":"ssl_error","status_checked_at":"2026-01-17T06:56:03.931Z","response_time":85,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":[],"created_at":"2026-01-17T07:02:52.766Z","updated_at":"2026-01-17T07:02:52.859Z","avatar_url":"https://github.com/ross.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# octoDNS API - RESTful API for octoDNS\n\nA JSON web service API for interacting with [octoDNS](https://github.com/octodns/octodns/), allowing clients to perform CRUD operations on DNS records.\n\n## Features\n\n- RESTful JSON API for DNS management\n- Support for all octoDNS providers (Route53, Cloudflare, etc.)\n- API key authentication\n- Zone and record operations\n- Dry-run sync capabilities\n\n## Installation\n\n### From PyPI\n\n```bash\npip install octodns-api\n```\n\n### From source\n\n```bash\ngit clone https://github.com/octodns/octodns-api.git\ncd octodns-api\n./script/bootstrap\n```\n\n## Configuration\n\nCreate an octoDNS configuration file with API key configuration:\n\n```yaml\napi:\n  keys:\n    - name: admin\n      key: env/OCTODNS_API_KEY_ADMIN\n\nproviders:\n  route53:\n    class: octodns_route53.Route53Provider\n    access_key_id: env/AWS_ACCESS_KEY_ID\n    secret_access_key: env/AWS_SECRET_ACCESS_KEY\n\nzones:\n  example.com.:\n    sources:\n      - route53\n    targets:\n      - route53\n```\n\nSet environment variables:\n\n```bash\nexport OCTODNS_API_KEY_ADMIN=your-secure-random-key-here\nexport AWS_ACCESS_KEY_ID=your-aws-key\nexport AWS_SECRET_ACCESS_KEY=your-aws-secret\n```\n\n## Running the Server\n\n```bash\noctodns-api --config /path/to/config.yaml --host 127.0.0.1 --port 5000\n```\n\nOptions:\n- `--config`: Path to octoDNS configuration file (required)\n- `--host`: Host to bind to (default: 127.0.0.1)\n- `--port`: Port to bind to (default: 5000)\n- `--debug`: Enable debug mode\n\n## API Endpoints\n\nAll endpoints require authentication via `Authorization: Bearer \u003capi-key\u003e` header.\n\n### Zones\n\n#### List all zones\n```\nGET /zones\n```\n\nResponse:\n```json\n{\n  \"zones\": [\"example.com.\", \"example.org.\"]\n}\n```\n\n#### Get zone details\n```\nGET /zones/{zone}\n```\n\nResponse:\n```json\n{\n  \"name\": \"example.com.\",\n  \"decoded_name\": \"example.com.\",\n  \"records\": [\n    {\n      \"name\": \"www\",\n      \"type\": \"A\",\n      \"ttl\": 300,\n      \"values\": [\"1.2.3.4\"]\n    }\n  ]\n}\n```\n\n#### Sync zone\n```\nPOST /zones/{zone}/sync\nContent-Type: application/json\n\n{\n  \"dry_run\": true\n}\n```\n\n### Records\n\n#### List records in zone\n```\nGET /zones/{zone}/records\n```\n\n#### Get specific record\n```\nGET /zones/{zone}/records/{name}/{type}\n```\n\nExample:\n```\nGET /zones/example.com./records/www/A\n```\n\nResponse:\n```json\n{\n  \"name\": \"www\",\n  \"type\": \"A\",\n  \"ttl\": 300,\n  \"values\": [\"1.2.3.4\"]\n}\n```\n\n#### Create or update record\n```\nPOST /zones/{zone}/records\nContent-Type: application/json\n\n{\n  \"name\": \"www\",\n  \"type\": \"A\",\n  \"ttl\": 300,\n  \"values\": [\"1.2.3.4\"]\n}\n```\n\nResponse:\n```json\n{\n  \"record\": {\n    \"name\": \"www\",\n    \"type\": \"A\",\n    \"ttl\": 300,\n    \"values\": [\"1.2.3.4\"]\n  },\n  \"changed\": true\n}\n```\n\n#### Delete record\n```\nDELETE /zones/{zone}/records/{name}/{type}\n```\n\nResponse:\n```json\n{\n  \"deleted\": true\n}\n```\n\n## Authentication\n\nAPI keys are configured in the config file and can use environment variables:\n\n```yaml\napi:\n  keys:\n    - name: admin\n      key: env/OCTODNS_API_KEY_ADMIN\n    - name: readonly\n      key: env/OCTODNS_API_KEY_READONLY\n```\n\nInclude the API key in requests:\n\n```bash\ncurl -H \"Authorization: Bearer your-api-key\" http://localhost:5000/zones\n```\n\n## Development\n\nSee the [/script/](/script/) directory for development tools following the [Script to rule them all](https://github.com/github/scripts-to-rule-them-all) pattern.\n\n### Setup\n\n```bash\n./script/bootstrap\n```\n\n### Run tests\n\n```bash\n./script/test\n```\n\n### Linting\n\n```bash\n./script/lint\n```\n\n### Formatting\n\n```bash\n./script/format\n```\n\n## Security Considerations\n\n- Always use HTTPS in production\n- Store API keys in environment variables, not in config files\n- Use strong, randomly generated API keys (32+ characters)\n- Restrict network access to the API server\n- Consider placing behind a reverse proxy with rate limiting\n\n## License\n\nMIT License - see LICENSE file for details\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fross%2Foctodns-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fross%2Foctodns-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fross%2Foctodns-api/lists"}