Update restapi #197
Update restapi #197
Conversation
WalkthroughRenamed and reorganized the REST API docs to "FalkorDB Browser REST API" (v1.4.6), added Base URL and JWT Bearer auth, replaced provider-based auth with POST /api/auth/login, introduced GET /api/status, reworked Graph/Schema/Configuration/User management endpoints and payload shapes (SSE for query execution), and appended data types and error response updates. Also added four tokens to 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 object
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 SSE Stream
Client->>API: POST /api/graph/{graph}/query (Authorization)
API-->>SSE: Open SSE stream for query execution
SSE-->>Client: event: data chunk(s)
SSE-->>Client: event: completion / 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 Possibly related PRs
Suggested labels
Suggested reviewers
Pre-merge checks (1 passed, 2 inconclusive)❌ Failed checks (2 inconclusive)
✅ Passed checks (1 passed)
Poem
📜 Recent review detailsConfiguration used: CodeRabbit UI Review profile: CHILL Plan: Pro 📒 Files selected for processing (1)
✅ Files skipped from review due to trivial changes (1)
✨ Finishing Touches🧪 Generate unit tests
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/[email protected]). Misspelled word detected: 'JWT' in integration/rest.md (context: html>body>p).
[error] 1-1: Spellcheck step failed (rojopolis/[email protected]). Misspelled word detected: 'nodeId' in integration/rest.md (context: html>body>ul>li).
[error] 1-1: Spellcheck step failed (rojopolis/[email protected]). Misspelled word detected: 'relationshipId' in integration/rest.md (context: html>body>ul>li).
[error] 1-1: Spellcheck step failed (rojopolis/[email protected]). 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.
|
|
||
| **Base URL:** Your FalkorDB Browser instance URL | ||
|
|
||
| **Authentication:** Bearer Token (JWT) |
There was a problem hiding this comment.
[nitpick] Consider adding a brief explanation of what JWT stands for in the authentication section, as this might not be immediately clear to all developers.
| **Authentication:** Bearer Token (JWT) | |
| **Authentication:** Bearer Token (JWT - JSON Web Token) |
Copilot uses AI. Check for mistakes.
|
|
||
| ```bash | ||
| AUTH_HEADER="Authorization: Bearer ${JWT_TOKEN}" |
There was a problem hiding this comment.
[nitpick] The curl example uses URL encoding for the query parameter (%20 for spaces), but this might be confusing for beginners. Consider adding a note about URL encoding or showing both encoded and unencoded versions.
| ```bash | |
| AUTH_HEADER="Authorization: Bearer ${JWT_TOKEN}" | |
| > **Note:** Query parameters in URLs must be [URL-encoded](https://en.wikipedia.org/wiki/Percent-encoding). For example, spaces become `%20`. You can use tools like [urlencoder.org](https://www.urlencoder.org/) or `encodeURIComponent` in JavaScript to encode your queries. | |
| ```bash | |
| AUTH_HEADER="Authorization: Bearer ${JWT_TOKEN}" | |
| # Unencoded (for readability): | |
| # curl -N -X GET "http://your-falkordb-browser-url/api/graph/my_graph?query=MATCH (n) RETURN n LIMIT 5&timeout=30000" \ | |
| # -H "$AUTH_HEADER" \ | |
| # -H "Accept: text/event-stream" | |
| # Encoded (required for actual requests): |
Copilot uses AI. Check for mistakes.
|
|
||
| This endpoint deletes a label from a node in a graph. | ||
| **IMPORTANT:** Use `type=true` for nodes, `type=false` for relationships. |
There was a problem hiding this comment.
[nitpick] The same important note about type parameter usage is repeated multiple times throughout the documentation. Consider creating a dedicated section explaining the type parameter once and referencing it to avoid repetition.
Copilot uses AI. Check for mistakes.
|
|
||
| Remove a property from a node or relationship. | ||
|
|
||
| **IMPORTANT:** Use `type=true` for nodes, `type=false` for relationships. |
There was a problem hiding this comment.
[nitpick] The same important note about type parameter usage is repeated multiple times throughout the documentation. Consider creating a dedicated section explaining the type parameter once and referencing it to avoid repetition.
Copilot uses AI. Check for mistakes.
Summary by CodeRabbit