| name | api-retest |
| description | Verify whether documented API articles need updates after a backend change ticket (migration, refactoring, version bump). Use when a Jira ticket describes backend changes to API handlers and the user asks to check if documentation is still accurate. |
API Retest
Validate that existing documentation articles remain accurate after a backend API change. The goal is a binary outcome: no changes needed or specific fixes required.
Inputs
| Input | Required | Notes |
|---|
| Jira ticket ID | Yes | e.g. DOC-1411, GCLOUD2-XXXXX |
| Branch | No | Create a new branch from main if any changes are expected |
Phase 1 — Read the ticket
Use the Jira MCP tool to fetch the ticket and any linked tickets.
Identify:
- Which API handlers changed — file names, class names, endpoint paths
- Nature of the change — migration to a new framework, request/response schema change, field rename, removal of a parameter, new validation rules
- Scope — does this change the external API surface (request fields, response fields, status codes, error format) or is it internal refactoring with no external effect?
If the change is purely internal (framework swap with identical external behavior), retest is still required — the ticket description is not sufficient proof.
Phase 2 — Find affected articles
Search the documentation for articles that call these endpoints:
rg -l "v1/reserved_fixed_ips" cloud/ edge-ai/
Check:
- Articles that show
curl examples with the endpoint path
- Articles that show SDK calls corresponding to those endpoints
- The OpenAPI spec (
api-reference/services_documented/cloud_api.yaml) for the current field definitions
Phase 3 — Create a branch
git checkout main
git pull origin main
git checkout -b {TICKET_ID}
Even if no changes turn out to be needed, work on the branch. Delete it at the end if empty.
Phase 4 — Write and run the test script
Test script location
c:\Projects\docops-agent2\scripts\test_{resource_name}.py
Environment
Test on preprod first — this allows documentation to be ready before the feature reaches production.
Switch to production only if the feature is not yet deployed on preprod.
| Environment | API base | Portal |
|---|
| Preprod | https://api.preprod.world | https://portal.preprod.world |
| Production | https://api.gcore.com | https://portal.gcore.com |
Region rules
Production:
| Resource type | Region | region_id |
|---|
| Networking, VMs, reserved IPs, bare metal | Luxembourg-3 | 148 |
| DBaaS, Kubernetes | Frankfurt-2 | 180 |
Preprod:
| Region | region_id |
|---|
| Luxembourg Preprod | 4 |
| INF-1 Preprod | 20 |
| ED-10 Preprod | 10 |
Use Luxembourg Preprod (region_id=4) for general networking and VM tests.
Credentials
Credentials are in C:\Projects\docops-agent2\access.md — both prod and preprod tokens are there. Always use dotenv pattern or inline env vars — never hardcode the token in committed files.
If the feature is not yet on preprod
If tests show the old behavior on preprod (dev ticket is Done but change is invisible), stop and inform the user. Do not document a behavior you cannot verify. Ask the developer which environment the change is deployed to and retest there.
Script structure
- List — verify the list endpoint returns HTTP 200 and expected top-level keys
- Filter parameters — verify each query parameter the article documents actually works
- Create — create a minimal test resource; poll the task to completion
- Get — retrieve by ID; verify all fields the article shows in the response JSON are present
- Update — if the article documents a PATCH/PUT, run it and verify the response
- Sub-resources — if the article documents nested endpoints (e.g.
connected_devices), test each method (GET, PUT, PATCH)
- Delete — delete the test resource; poll to completion
Cleanup rule
Every resource created in the test must be deleted in the same run. Use try/finally if needed to guarantee cleanup even on failure.
Run the script
.\venv\Scripts\python.exe scripts\test_{resource_name}.py
Phase 5 — Compare results with documentation
For each endpoint the article documents, check:
| Item | What to verify |
|---|
| HTTP method and path | Still correct? |
| Request body fields | Names unchanged? New required fields? Fields removed? |
| Response fields | All fields the article shows are still present? Any renamed? |
| Query parameters | All filter/sort parameters still accepted? |
| Status codes | Same as documented? |
| Task vs synchronous | Still async (returns tasks)? Or changed to sync? |
| Error format | If the article shows a 404 or 400 example, still the same shape? |
Phase 6 — Decide and act
If nothing changed:
- Delete the branch
- Close the ticket with a comment: "Tested all endpoints against the live API. No changes to documentation required."
If changes are needed:
- Update the affected articles
- Test the updated code examples end-to-end
- Commit and push to the branch
- Open a PR
Output
Report to the user:
Ticket: {ID}
Articles checked: N
Endpoints tested: list of paths
Result: no changes / N items updated
Changes made:
- {article}: {what changed}
