ldraney/godaddy-sdk
1
0
Fork 0
Code Issues 4 Pull requests 1 Projects Releases Packages Wiki Activity Actions

Add docs/ with swagger specs, README TOC, and CLAUDE.md #5

Open
ldraney wants to merge 3 commits from 1-docs-swagger-specs into main
pull from: 1-docs-swagger-specs
merge into: ldraney:main
Conversation 1 Commits 3 Files changed 15 +18875 -1
ldraney commented 2026-06-13 14:58:10 +00:00
Owner
Copy link

Summary

  • Adds all 10 official GoDaddy Swagger 2.0 specs to docs/ (121 endpoints across 10 API groups)
  • README rewritten as table of contents with mermaid architecture and pipeline diagrams
  • CLAUDE.md symlinked to README for agent context
  • docs/api-groups.md — overview table with endpoint counts
  • docs/dns-endpoints.md — P0 DNS record management reference (6 endpoints, schema, rate limits)
  • docs/auth.md — credential setup guide for sso-key auth

Changes

  • README.md — full rewrite as TOC linking to docs/, includes mermaid diagrams, usage examples, API coverage table
  • CLAUDE.md — symlink to README.md
  • docs/api-groups.md — new, generated from swagger specs
  • docs/dns-endpoints.md — new, P0 DNS endpoint reference with SDK method mapping
  • docs/auth.md — new, credential setup and base URL reference
  • docs/swagger_*.json — all 10 official swagger specs

Test Plan

  • All 10 swagger JSON files parse correctly (python3 -c "import json; json.load(open('docs/swagger_domains.json'))")
  • api-groups.md links resolve to spec files
  • Mermaid diagrams render in Forgejo
  • CLAUDE.md symlink resolves correctly

Review Checklist

  • Passed automated review-fix loop
  • No secrets committed
  • No unnecessary file changes
  • Commit messages are descriptive
  • Feature flag needed? No — docs only

Related Notes

  • Closes #1 (docs portion of scaffold ticket)
  • project-godaddy-sdk — project page
  • Supports #2 (DNS mixin), #3 (Domains mixin), #4 (credentials)
## Summary - Adds all 10 official GoDaddy Swagger 2.0 specs to `docs/` (121 endpoints across 10 API groups) - README rewritten as table of contents with mermaid architecture and pipeline diagrams - CLAUDE.md symlinked to README for agent context - `docs/api-groups.md` — overview table with endpoint counts - `docs/dns-endpoints.md` — P0 DNS record management reference (6 endpoints, schema, rate limits) - `docs/auth.md` — credential setup guide for `sso-key` auth ## Changes - `README.md` — full rewrite as TOC linking to docs/, includes mermaid diagrams, usage examples, API coverage table - `CLAUDE.md` — symlink to README.md - `docs/api-groups.md` — new, generated from swagger specs - `docs/dns-endpoints.md` — new, P0 DNS endpoint reference with SDK method mapping - `docs/auth.md` — new, credential setup and base URL reference - `docs/swagger_*.json` — all 10 official swagger specs ## Test Plan - [ ] All 10 swagger JSON files parse correctly (`python3 -c "import json; json.load(open('docs/swagger_domains.json'))"`) - [ ] `api-groups.md` links resolve to spec files - [ ] Mermaid diagrams render in Forgejo - [ ] CLAUDE.md symlink resolves correctly ## Review Checklist - [ ] Passed automated review-fix loop - [ ] No secrets committed - [ ] No unnecessary file changes - [ ] Commit messages are descriptive - [ ] Feature flag needed? No — docs only ## Related Notes - Closes #1 (docs portion of scaffold ticket) - `project-godaddy-sdk` — project page - Supports #2 (DNS mixin), #3 (Domains mixin), #4 (credentials)
Provides the reference documentation for all subsequent SDK tickets (#1-#4).
121 endpoints across 10 API groups, sourced from developer.godaddy.com.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
README serves as table of contents linking to docs/ with architecture
and pipeline mermaid diagrams. CLAUDE.md symlinks to README so agents
pick up the same context. Adds docs/dns-endpoints.md (P0 reference)
and docs/auth.md (credential setup guide).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
ldraney commented 2026-06-13 15:03:31 +00:00
Author
Owner
Copy link

PR #5 Review

DOMAIN REVIEW

Tech stack: Documentation-only PR (Markdown, Mermaid diagrams, JSON swagger specs, symlink). No executable code to review for runtime correctness. Domain expertise applied: documentation quality, data accuracy, link integrity, security hygiene.

Endpoint Count Discrepancies (data accuracy)

The README and docs/api-groups.md both claim specific endpoint counts per API group, but spot-checking the actual swagger JSON files reveals mismatches:

Group Claimed Actual paths in swagger Delta
Abuse 6 4 -2
Certificates 29 26 -3
Domains 65 50 -15
Shoppers 6 4 -2
Subscriptions 5 3 -2

The claimed total of 121 endpoints appears to be ~97 based on actual path counts in the swagger files. This needs to be reconciled -- either the counting methodology should be documented (e.g., "each HTTP method on a path counts separately") or the numbers corrected.

"10 API groups" vs 11 table rows

The README intro says "10 API groups (121 endpoints)" but the API Coverage table has 11 rows. DNS (6 endpoints) and Domains (65 endpoints) are listed as separate rows but both link to swagger_domains.json. There is no swagger_dns.json. This is confusing -- DNS is a subset of the Domains spec, not a separate API group. Either:

  • Say "10 API groups" and merge DNS into the Domains row, or
  • Say "11 categories" and clarify DNS is carved out from the Domains spec for prioritization

docs/dns-endpoints.md -- SDK method names are speculative

The SDK Method column (get_records, replace_records, add_records, etc.) references methods that do not exist yet -- the SDK has no code. This is fine as forward-looking design docs, but should be labeled as "Planned SDK Method" to avoid confusion.

docs/api-groups.md -- thin descriptions

Every group description is just the group name restated ("Abuse API", "Domains API", "Certificates", "Orders"). These add zero information. Either pull actual descriptions from the swagger info.description fields or remove the Description column.

CLAUDE.md symlink

Symlink CLAUDE.md -> README.md is a clean approach. The symlink mode 120000 is correct. No missing newline at end of symlink target (expected for symlinks).

BLOCKERS

  1. Endpoint count inaccuracy across README.md, docs/api-groups.md, and PR body. The claimed counts do not match the actual swagger specs being committed in the same PR. Documentation that ships with incorrect numbers on day one erodes trust. Fix the counts or document the counting methodology that explains the discrepancy.

  2. "10 API groups" vs 11-row table inconsistency. The README intro and the table contradict each other. Pick one framing and apply it consistently across README.md and api-groups.md.

NITS

  1. docs/api-groups.md descriptions are redundant. "Abuse API" for the Abuse group adds nothing. Consider pulling the one-liner from each swagger spec's info.description field, or dropping the column.

  2. docs/dns-endpoints.md SDK Method column. Label as "Planned SDK Method" since no code exists yet.

  3. README Usage example references ~/secrets/godaddy/.env in Testing section. This is fine as documentation, but consider adding a note that this path is established by docs/auth.md -- a reader jumping to Testing without reading Auth will be confused.

  4. docs/dns-endpoints.md rate limit section is terse. "60 requests per minute per API key" -- is this documented in the swagger spec or observed? A source reference would help.

  5. docs/api-groups.md uses relative links (swagger_abuse.json). These resolve correctly from within docs/ but will break if the file is viewed from repo root in some renderers. The README table correctly uses docs/swagger_abuse.json. Consider making api-groups.md consistent -- though this is minor since Forgejo renders relative links correctly within the directory.

  6. Missing Countries mention. The architecture mermaid diagram lists a CountriesMixin but the api-groups table lists "Countries" without the Mixin suffix. Consistent naming is a nit but worth aligning.

SOP COMPLIANCE

  • Branch named after issue (1-docs-swagger-specs references issue #1)
  • PR body has ## Summary -- present, clear
  • PR body has ## Changes -- present, lists all files
  • PR body has ## Test Plan -- present with checkboxes
  • PR body has ## Review Checklist -- present
  • PR body has ## Related Notes -- present, references Closes #1 and related issues
  • No secrets committed (all credential references are placeholder examples: your_key_here, api_key="...")
  • No .env files committed (only documentation references to ~/secrets/godaddy/.env)
  • Commit messages are descriptive (single commit matching PR title)
  • No unnecessary file changes (all 15 files are docs-related, on scope)
  • Feature flag consideration -- N/A (docs only), correctly noted in checklist

PROCESS OBSERVATIONS

  • This is a pure documentation/reference PR with no executable code, so test coverage requirements do not apply. The test plan appropriately focuses on JSON validity and link resolution.
  • The PR cleanly scopes to the docs portion of issue #1 ("Scaffold godaddy-sdk repo with pyproject.toml, client, and docs"). The pyproject.toml and client scaffolding are presumably in a separate PR -- confirm this is intentional.
  • Good practice: swagger specs committed to the repo rather than referenced externally ensures reproducibility and offline development.

VERDICT: NOT APPROVED

Two blockers must be resolved before merge: (1) endpoint count discrepancies between documentation and actual swagger specs, and (2) the "10 groups" vs 11-row table inconsistency. Both are data accuracy issues in a documentation PR -- the one thing a docs PR must get right is the data.

## PR #5 Review ### DOMAIN REVIEW **Tech stack:** Documentation-only PR (Markdown, Mermaid diagrams, JSON swagger specs, symlink). No executable code to review for runtime correctness. Domain expertise applied: documentation quality, data accuracy, link integrity, security hygiene. **Endpoint Count Discrepancies (data accuracy)** The README and `docs/api-groups.md` both claim specific endpoint counts per API group, but spot-checking the actual swagger JSON files reveals mismatches: | Group | Claimed | Actual paths in swagger | Delta | |-------|---------|------------------------|-------| | Abuse | 6 | 4 | -2 | | Certificates | 29 | 26 | -3 | | Domains | 65 | 50 | -15 | | Shoppers | 6 | 4 | -2 | | Subscriptions | 5 | 3 | -2 | The claimed total of **121 endpoints** appears to be **~97** based on actual path counts in the swagger files. This needs to be reconciled -- either the counting methodology should be documented (e.g., "each HTTP method on a path counts separately") or the numbers corrected. **"10 API groups" vs 11 table rows** The README intro says "10 API groups (121 endpoints)" but the API Coverage table has **11 rows**. DNS (6 endpoints) and Domains (65 endpoints) are listed as separate rows but both link to `swagger_domains.json`. There is no `swagger_dns.json`. This is confusing -- DNS is a subset of the Domains spec, not a separate API group. Either: - Say "10 API groups" and merge DNS into the Domains row, or - Say "11 categories" and clarify DNS is carved out from the Domains spec for prioritization **`docs/dns-endpoints.md` -- SDK method names are speculative** The SDK Method column (`get_records`, `replace_records`, `add_records`, etc.) references methods that do not exist yet -- the SDK has no code. This is fine as forward-looking design docs, but should be labeled as "Planned SDK Method" to avoid confusion. **`docs/api-groups.md` -- thin descriptions** Every group description is just the group name restated ("Abuse API", "Domains API", "Certificates", "Orders"). These add zero information. Either pull actual descriptions from the swagger `info.description` fields or remove the Description column. **`CLAUDE.md` symlink** Symlink `CLAUDE.md -> README.md` is a clean approach. The symlink mode `120000` is correct. No missing newline at end of symlink target (expected for symlinks). ### BLOCKERS 1. **Endpoint count inaccuracy across README.md, docs/api-groups.md, and PR body.** The claimed counts do not match the actual swagger specs being committed in the same PR. Documentation that ships with incorrect numbers on day one erodes trust. Fix the counts or document the counting methodology that explains the discrepancy. 2. **"10 API groups" vs 11-row table inconsistency.** The README intro and the table contradict each other. Pick one framing and apply it consistently across README.md and api-groups.md. ### NITS 1. **`docs/api-groups.md` descriptions are redundant.** "Abuse API" for the Abuse group adds nothing. Consider pulling the one-liner from each swagger spec's `info.description` field, or dropping the column. 2. **`docs/dns-endpoints.md` SDK Method column.** Label as "Planned SDK Method" since no code exists yet. 3. **README Usage example references `~/secrets/godaddy/.env` in Testing section.** This is fine as documentation, but consider adding a note that this path is established by `docs/auth.md` -- a reader jumping to Testing without reading Auth will be confused. 4. **`docs/dns-endpoints.md` rate limit section is terse.** "60 requests per minute per API key" -- is this documented in the swagger spec or observed? A source reference would help. 5. **`docs/api-groups.md` uses relative links (`swagger_abuse.json`).** These resolve correctly from within `docs/` but will break if the file is viewed from repo root in some renderers. The README table correctly uses `docs/swagger_abuse.json`. Consider making api-groups.md consistent -- though this is minor since Forgejo renders relative links correctly within the directory. 6. **Missing `Countries` mention.** The architecture mermaid diagram lists a `CountriesMixin` but the api-groups table lists "Countries" without the Mixin suffix. Consistent naming is a nit but worth aligning. ### SOP COMPLIANCE - [x] Branch named after issue (`1-docs-swagger-specs` references issue #1) - [x] PR body has `## Summary` -- present, clear - [x] PR body has `## Changes` -- present, lists all files - [x] PR body has `## Test Plan` -- present with checkboxes - [x] PR body has `## Review Checklist` -- present - [x] PR body has `## Related Notes` -- present, references `Closes #1` and related issues - [x] No secrets committed (all credential references are placeholder examples: `your_key_here`, `api_key="..."`) - [x] No `.env` files committed (only documentation references to `~/secrets/godaddy/.env`) - [x] Commit messages are descriptive (single commit matching PR title) - [x] No unnecessary file changes (all 15 files are docs-related, on scope) - [ ] Feature flag consideration -- N/A (docs only), correctly noted in checklist ### PROCESS OBSERVATIONS - This is a pure documentation/reference PR with no executable code, so test coverage requirements do not apply. The test plan appropriately focuses on JSON validity and link resolution. - The PR cleanly scopes to the docs portion of issue #1 ("Scaffold godaddy-sdk repo with pyproject.toml, client, and docs"). The pyproject.toml and client scaffolding are presumably in a separate PR -- confirm this is intentional. - Good practice: swagger specs committed to the repo rather than referenced externally ensures reproducibility and offline development. ### VERDICT: NOT APPROVED Two blockers must be resolved before merge: (1) endpoint count discrepancies between documentation and actual swagger specs, and (2) the "10 groups" vs 11-row table inconsistency. Both are data accuracy issues in a documentation PR -- the one thing a docs PR must get right is the data.
QA review correctly flagged that the API Coverage table had 11 rows
for "10 API groups" because DNS was split from Domains despite sharing
swagger_domains.json. Merged DNS into the Domains row with priority
annotation. Added paths column to api-groups.md to disambiguate
endpoint (method+path) vs path counts.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This pull request can be merged automatically.
You are not authorized to merge this pull request.
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u origin 1-docs-swagger-specs:1-docs-swagger-specs
git switch 1-docs-swagger-specs

Merge

Merge the changes and update on Forgejo.

Warning: The "Autodetect manual merge" setting is not enabled for this repository, you will have to mark this pull request as manually merged afterwards.

git switch main
git merge --no-ff 1-docs-swagger-specs
git switch 1-docs-swagger-specs
git rebase main
git switch main
git merge --ff-only 1-docs-swagger-specs
git switch 1-docs-swagger-specs
git rebase main
git switch main
git merge --no-ff 1-docs-swagger-specs
git switch main
git merge --squash 1-docs-swagger-specs
git switch main
git merge --ff-only 1-docs-swagger-specs
git switch main
git merge 1-docs-swagger-specs
git push origin main
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
ldraney/godaddy-sdk!5
No description provided.