Update restapi #197
Update restapi #197
Conversation
|
Note Other AI code review bot(s) detectedCodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review. WalkthroughRewrote and reorganized REST documentation as "FalkorDB Browser REST API" v1.4.6: introduced Base URL and JWT Bearer auth with POST Changes
Sequence Diagram(s)sequenceDiagram
autonumber
participant Client
participant API as FalkorDB Browser REST API
participant Auth as Auth Service
Client->>API: POST /api/auth/login {username, password}
API->>Auth: Validate credentials
Auth-->>API: JWT token + user
API-->>Client: 200 {token, user}
Note over Client,API: Use Authorization: Bearer <token> for subsequent requests
sequenceDiagram
autonumber
participant Client
participant API as FalkorDB Browser REST API
participant SSE as Query SSE
Client->>API: POST /api/graph/{graph}/query (Authorization, body)
API->>SSE: Start SSE stream for query execution
SSE-->>Client: event: data (chunks)
SSE-->>Client: event: complete / error
Note over SSE,Client: Query results streamed incrementally
sequenceDiagram
autonumber
participant Client
participant API as FalkorDB Browser REST API
Client->>API: POST /api/schema/{schema}/nodes {type, attributes}
API-->>Client: 201 {message: "Node created successfully", data: {...}}
Client->>API: POST /api/schema/{schema}/relationships {type, selectedNodes, attributes}
API-->>Client: 201 {message: "Relationship created successfully", data: {...}}
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes
Poem
Pre-merge checks and finishing touches❌ Failed checks (1 inconclusive)
✅ Passed checks (2 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
📜 Recent review detailsConfiguration used: CodeRabbit UI Review profile: CHILL Plan: Pro 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 9
🧹 Nitpick comments (14)
integration/rest.md (14)
188-200: HTTP status for offline DB should be 503, not 404404 implies the route is missing; 503 is standard for temporary unavailability.
-- **404**: Database is offline or not accessible +- **503**: Database is offline or not accessible
246-249: Document SSE response headersState Content-Type for SSE and example event format to aid clients.
- **200**: Query executed successfully (Server-Sent Events stream) + - Content-Type: `text/event-stream` + - Example event: + ``` + event: message + data: {"columns":["n"],"rows":[{"n":{"id":1,"labels":["Person"]}}]} + ```
283-285: Clarify rename semantics for path vs. sourceNameStating “graph (path) = new name” is unconventional and easy to misuse. Either swap (path=current, body=new) or explicitly call this out in bold with an example request.
Would you like a patch to switch to body payload
{ "newName": "..." }?
319-323: Polish deletion message for consistencyAlign with other messages and quote the name.
- "message": "graph_name graph deleted" + "message": "Graph 'graph_name' deleted"
437-440: Normalize response envelope keysThis uses
result.statuswhile rename usesdata.result. Pick one convention across the doc.- "result": { - "status": "Graph duplicated successfully" - } + "data": { + "result": "Graph duplicated successfully" + }
503-510: Use explicit enum for “type” instead of boolean true/false
type=true/falseis ambiguous and error-prone. Prefertype: "node" | "relationship".- "type": true + "type": "node"And update text accordingly.
582-607: Clarify accepted value types and example for property settingSpecify that
valuecan be STRING/INTEGER/FLOAT/BOOLEAN and show a non-string example to avoid confusion.-- `value`: Property value to set +- `value`: Property value to set (STRING | INTEGER | FLOAT | BOOLEAN)
700-712: POST with query paramvalueis unconventionalMove
valueto JSON body for consistency with other endpoints; keeps semantics cleaner.-- `value` (query, required): Configuration value to set (numeric values will be parsed as integers except for CMD_INFO) +- Body field `value` (required): Configuration value to set (numeric values parsed as integers except for `CMD_INFO`)If backend can’t change, add an explicit example including
?value=....
828-851: Schema duplicate: normalize envelope like graph duplicate/renameUnify to
data.resultor vice versa.-{ - "result": { - "status": "Schema duplicated successfully" - } -} +{ + "data": { + "result": "Schema duplicated successfully" + } +}
918-928: Creation endpoints should return 201 CreatedAlign node creation with schema/user creation.
-- **200**: Node created successfully +- **201**: Node created successfullySame for relationships (Line 972).
1338-1344: PUT/PATCH withroleas query param is brittlePrefer a JSON body
{ "role": "Read-Only" }for clarity and parity with other endpoints.
171-174: General: avoid hardcoding the version“Version: 1.4.6” will drift. Use a site variable (e.g., Jekyll config or data file) or omit.
Would you like a PR to parameterize this via site.data?
1032-1085: Stabilize heading IDs with explicit anchorsKramdown/Just-the-Docs slugging differs with symbols like
{}and/. Add explicit IDs and update ToC to match; this will also eliminate future MD051 noise.Example:
-### **Add label to node** - `POST /api/schema/{schema}/{node}/label` +### **Add label to node** - `POST /api/schema/{schema}/{node}/label` {#add-label-to-node---post-apischemaschemanodelabel}Apply similarly to all headings referenced by ToC.
64-69: Optional: safer curl for query parameter encodingUse
--get --data-urlencodeto avoid manual encoding mistakes.-curl -N -X GET "http://your-falkordb-browser-url/api/graph/my_graph?query=MATCH%20(n)%20RETURN%20n%20LIMIT%205&timeout=30000" \ +curl -N -G "http://your-falkordb-browser-url/api/graph/my_graph" \ + --data-urlencode 'query=MATCH (n) RETURN n LIMIT 5' \ -H "$AUTH_HEADER" \ -H "Accept: text/event-stream"
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
integration/rest.md(1 hunks)
🧰 Additional context used
🪛 Gitleaks (8.27.2)
integration/rest.md
[high] 51-52: Discovered a potential authorization token provided in a curl command header, which could compromise the curl accessed resource.
(curl-auth-header)
[high] 59-60: Discovered a potential authorization token provided in a curl command header, which could compromise the curl accessed resource.
(curl-auth-header)
[high] 67-68: Discovered a potential authorization token provided in a curl command header, which could compromise the curl accessed resource.
(curl-auth-header)
[high] 39-39: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.
(generic-api-key)
[high] 163-163: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.
(generic-api-key)
🪛 markdownlint-cli2 (0.17.2)
integration/rest.md
110-110: Link fragments should be valid
(MD051, link-fragments)
112-112: Link fragments should be valid
(MD051, link-fragments)
116-116: Link fragments should be valid
(MD051, link-fragments)
117-117: Link fragments should be valid
(MD051, link-fragments)
134-134: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (3)
integration/rest.md (3)
51-53: Replace literal Authorization header with env var (satisfy Gitleaks; keep examples consistent).Mirror the AUTH_HEADER pattern used below.
-curl -X GET "http://your-falkordb-browser-url/api/status" \ - -H "Authorization: Bearer $JWT_TOKEN" +AUTH_HEADER="Authorization: Bearer ${JWT_TOKEN}" +curl -X GET "http://your-falkordb-browser-url/api/status" \ + -H "$AUTH_HEADER"
137-139: Add language to fenced code block (MD040).Use http to fix markdownlint.
-``` +```http Authorization: Bearer <your-jwt-token>--- `1287-1289`: **Fix Location header path for created user.** Should be /api/user/{username}. ```diff - - Headers: - - `location`: Location of the created user resource (example: `/api/db/user/new_user`) + - Headers: + - `location`: Location of the created user resource (example: `/api/user/new_user`)
🧹 Nitpick comments (4)
integration/rest.md (4)
371-373: Remove parentheses from option tokens and JSON keys; use stable snake_case.Parentheses hinder clients and anchor generation. Recommend explicit tokens.
- - Options: `(function)`, `(property key)`, `(label)`, `(relationship type)` - - Example: `(label)` + - Options: `function`, `property_key`, `label`, `relationship_type` + - Example: `label` @@ - {"(label)": "Person"}, - {"(label)": "Company"} + {"label": "Person"}, + {"label": "Company"}Also applies to: 384-386
265-273: Standardize response envelope shape (“message” vs nesteddata.result).Mixing top-level "message" and nested
data.resultadds friction. Pick one convention and apply across endpoints.For example, flatten Rename/Duplicate responses to a single
message:{ - "data": { - "result": "Graph renamed successfully" - } + "message": "Graph renamed successfully" }Do the same for schema rename/duplicate for consistency.
Also applies to: 295-301, 322-326, 438-444, 791-797, 847-853, 1281-1285
585-606: Booleantypeflags are opaque; prefer explicit enums or drop where endpoint implies entity.If backend accepts it, consider
entity: "node"|"relationship"; for /nodes and /relationships, omit the field entirely.Example payload alternative:
{ "entity": "node", "label": ["Person","User"], "attributes": [["name",["STRING","","false","true"]]] }Also applies to: 619-642, 897-901, 933-936, 968-972, 1000-1001, 1029-1030, 1114-1116, 1145-1146, 1176-1178, 1207-1208
14-15: DRY the base URL and auth in curl examples with env vars.Introduce BASE_URL and reuse AUTH_HEADER everywhere.
- curl -X POST "http://your-falkordb-browser-url/api/auth/login" \ + BASE_URL="${BASE_URL:-http://your-falkordb-browser-url}" + curl -X POST "$BASE_URL/api/auth/login" \ @@ -AUTH_HEADER="Authorization: Bearer ${JWT_TOKEN}" -curl -X GET "http://your-falkordb-browser-url/api/graph" \ +AUTH_HEADER="Authorization: Bearer ${JWT_TOKEN}" +curl -X GET "$BASE_URL/api/graph" \ -H "$AUTH_HEADER" @@ -curl -N -X GET "http://your-falkordb-browser-url/api/graph/my_graph?query=MATCH%20(n)%20RETURN%20n%20LIMIT%205&timeout=30000" \ +curl -N -X GET "$BASE_URL/api/graph/my_graph?query=MATCH%20(n)%20RETURN%20n%20LIMIT%205&timeout=30000" \ -H "$AUTH_HEADER" \ -H "Accept: text/event-stream"Also applies to: 27-34, 51-62, 67-72
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
integration/rest.md(3 hunks)
🧰 Additional context used
🪛 markdownlint-cli2 (0.17.2)
integration/rest.md
137-137: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🪛 GitHub Actions: spellcheck
integration/rest.md
[error] 1-1: Spellcheck step failed (rojopolis/spellcheck-github-actions@0.33.1). Misspelled word detected: 'JWT' in integration/rest.md (context: html>body>p).
[error] 1-1: Spellcheck step failed (rojopolis/spellcheck-github-actions@0.33.1). Misspelled word detected: 'nodeId' in integration/rest.md (context: html>body>ul>li).
[error] 1-1: Spellcheck step failed (rojopolis/spellcheck-github-actions@0.33.1). Misspelled word detected: 'relationshipId' in integration/rest.md (context: html>body>ul>li).
[error] 1-1: Spellcheck step failed (rojopolis/spellcheck-github-actions@0.33.1). Misspelled word detected: 'backend' in integration/rest.md (context: html>body>p).
🔇 Additional comments (2)
integration/rest.md (2)
68-72: SSE curl example looks correct (Accept + -N + URL-encoded query).Good usability and correctness.
201-202: Confirm actual status code for “database offline.”404 is unusual for backend-down; many APIs use 503 Service Unavailable. Please verify the real behavior and align docs.
There was a problem hiding this comment.
Pull Request Overview
This PR updates the REST API documentation for FalkorDB Browser, rebranding it from a generic "Rest API" to "FalkorDB Browser REST API" with comprehensive restructuring and modernization. The documentation now includes JWT authentication, a quick start guide, and greatly expanded endpoint coverage with detailed examples.
Key changes include:
- Complete rebranding and restructuring with version 1.4.6
- Addition of JWT-based authentication system replacing cookie-based auth
- Comprehensive quick start guide with curl examples
- Expanded endpoint documentation with Server-Sent Events support and standardized response formats
Reviewed Changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| integration/rest.md | Complete rewrite of REST API documentation with new structure, authentication method, and expanded endpoint coverage |
| .wordlist.txt | Added new glossary terms: JWT, nodeId, relationshipId, backend |
Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.
There was a problem hiding this comment.
Actionable comments posted: 3
♻️ Duplicate comments (3)
integration/rest.md (3)
1451-1452: Correct the Location header path.The Location header should point to
/api/user/new_user, not/api/db/user/new_user, to match the documented user endpoint.- Headers: - - `location`: Location of the created user resource (example: `/api/db/user/new_user`) + - `location`: Location of the created user resource (example: `/api/user/new_user`)
535-536: Remove parentheses from type parameter options.The
typeparameter options should use clean snake_case tokens instead of parentheses, which are awkward for API clients.- - Options: `(function)`, `(property key)`, `(label)`, `(relationship type)` - - Example: `(label)` + - Options: `function`, `property_key`, `label`, `relationship_type` + - Example: `label`
544-553: Update example response to use clean JSON keys (without parentheses).When the
typeparameter options are refactored to remove parentheses, this example response must also be updated for consistency.{ - "result": { - "data": [ - {"(label)": "Person"}, - {"(label)": "Company"} + "result": { + "data": [ + {"label": "Person"}, + {"label": "Company"} ] } }
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
.wordlist.txt(4 hunks)integration/rest.md(4 hunks)
🧰 Additional context used
🪛 Gitleaks (8.28.0)
integration/rest.md
[high] 196-196: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.
(generic-api-key)
[high] 271-271: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.
(generic-api-key)
[high] 308-308: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.
(generic-api-key)
🪛 LanguageTool
.wordlist.txt
[uncategorized] ~258-~258: Ger doublet «reltype reltype».
Context: ...lTypes relationshipTypes relationshipId reltype reltype reltypeList replaceRegEx rgraph rueidis...
(GER_DOUBLET)
🪛 markdownlint-cli2 (0.18.1)
integration/rest.md
140-140: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (1)
.wordlist.txt (1)
57-58: New wordlist entries look good.The additions (
JWT,tokenId,nodeId,relationshipId,backend) align with REST API terminology inintegration/rest.mdand resolve spellcheck CI failures.Also applies to: 214-214, 258-258, 337-337
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (1)
integration/rest.md (1)
1503-1504: Fix incorrect Location header path.Line 1503-1504 shows
/api/db/user/{username}but should be/api/user/{username}to match the actual endpoint path defined elsewhere in the document.- Headers: - - `location`: Location of the created user resource (example: `/api/db/user/new_user`) + - `location`: Location of the created user resource (example: `/api/user/new_user`)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
.wordlist.txt(4 hunks)integration/rest.md(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
- .wordlist.txt
🧰 Additional context used
🪛 GitHub Actions: spellcheck
integration/rest.md
[error] 1-1: Spell check failed. Files in repository contain spelling errors. Misspelled word: .
🪛 Gitleaks (8.29.0)
integration/rest.md
[high] 244-244: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.
(generic-api-key)
[high] 323-323: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.
(generic-api-key)
[high] 360-360: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.
(generic-api-key)
🔇 Additional comments (1)
integration/rest.md (1)
1-1500: Resolve spellcheck pipeline failure by adding terms to .wordlist.txt or adjusting wording.The spellcheck CI is failing because terms like
JWT,backend,nodeId, andrelationshipIdappear throughout the documentation but are not in.wordlist.txt. Two approaches:Option A (preferred): Adjust wording to use spellcheck-friendly alternatives:
- "JWT token" → "JWT" or "JSON Web Token (JWT)"
- "backend endpoint" → "back-end endpoint"
- "nodeId"/"relationshipId" → "node ID"/"relationship ID" (and update any anchor links to match)
Option B: Add these terms to
.wordlist.txt:
JWTbackendnodeIdrelationshipIdPlease confirm which approach aligns with your project's style guide and update either the documentation wording or the wordlist accordingly. If you choose Option A, you'll also need to verify that anchor links in the table of contents still match the updated heading slugs after wording changes.
Summary by CodeRabbit