Add API documentation for graph retrieval, query, and commit history endpoints #96
Conversation
Co-authored-by: gkorland <[email protected]>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Important Review skippedBot user detected. To trigger a single review, invoke the You can disable this status message by setting the WalkthroughREADME.md updated with an API Reference section documenting three endpoints: GET /graph_entities for retrieving graphs, POST /chat for sending queries, and POST /list_commits and POST /switch_commit for history changes. Examples include curl commands and JSON request/response structures for each endpoint. Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~5 minutes
Poem
Pre-merge checks and finishing touches❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
Comment |
|
@CodeRabbit review |
✅ Actions performedReview triggered.
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
README.md(1 hunks)
🧰 Additional context used
🪛 Gitleaks (8.28.0)
README.md
[high] 51-57: Discovered a potential authorization token provided in a curl command header, which could compromise the curl accessed resource.
(curl-auth-header)
[high] 76-82: Discovered a potential authorization token provided in a curl command header, which could compromise the curl accessed resource.
(curl-auth-header)
[high] 98-104: Discovered a potential authorization token provided in a curl command header, which could compromise the curl accessed resource.
(curl-auth-header)
[high] 125-131: Discovered a potential authorization token provided in a curl command header, which could compromise the curl accessed resource.
(curl-auth-header)
🔇 Additional comments (1)
README.md (1)
50-69: API Reference documentation is clear and well-structured.The endpoint documentation follows a consistent pattern (template → example → response format) that is easy to follow. Response structures are sensible and include helpful fields.
| ## API Reference | ||
|
|
||
| ### Retrieve a graph | ||
|
|
||
| Fetch graph entities from a repository: | ||
|
|
||
| ```bash | ||
| curl -X GET "http://127.0.0.1:5000/graph_entities?repo=<REPO_NAME>" -H "Authorization: <.ENV_SECRET_TOKEN>" | ||
| ``` | ||
|
|
||
| For example: | ||
|
|
||
| ```bash | ||
| curl -X GET "http://127.0.0.1:5000/graph_entities?repo=GraphRAG-SDK" -H "Authorization: OpenSesame" | ||
| ``` | ||
|
|
||
| Response: | ||
| ```json | ||
| { | ||
| "status": "success", | ||
| "entities": { | ||
| "nodes": [...], | ||
| "edges": [...] | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ### Send Query | ||
|
|
||
| Query your code graph using natural language: | ||
|
|
||
| ```bash | ||
| curl -X POST http://127.0.0.1:5000/chat -H "Content-Type: application/json" -d '{"repo": "<REPO_NAME>", "msg": "<YOUR_QUESTION>"}' -H "Authorization: <.ENV_SECRET_TOKEN>" | ||
| ``` | ||
|
|
||
| For example: | ||
|
|
||
| ```bash | ||
| curl -X POST http://127.0.0.1:5000/chat -H "Content-Type: application/json" -d '{"repo": "GraphRAG-SDK", "msg": "What are the main classes in this project?"}' -H "Authorization: OpenSesame" | ||
| ``` | ||
|
|
||
| Response: | ||
| ```json | ||
| { | ||
| "status": "success", | ||
| "response": "The main classes in this project are..." | ||
| } | ||
| ``` | ||
|
|
||
| ### History change | ||
|
|
||
| List all commits in a repository: | ||
|
|
||
| ```bash | ||
| curl -X POST http://127.0.0.1:5000/list_commits -H "Content-Type: application/json" -d '{"repo": "<REPO_NAME>"}' -H "Authorization: <.ENV_SECRET_TOKEN>" | ||
| ``` | ||
|
|
||
| For example: | ||
|
|
||
| ```bash | ||
| curl -X POST http://127.0.0.1:5000/list_commits -H "Content-Type: application/json" -d '{"repo": "GraphRAG-SDK"}' -H "Authorization: OpenSesame" | ||
| ``` | ||
|
|
||
| Response: | ||
| ```json | ||
| { | ||
| "status": "success", | ||
| "commits": [ | ||
| { | ||
| "hash": "abc123", | ||
| "date": 1234567890, | ||
| "author": "John Doe", | ||
| "message": "Initial commit" | ||
| } | ||
| ] | ||
| } | ||
| ``` | ||
|
|
||
| Switch repository to a specific commit: | ||
|
|
||
| ```bash | ||
| curl -X POST http://127.0.0.1:5000/switch_commit -H "Content-Type: application/json" -d '{"repo": "<REPO_NAME>", "commit": "<COMMIT_HASH>"}' -H "Authorization: <.ENV_SECRET_TOKEN>" | ||
| ``` | ||
|
|
||
| For example: | ||
|
|
||
| ```bash | ||
| curl -X POST http://127.0.0.1:5000/switch_commit -H "Content-Type: application/json" -d '{"repo": "GraphRAG-SDK", "commit": "abc123"}' -H "Authorization: OpenSesame" | ||
| ``` | ||
|
|
||
| Response: | ||
| ```json | ||
| { | ||
| "status": "success" | ||
| } | ||
| ``` |
There was a problem hiding this comment.
Hardcoded authorization token in curl examples presents security risk.
Gitleaks flagged 4 instances of authorization tokens in the curl command examples (lines 51-57, 76-82, 98-104, 125-131). While "OpenSesame" is clearly a placeholder, including literal token values in documentation examples—even placeholders—normalizes a risky copy-paste pattern that could lead developers to accidentally commit real secrets.
Recommendation: Add a prominent note before the examples explaining that developers should never include literal tokens in curl commands, or refactor the examples to use environment variable references instead:
+> **⚠️ Security Note:** Never include actual authorization tokens in curl commands or documentation. Always use environment variables or secrets management.
### Retrieve a graph
Fetch graph entities from a repository:
```bash
-curl -X GET "http://127.0.0.1:5000/graph_entities?repo=<REPO_NAME>" -H "Authorization: <.ENV_SECRET_TOKEN>"
+curl -X GET "http://127.0.0.1:5000/graph_entities?repo=<REPO_NAME>" -H "Authorization: $AUTH_TOKEN"For example:
-curl -X GET "http://127.0.0.1:5000/graph_entities?repo=GraphRAG-SDK" -H "Authorization: OpenSesame"
+# Set AUTH_TOKEN environment variable: export AUTH_TOKEN="your_token_here"
+curl -X GET "http://127.0.0.1:5000/graph_entities?repo=GraphRAG-SDK" -H "Authorization: $AUTH_TOKEN"
Apply the same refactoring pattern to the POST /chat (lines 76-82), POST /list_commits (lines 98-104), and POST /switch_commit (lines 125-131) examples.
<details>
<summary>🧰 Tools</summary>
<details>
<summary>🪛 Gitleaks (8.28.0)</summary>
[high] 51-57: Discovered a potential authorization token provided in a curl command header, which could compromise the curl accessed resource.
(curl-auth-header)
---
[high] 76-82: Discovered a potential authorization token provided in a curl command header, which could compromise the curl accessed resource.
(curl-auth-header)
---
[high] 98-104: Discovered a potential authorization token provided in a curl command header, which could compromise the curl accessed resource.
(curl-auth-header)
---
[high] 125-131: Discovered a potential authorization token provided in a curl command header, which could compromise the curl accessed resource.
(curl-auth-header)
</details>
</details>
<details>
<summary>🤖 Prompt for AI Agents</summary>
In README.md around lines 44 to 139, replace the hardcoded "OpenSesame"
Authorization examples and add a short warning about never including literal
tokens: add one-line note above the examples telling users to never paste real
tokens and to use an environment variable (e.g., AUTH_TOKEN). For each curl
example at lines 51-57, 76-82, 98-104, and 125-131 swap the literal
Authorization value with the environment variable reference ($AUTH_TOKEN) and
include an example export command (export AUTH_TOKEN="your_token_here")
immediately before the concrete example lines so readers set the env var rather
than hardcoding secrets.
</details>
<!-- This is an auto-generated comment by CodeRabbit -->
|
@copilot the CI is failing |
Co-authored-by: gkorland <[email protected]>
Update README to include missing API documentation ✅
Completed:
/graph_entities)/chat)/list_commitsand/switch_commit)Summary:
Successfully added a new "API Reference" section to README.md documenting the three missing APIs requested in the issue:
GET /graph_entities) - Fetches graph entities from a repositoryPOST /chat) - Queries the code graph using natural language via LLMPOST /list_commits- Lists all commits in a repositoryPOST /switch_commit- Switches repository to a specific commitEach API section includes:
All documentation follows the existing format and style conventions in the README.
CI Fix:
Fixed flake8 linting error in
api/llm.pyby removing unnecessaryglobal ontologydeclaration that was never assigned in the function scope.Original prompt
💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.
Summary by CodeRabbit