diff --git a/.wordlist.txt b/.wordlist.txt index 930132b8..1369fc11 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -56,6 +56,8 @@ JS js JSDoc JSON +JWT +tokenId KJDev Kepner Keren @@ -77,6 +79,7 @@ MotoGP NRedisGraph NaN NFalkorDB +NEXTAUTH NodeJS Nostem NumItems @@ -131,7 +134,6 @@ acos acyclic algo alister -alister allShortestPaths arccosine arcsine @@ -195,7 +197,6 @@ Jupyter javadocs javascript jedis -jfalkordb jinja jl jpbourbon @@ -213,6 +214,7 @@ myGraph myPassword myUsername namespace +nodeId nan nav nd @@ -256,7 +258,7 @@ redisgraph relDirection relTypes relationshipTypes -reltype +relationshipId reltype reltypeList replaceRegEx @@ -320,7 +322,6 @@ vec euclideanDistance cosineDistance vecf - Dani Dovizioso Pedrosa @@ -331,10 +332,10 @@ RDB scalable scalability falkorDB - GraphName api auth +backend callbackUrl csrf csrfToken @@ -364,9 +365,7 @@ FalkorConnectionInfo h1 tokio async -falkor fn - xxHash proc utf @@ -377,7 +376,6 @@ thpool sds CRoaring RSALv - hostnames bigmac calmcode @@ -386,15 +384,12 @@ kafka readme github pre -html -body table Explainer propname propvalue ro GenAI - Kruskal's MSF MST @@ -404,7 +399,6 @@ SPpath SSpath WCC WSL - undirected preprocessing subgraphs @@ -419,7 +413,6 @@ prev componentId Betweenness betweenness - LLMs Groq ontologies @@ -455,7 +448,6 @@ embeddings Colab chatbots Cognee's - alice cypher createQuery @@ -478,7 +470,6 @@ copyGraph myproject mut readOnlyQuery - Dunder Mifflin scranton @@ -490,7 +481,6 @@ Munger queryRelationships similarityFunction FIELDTERMINATOR -backend md Opire hh @@ -613,7 +603,6 @@ findByAgeNotIn findByNameAndAgeGreaterThan findFirstByOrderByCreatedAtDesc findTop10ByOrderByAgeDesc -findByAgeGreaterThanEqual findTop5ByOrderByAgeDesc findFirstByOrderByAgeAsc deleteByAge @@ -651,7 +640,6 @@ OpsRequest ComponentDefinition ClusterDefinition PodMonitor -BGSAVE datafile quorum NLB diff --git a/integration/rest.md b/integration/rest.md index eb1fbf9c..ac7f6315 100644 --- a/integration/rest.md +++ b/integration/rest.md @@ -5,301 +5,503 @@ description: "Rest API detailed doc" parent: "Integration" --- -# Rest API +# FalkorDB Browser REST API + +REST API for FalkorDB Browser - Graph Database Management Interface + +**Version:** 1.4.6 + +**Base URL:** Your FalkorDB Browser instance URL + +**Authentication:** Bearer Token (JWT) + +## Getting Started + +### Quick Start Guide + +To start using the FalkorDB Browser REST API, follow these simple steps: + +#### 1. Authentication +First, you need to authenticate to get a JWT token: + +```bash +curl -X POST "http://your-falkordb-browser-url/api/auth/tokens/credentials" \ + -H "Content-Type: application/json" \ + -d '{ + "username": "default", + "password": "", + "host": "localhost", + "port": "6379", + "tls": "false" + }' +``` + +This will return a JWT token that you'll use for all subsequent requests: +```json +{ + "message": "Token created successfully", + "token": "" +} +``` + +#### 2. Check Connection Status +Verify that FalkorDB is running and accessible: + +```bash +curl -X GET "http://your-falkordb-browser-url/api/status" \ + -H "Authorization: Bearer $JWT_TOKEN" +``` + +#### 3. List Available Graphs +See what graphs are available in your FalkorDB instance: + +```bash +AUTH_HEADER="Authorization: Bearer ${JWT_TOKEN}" +curl -X GET "http://your-falkordb-browser-url/api/graph" \ + -H "$AUTH_HEADER" +``` + +#### 4. Execute Your First Query +Run a simple Cypher query on a graph: + +```bash +AUTH_HEADER="Authorization: Bearer ${JWT_TOKEN}" +curl -N -X GET "http://your-falkordb-browser-url/api/graph/my_graph?query=MATCH%20(n)%20RETURN%20n%20LIMIT%205&timeout=30000" \ + -H "$AUTH_HEADER" \ + -H "Accept: text/event-stream" +``` ## Table of Contents ### Authentication -- [Login - GET /api/auth/providers](#login---get-apiauthproviders) -- [Logout - POST /api/auth/signout](#logout---post-apiauthsignout) - -### Settings -- [Set Configuration Value - POST /api/config](#set-configuration-value---post-apiconfig) -- [Get Configuration Value - GET /api/config](#get-configuration-value---get-apiconfig) -- [Create New User - POST /api/user](#create-new-user---post-apiuser) -- [Delete User - DELETE /api/user](#delete-user---delete-apiuser) -- [Get All Users - GET /api/user](#get-all-users---get-apiuser) -- [Modify a User - PATCH /api/user/{userName}](#modify-a-user---patch-apiuserusername) - -### Graph -- [Create a Graph & Run A Query - GET /api/graph/{graphName}](#create-a-graph--run-a-query---get-apigraphgraphname) -- [Delete a Graph - DELETE /api/graph/{graphName}](#delete-a-graph---delete-apigraphgraphname) -- [Get All Graphs - GET /api/graph](#get-all-graphs---get-apigraph) -- [Duplicate a Graph - POST /api/graph/{destinationGraphName}](#duplicate-a-graph---post-apigraphdestinationgraphname) -- [Get Graph Count - GET /api/graph/{graphName}/count](#get-graph-count---get-apigraphgraphnamecount) -- [Add Node Attribute - POST /api/graph/{graphName}/{id}/{attribute}](#add-node-attribute---post-apigraphgraphnameidattribute) -- [Delete Node Attribute - DELETE /api/graph/{graphName}/{id}/{attribute}](#delete-node-attribute---delete-apigraphgraphnameidattribute) -- [Add Node Label - POST /api/graph/{graphName}/{id}/label](#add-node-label---post-apigraphgraphnameidlabel) -- [Delete Node Label - DELETE /api/graph/{graphName}/{id}/label](#delete-node-label---delete-apigraphgraphnameidlabel) -- [Delete Node - DELETE /api/graph/{graphName}/{id}](#delete-node---delete-apigraphgraphnameid) - -### Schema -- [Create New Schema & Run A Query - GET /api/graph/{schemaName}](#create-new-schema--run-a-query---get-apigraphschemaname) -- [Delete a Schema - DELETE /api/graph/{schemaName}](#delete-a-schema---delete-apigraphschemaname) -- [Get Schema Count - GET /api/schema/{schemaName}/count](#get-schema-count---get-apischemaschemaname-count) -- [Add Schema Node - POST /api/schema/{schemaName}/{id}](#add-schema-node---post-apischemaschemanameid) -- [Delete Schema Node - DELETE /api/schema/{schemaName}/{id}](#delete-schema-node---delete-apischemaschemanameid) -- [Add Schema Attribute - PATCH /api/schema/{schemaName}/{id}/{attribute}](#add-schema-attribute---patch-apischemaschemanameidattribute) -- [Delete Schema Attribute - DELETE /api/schema/{schemaName}/{id}/{attribute}](#delete-schema-attribute---delete-apischemaschemanameidattribute) -- [Add Schema Label - POST /api/schema/{schemaName}/{id}/label](#add-schema-label---post-apischemaschemanameidlabel) -- [Delete Schema Label - DELETE /api/schema/{schemaName}/{id}/label](#delete-schema-label---delete-apischemaschemanameidlabel) +- [Generate JWT Token with Credentials - POST /api/auth/tokens/credentials](#generate-jwt-token-with-credentials---post-apiauthtokenscredentials) +- [List JWT tokens - GET /api/auth/tokens](#list-jwt-tokens---get-apiauthtokens) +- [Get token metadata - GET /api/auth/tokens/{tokenId}](#get-token-metadata---get-apiauthtokenstokenid) +- [Revoke token by ID - DELETE /api/auth/tokens/{tokenId}](#revoke-token-by-id---delete-apiauthtokenstokenid) + +### Status +- [Check FalkorDB connection status - GET /api/status](#check-falkordb-connection-status---get-apistatus) + +### Graph Management +- [List all graphs - GET /api/graph](#list-all-graphs---get-apigraph) +- [Execute graph query - GET /api/graph/{graph}](#execute-graph-query---get-apigraphgraph) +- [Create or verify a graph - POST /api/graph/{graph}](#create-or-verify-a-graph---post-apigraphgraph) +- [Rename graph - PATCH /api/graph/{graph}](#rename-graph---patch-apigraphgraph) +- [Delete a graph - DELETE /api/graph/{graph}](#delete-a-graph---delete-apigraphgraph) +- [Get query execution plan - GET /api/graph/{graph}/explain](#get-query-execution-plan---get-apigraphgraphexplain) +- [Profile query execution - GET /api/graph/{graph}/profile](#profile-query-execution---get-apigraphgraphprofile) +- [Get graph information - GET /api/graph/{graph}/info](#get-graph-information---get-apigraphgraphinfo) +- [Get graph element counts - GET /api/graph/{graph}/count](#get-graph-element-counts---get-apigraphgraphcount) +- [Export graph data - GET /api/graph/{graph}/export](#export-graph-data---get-apigraphgraphexport) +- [Duplicate a graph - PATCH /api/graph/{graph}/duplicate](#duplicate-a-graph---patch-apigraphgraphduplicate) +- [Get node information - GET /api/graph/{graph}/{node}](#get-node-information---get-apigraphgraphnode) +- [Delete node or relationship - DELETE /api/graph/{graph}/{node}](#delete-node-or-relationship---delete-apigraphgraphnode) +- [Add node label - POST /api/graph/{graph}/{node}/label](#add-node-label---post-apigraphgraphnodelabel) +- [Remove node label - DELETE /api/graph/{graph}/{node}/label](#remove-node-label---delete-apigraphgraphnodelabel) +- [Set node/relationship property - POST /api/graph/{graph}/{node}/{key}](#set-noderelationship-property---post-apigraphgraphnodekey) +- [Remove node/relationship property - DELETE /api/graph/{graph}/{node}/{key}](#remove-noderelationship-property---delete-apigraphgraphnodekey) + +### Configuration Management +- [Get all configuration values - GET /api/graph/config](#get-all-configuration-values---get-apigraphconfig) +- [Get specific configuration value - GET /api/graph/config/{config}](#get-specific-configuration-value---get-apigraphconfigconfig) +- [Set configuration value - POST /api/graph/config/{config}](#set-configuration-value---post-apigraphconfigconfig) + +### Schema Management +- [List all schemas - GET /api/schema](#list-all-schemas---get-apischema) +- [Get schema information - GET /api/schema/{schema}](#get-schema-information---get-apischemaschema) +- [Create new schema - POST /api/schema/{schema}](#create-new-schema---post-apischemaschema) +- [Rename schema - PATCH /api/schema/{schema}](#rename-schema---patch-apischemaschema) +- [Delete schema - DELETE /api/schema/{schema}](#delete-schema---delete-apischemaschema) +- [Get schema element counts - GET /api/schema/{schema}/count](#get-schema-element-counts---get-apischemaschemacount) +- [Duplicate schema - PATCH /api/schema/{schema}/duplicate](#duplicate-schema---patch-apischemaschemaduplicate) +- [Create node or relationship in schema - POST /api/schema/{schema}/new](#create-node-or-relationship-in-schema---post-apischemaschemanew) +- [Create node in schema - POST /api/schema/{schema}/nodes](#create-node-in-schema---post-apischemaschemanodes) +- [Create relationship in schema - POST /api/schema/{schema}/relationships](#create-relationship-in-schema---post-apischemaschemarelationships) +- [Delete node from schema - DELETE /api/schema/{schema}/{nodeId}](#delete-node-from-schema---delete-apischemaschemanodeid) +- [Delete relationship from schema - DELETE /api/schema/{schema}/{relationshipId}](#delete-relationship-from-schema---delete-apischemaschemarelationshipid) +- [Add label to node - POST /api/schema/{schema}/{node}/label](#add-label-to-node---post-apischemaschemanodelabel) +- [Remove label from node - DELETE /api/schema/{schema}/{node}/label](#remove-label-from-node---delete-apischemaschemanodelabel) +- [Add/Update attribute to node - PATCH /api/schema/{schema}/{nodeId}/{key}](#addupdate-attribute-to-node---patch-apischemaschemanodeidkey) +- [Remove attribute from node - DELETE /api/schema/{schema}/{nodeId}/{key}](#remove-attribute-from-node---delete-apischemaschemanodeidkey) +- [Add/Update attribute to relationship - PATCH /api/schema/{schema}/{relationshipId}/{key}](#addupdate-attribute-to-relationship---patch-apischemaschemarelationshipidkey) +- [Remove attribute from relationship - DELETE /api/schema/{schema}/{relationshipId}/{key}](#remove-attribute-from-relationship---delete-apischemaschemarelationshipidkey) + +### User Management +- [List all users - GET /api/user](#list-all-users---get-apiuser) +- [Create new user - POST /api/user](#create-new-user---post-apiuser) +- [Delete multiple users - DELETE /api/user](#delete-multiple-users---delete-apiuser) +- [Update user role - PATCH /api/user/{user}](#update-user-role---patch-apiuseruser) --- ## Authentication -### **Login** - `GET /api/auth/providers` +All endpoints except `/api/auth/tokens/credentials` require authentication using a JWT bearer token in the Authorization header: +```http +Authorization: Bearer +``` -This endpoint retrieves information about authentication providers and their respective URLs for sign-in and callback. +### **Generate JWT Token with Credentials** - `POST /api/auth/tokens/credentials` + +Authenticate with direct credentials and generate a JWT Personal Access Token (PAT) for external API access, CLI tools, or programmatic access. This endpoint does NOT require an existing session. + +#### Request Body + +- Content-Type: `application/json` +- Required fields: `username`, `host`, `port`, `tls` +- Optional fields: `password`, `name`, `expiresAt`, `ttlSeconds` + +Example request: +```json +{ + "username": "default", + "password": "", + "name": "API Token", + "expiresAt": null, + "ttlSeconds": 31622400, + "host": "localhost", + "port": "6379", + "tls": "false" +} +``` + +**Request Parameters:** +- `username` (required): Username for database connection +- `password` (optional): Password for database connection. Can be omitted (or empty) only when using the `default` user on localhost; otherwise a non-empty password is required +- `name` (optional): Token name +- `expiresAt` (optional): Token expiration date in ISO 8601 format +- `ttlSeconds` (optional): Time-to-live in seconds (max: 31622400) +- `host` (required): FalkorDB host +- `port` (required): FalkorDB port +- `tls` (required): Enable TLS connection - "true" or "false" #### Responses -- **200**: Successful authentication provider retrieval +- **200**: Token generated successfully - Content-Type: `application/json` - Example response: ```json { - "credentials": { - "id": "credentials", - "name": "Credentials", - "type": "credentials", - "signinUrl": "http://localhost:3000/api/auth/signin/credentials", - "callbackUrl": "http://localhost:3000/api/auth/callback/credentials" - } + "message": "Token created successfully", + "token": "" } ``` -### **Logout** - `POST /api/auth/signout` +- **400**: Bad request - Invalid JSON, validation error, expiration date in the past, or invalid TTL value + - Content-Type: `application/json` + - Example response: -This endpoint signs out a user, ending their authenticated session. + ```json + { + "message": "Expiration date must be in the future" + } + ``` -#### Request Body +- **401**: Authentication failed - Invalid credentials or connection failed + - Content-Type: `application/json` + - Example response: -- Content-Type: `application/x-www-form-urlencoded` -- Example request: + ```json + { + "message": "Invalid credentials or connection failed" + } + ``` + +- **500**: Server configuration error - Missing NEXTAUTH_SECRET + - Content-Type: `application/json` + - Example response: ```json { - "csrfToken": "insert csrfToken", - "callbackUrl": "/login", - "json": true + "message": "Server configuration error: NEXTAUTH_SECRET not set" } ``` +### **List JWT tokens** - `GET /api/auth/tokens` + +Get a list of active JWT tokens. Admins see all tokens, regular users see only their own tokens. + +#### Headers +- `Authorization: Bearer ` (required) + #### Responses -- **200**: Successful logout +- **200**: List of tokens retrieved successfully - Content-Type: `application/json` - Example response: ```json { - "url": "http://localhost:3000/api/auth/signout?csrf=true" + "tokens": [ + { + "user_id": "7262bcaecc2b06ff66e28ede90e6dce39c218685af9272d7a3fbd63ae08d17c2", + "token_id": "1761055513181-215c579b-c6e1-4f10-9b07-aacbf89cda21", + "created_at": "2025-10-21T14:05:13.182Z", + "expires_at": "2026-10-21T14:05:13.182Z", + "last_used": null, + "name": "API Token", + "permissions": ["Admin"], + "username": "adminuser" + } + ], + "count": 8 } ``` ---- +- **401**: Authentication failed - invalid or missing token +- **500**: Internal server error -## Settings +### **Get token metadata** - `GET /api/auth/tokens/{tokenId}` -### **Set Configuration Value** - `POST /api/config` +Get detailed metadata for a specific JWT token by its token ID. Admins can view any token, regular users can only view their own tokens. -This endpoint sets a configuration value for `MAX_QUEUED_QUERIES`. +#### Headers +- `Authorization: Bearer ` (required) #### Parameters - -- `cookie` (header, required): Cookie header with session and auth tokens. -- `config` (query, required): The configuration name. -- `value` (query, required): The integer value to set. +- `tokenId` (path, required): Token ID to retrieve + - Example: `1761053108078-554350d7-c965-4ed7-8d32-679b7f705e81` #### Responses -- **200**: Successful configuration update +- **200**: Token metadata retrieved successfully - Content-Type: `application/json` - Example response: ```json { - "config": "OK" + "token": { + "user_id": "e5d09e7d2141f77f80008ff73f04104b9484f59baa8e19a4ea758495d289fd0f", + "token_id": "1761053108078-554350d7-c965-4ed7-8d32-679b7f705e81", + "created_at": "2025-10-21T13:25:08.085Z", + "expires_at": "2026-10-21T13:25:08.085Z", + "last_used": null, + "name": "API Token", + "permissions": ["Read-Only"], + "username": "readonlyuser" + } } ``` -### **Get Configuration Value** - `GET /api/config` - -This endpoint retrieves the value for `MAX_QUEUED_QUERIES`. - -#### Parameters - -- `cookie` (header, required): Cookie header with session and auth tokens. -- `config` (query, required): The name of the configuration to retrieve. +- **401**: Authentication failed - invalid or missing token +- **403**: Forbidden - You can only view your own tokens (unless you are an Admin) + - Content-Type: `application/json` + - Example response: -#### Responses + ```json + { + "message": "Forbidden: You can only view your own tokens" + } + ``` -- **200**: Successful configuration retrieval +- **404**: Token not found - Content-Type: `application/json` - Example response: ```json { - "config": [ - "MAX_QUEUED_QUERIES", - 25 - ] + "message": "Token not found" } ``` -### **Create New User** - `POST /api/user` +- **500**: Internal server error -This endpoint creates a new user with specified credentials. +### **Revoke token by ID** - `DELETE /api/auth/tokens/{tokenId}` -#### Request Body +Revoke a specific JWT token by its token ID. Once revoked, the token cannot be used for authentication. Admins can revoke any token, regular users can only revoke their own tokens. -- Content-Type: `application/json` -- Example request: +#### Headers +- `Authorization: Bearer ` (required) + +#### Parameters +- `tokenId` (path, required): Token ID to revoke + - Example: `1761053108078-554350d7-c965-4ed7-8d32-679b7f705e81` + +#### Responses + +- **200**: Token revoked successfully + - Content-Type: `application/json` + - Example response: ```json { - "username": "user", - "password": "Pass123@", - "role": "Read-Write" + "message": "Token revoked successfully", + "tokenId": "1761053108078-554350d7-c965-4ed7-8d32-679b7f705e81" } ``` -#### Responses - -- **201**: User created successfully +- **400**: Bad request - Token is already revoked - Content-Type: `application/json` - Example response: ```json { - "message": "User created" + "message": "Token is already revoked" } ``` -### **Delete User** - `DELETE /api/user` +- **401**: Authentication failed - invalid or missing token -This endpoint deletes a user based on their username and role. +- **403**: Forbidden - You can only revoke your own tokens (unless you are an Admin) + - Content-Type: `application/json` + - Example response: -#### Request Body + ```json + { + "message": "Forbidden: You can only revoke your own tokens" + } + ``` -- Content-Type: `application/json` -- Example request: +- **404**: Token not found + - Content-Type: `application/json` + - Example response: ```json { - "users": [ - { - "username": "userName", - "role": "Read-Write" - } - ] + "message": "Token not found" } ``` +- **500**: Internal server error + +--- + +## Status + +### **Check FalkorDB connection status** - `GET /api/status` + +Returns the current connection status to the FalkorDB database. + +#### Headers +- `Authorization: Bearer ` (required) + #### Responses -- **200**: User deleted successfully +- **200**: Database is online and accessible - Content-Type: `application/json` - Example response: ```json { - "message": "User deleted" + "status": "online" } ``` -### **Get All Users** - `GET /api/user` +- **404**: Database is offline or not accessible +- **500**: Internal server error + +--- + +## Graph Management -This endpoint retrieves a list of all users. +### **List all graphs** - `GET /api/graph` + +Get a list of all graphs in the FalkorDB instance. + +#### Headers +- `Authorization: Bearer ` (required) #### Responses -- **200**: List of users retrieved successfully +- **200**: List of graphs retrieved successfully - Content-Type: `application/json` - Example response: ```json { - "result": [ - { - "username": "default", - "role": "Admin", - "checked": false - } + "opts": [ + "social_network", + "product_catalog", + "user_interactions" ] } ``` -### **Modify A User** - `PATCH /api/user/{userName}` +- **400**: Bad request +- **500**: Internal server error -This endpoint updates the role of a specific user. +### **Execute graph query** - `GET /api/graph/{graph}` + +Execute a Cypher query on the specified graph (Server-Sent Events). + +#### Headers +- `Authorization: Bearer ` (required) #### Parameters +- `graph` (path, required): Graph name to query + - Example: `social_network` +- `query` (query, required): Cypher query to execute + - Example: `MATCH (n) RETURN n LIMIT 10` +- `timeout` (query, required): Query timeout in milliseconds + - Example: `30000` + +#### Responses -- `cookie` (header, required): Cookie header with session and auth tokens. -- `userName` (path, required): The username of the user to modify. -- `role` (query, required): The new role to assign to the user (`Admin`, `Read-Only`, `Read-Write`). +- **200**: Query executed successfully (Server-Sent Events stream) + +### **Create or verify a graph** - `POST /api/graph/{graph}` + +Create a new graph or verify that a graph exists. + +#### Headers +- `Authorization: Bearer ` (required) + +#### Parameters +- `graph` (path, required): Graph name to create or verify #### Responses -- **200**: User updated successfully +- **200**: Graph created or verified successfully - Content-Type: `application/json` - Example response: ```json { - "message": "User role updated" + "message": "Graph created successfully" } ``` ---- +- **400**: Bad request +- **500**: Internal server error -## Graph +### **Rename graph** - `PATCH /api/graph/{graph}` -### **Create A Graph & Run A Query** - `GET /api/graph/{graphName}` +Rename an existing graph to a new name. -This endpoint creates a graph and runs a query. +#### Headers +- `Authorization: Bearer ` (required) #### Parameters - -- `cookie` (header, required): Cookie header with session and auth tokens. -- `graphName` (path, required): The name of the graph to be created. -- `query` (query, required): The query to run, such as `RETURN 1`. +- `graph` (path, required): New graph name +- `sourceName` (query, required): Current graph name to rename #### Responses -- **200**: Graph created and query executed +- **200**: Graph renamed successfully - Content-Type: `application/json` - Example response: ```json { - "result": { - "metadata": [ - "Nodes created: 40", - "Relationships created: 20", - "Cached execution: 1", - "Query internal execution time: 0.201420 milliseconds" - ], - "data": [ - { - "queryData": "exampleData" - } - ] + "data": { + "result": "Graph renamed successfully" } } ``` -### **Delete A Graph** - `DELETE /api/graph/{graphName}` +- **400**: Bad request - graph already exists or missing sourceName +- **500**: Internal server error -This endpoint deletes a specified graph. +### **Delete a graph** - `DELETE /api/graph/{graph}` -#### Parameters +Delete a graph from the FalkorDB instance. + +#### Headers +- `Authorization: Bearer ` (required) -- `cookie` (header, required): Cookie header with session and auth tokens. -- `graphName` (path, required): The name of the graph to be deleted. +#### Parameters +- `graph` (path, required): Graph name to delete #### Responses @@ -309,36 +511,113 @@ This endpoint deletes a specified graph. ```json { - "message": "GraphName graph deleted" + "message": "graph_name graph deleted" } ``` -### **Get All Graphs** - `GET /api/graph` +- **400**: Bad request +- **500**: Internal server error + +### **Get query execution plan** - `GET /api/graph/{graph}/explain` -This endpoint retrieves a list of all graphs. +Get the execution plan for a Cypher query without executing it. + +#### Headers +- `Authorization: Bearer ` (required) + +#### Parameters +- `graph` (path, required): Graph name +- `query` (query, required): Cypher query to explain #### Responses -- **200**: List of graphs retrieved successfully +- **200**: Query execution plan returned successfully + +### **Profile query execution** - `GET /api/graph/{graph}/profile` + +Get detailed profiling information for a Cypher query. + +#### Headers +- `Authorization: Bearer ` (required) + +#### Parameters +- `graph` (path, required): Graph name +- `query` (query, required): Cypher query to profile + +#### Responses + +- **200**: Query profiling information returned successfully + +### **Get graph information** - `GET /api/graph/{graph}/info` + +Get specific information about a graph (functions, property keys, labels, or relationship types). + +#### Headers +- `Authorization: Bearer ` (required) + +#### Parameters +- `graph` (path, required): Graph name +- `type` (query, required): Type of information to retrieve + - Options: `(function)`, `(property key)`, `(label)`, `(relationship type)` + - Example: `(label)` + +#### Responses + +- **200**: Graph information retrieved successfully - Content-Type: `application/json` - Example response: ```json { - "result": [ - "graphName" - ] + "result": { + "data": [ + {"(label)": "Person"}, + {"(label)": "Company"} + ] + } } ``` -### **Duplicate A Graph** - `POST /api/graph/{destinationGraphName}` +- **400**: Bad request - missing or invalid type parameter + +### **Get graph element counts** - `GET /api/graph/{graph}/count` + +Get the count of nodes and relationships in a graph. + +#### Headers +- `Authorization: Bearer ` (required) + +#### Parameters +- `graph` (path, required): Graph name + +#### Responses + +- **200**: Element counts retrieved successfully -This endpoint duplicates a graph from source to destination. +### **Export graph data** - `GET /api/graph/{graph}/export` + +Export graph data in various formats. + +#### Headers +- `Authorization: Bearer ` (required) #### Parameters +- `graph` (path, required): Graph name + +#### Responses + +- **200**: Graph data exported successfully + +### **Duplicate a graph** - `PATCH /api/graph/{graph}/duplicate` + +Create a copy of an existing graph with a new name. + +#### Headers +- `Authorization: Bearer ` (required) -- `destinationGraphName` (path, required): The name of the destination graph. -- `sourceName` (query, required): The name of the source graph to duplicate. +#### Parameters +- `graph` (path, required): New graph name for the duplicate +- `sourceName` (query, required): Source graph name to duplicate from #### Responses @@ -348,22 +627,29 @@ This endpoint duplicates a graph from source to destination. ```json { - "success": "OK" + "result": { + "status": "Graph duplicated successfully" + } } ``` -### **Get Graph Count** - `GET /api/graph/{graphName}/count` +- **400**: Bad request - missing sourceName parameter +- **500**: Internal server error -This endpoint retrieves the count of nodes and edges in a specified graph. +### **Get node information** - `GET /api/graph/{graph}/{node}` -#### Parameters +Get detailed information about a specific node. -- `cookie` (header, required): Cookie header with session and auth tokens. -- `graphName` (path, required): The name of the graph to count nodes and edges. +#### Headers +- `Authorization: Bearer ` (required) + +#### Parameters +- `graph` (path, required): Graph name +- `node` (path, required): Node ID #### Responses -- **200**: Graph count retrieved successfully +- **200**: Node information retrieved successfully - Content-Type: `application/json` - Example response: @@ -372,506 +658,916 @@ This endpoint retrieves the count of nodes and edges in a specified graph. "result": { "data": [ { - "nodes": 7417, - "edges": 4341 + "node": { + "id": 1, + "labels": ["Person"], + "properties": { + "name": "John Doe", + "age": 30 + } + }, + "relationships": [] } ] } } ``` -### **Add Node Attribute** - `POST /api/graph/{graphName}/{id}/{attribute}` +- **400**: Bad request +- **500**: Internal server error -This endpoint adds an attribute to a node in a graph. +### **Delete node or relationship** - `DELETE /api/graph/{graph}/{node}` -#### Parameters +Delete a node or relationship from the graph. + +#### Headers +- `Authorization: Bearer ` (required) -- `cookie` (header, required): Cookie header with session and auth tokens. -- `graphName` (path, required): The name of the graph. -- `id` (path, required): The ID of the node to which the attribute will be added. -- `attribute` (path, required): The name of the attribute to add. +#### Parameters +- `graph` (path, required): Graph name +- `node` (path, required): Node or relationship ID #### Request Body - Content-Type: `application/json` -- Example request: +- Required field: `type` - ```json - { - "value": "your_attribute_value", - "type": true - } - ``` +Example request: +```json +{ + "type": true +} +``` + +- `type`: `true` to delete a node, `false` to delete a relationship #### Responses -- **200**: Node attribute added successfully +- **200**: Node or relationship deleted successfully - Content-Type: `application/json` - Example response: ```json { - "result": { - "metadata": [ - "Cached execution: 0", - "Query internal execution time: 0.412958 milliseconds" - ] - } + "message": "Node deleted successfully" } ``` -### **Delete Node Attribute** - `DELETE /api/graph/{graphName}/{id}/{attribute}` +- **400**: Bad request - missing type parameter +- **500**: Internal server error -This endpoint deletes an attribute from a node in a graph. +### **Add node label** - `POST /api/graph/{graph}/{node}/label` -#### Parameters +Add a label to a specific node. + +#### Headers +- `Authorization: Bearer ` (required) -- `cookie` (header, required): Cookie header with session and auth tokens. -- `graphName` (path, required): The name of the graph. -- `id` (path, required): The ID of the node from which the attribute will be deleted. -- `attribute` (path, required): The name of the attribute to delete. +#### Parameters +- `graph` (path, required): Graph name +- `node` (path, required): Node ID #### Request Body - Content-Type: `application/json` -- Example request: - ```json - { - "type": true - } - ``` +Example request: +```json +{ + "label": "your_label" +} +``` #### Responses -- **200**: Node attribute deleted successfully - - Content-Type: `application/json` - - Example response: +- **200**: Label added successfully - ```json - { - "result": { - "metadata": [ - "Cached execution: 0", - "Query internal execution time: 0.407125 milliseconds" - ] - } - } - ``` +### **Remove node label** - `DELETE /api/graph/{graph}/{node}/label` -### **Add Node Label** - `POST /api/graph/{graphName}/{id}/label` +Remove a label from a specific node. -This endpoint adds a label to a node in a graph. +#### Headers +- `Authorization: Bearer ` (required) #### Parameters - -- `cookie` (header, required): Cookie header with session and auth tokens. -- `graphName` (path, required): The name of the graph. -- `id` (path, required): The ID of the node to which the label will be added. +- `graph` (path, required): Graph name +- `node` (path, required): Node ID #### Request Body - Content-Type: `application/json` -- Example request: - ```json - { - "label": "your_label_name" - } - ``` +Example request: +```json +{ + "label": "your_label" +} +``` #### Responses -- **200**: Node label added successfully - - Content-Type: `application/json` - - Example response: +- **200**: Label removed successfully - ```json - { - "message": "Label added successfully" - } - ``` +### **Set node/relationship property** - `POST /api/graph/{graph}/{node}/{key}` -### **Delete Node Label** - `DELETE /api/graph/{graphName}/{id}/label` +Set a property value on a node or relationship. -This endpoint deletes a label from a node in a graph. +**IMPORTANT:** Use `type=true` for nodes, `type=false` for relationships. + +#### Headers +- `Authorization: Bearer ` (required) #### Parameters +- `graph` (path, required): Graph name +- `node` (path, required): Node or relationship ID +- `key` (path, required): Property key name + +#### Request Body + +- Content-Type: `application/json` +- Required fields: `value`, `type` + +Example request: +```json +{ + "value": "your_property_value", + "type": true +} +``` + +- `value`: Property value to set +- `type`: `true` for nodes, `false` for relationships -- `cookie` (header, required): Cookie header with session and auth tokens. -- `graphName` (path, required): The name of the graph. -- `id` (path, required): The ID of the node from which the label will be deleted. +#### Responses + +- **200**: Property set successfully + +### **Remove node/relationship property** - `DELETE /api/graph/{graph}/{node}/{key}` + +Remove a property from a node or relationship. + +**IMPORTANT:** Use `type=true` for nodes, `type=false` for relationships. + +#### Headers +- `Authorization: Bearer ` (required) + +#### Parameters +- `graph` (path, required): Graph name +- `node` (path, required): Node or relationship ID +- `key` (path, required): Property key name #### Request Body - Content-Type: `application/json` -- Example request: +- Required field: `type` - ```json - { - "label": "your_label_name" - } - ``` +Example request: +```json +{ + "type": true +} +``` + +- `type`: `true` for nodes, `false` for relationships #### Responses -- **200**: Node label deleted successfully +- **200**: Property removed successfully + +--- + +## Configuration Management + +### **Get all configuration values** - `GET /api/graph/config` + +Get all FalkorDB configuration parameters and their values. + +#### Headers +- `Authorization: Bearer ` (required) + +#### Responses + +- **200**: Configuration values retrieved successfully - Content-Type: `application/json` - Example response: ```json { - "message": "Label removed successfully" + "configs": { + "MAX_INFO_QUERIES": 700, + "CMD_INFO": "server", + "TIMEOUT": 1000 + } } ``` -### **Delete Node** - `DELETE /api/graph/{graphName}/{id}` +- **400**: Bad request +- **500**: Internal server error -This endpoint deletes a node from a graph. +### **Get specific configuration value** - `GET /api/graph/config/{config}` -#### Parameters +Get the value of a specific configuration parameter. -- `cookie` (header, required): Cookie header with session and auth tokens. -- `graphName` (path, required): The name of the graph. -- `id` (path, required): The ID of the node to delete. +#### Headers +- `Authorization: Bearer ` (required) -#### Request Body +#### Parameters +- `config` (path, required): Configuration parameter name + - Example: `MAX_INFO_QUERIES` -- Content-Type: `application/json` -- Example request: +#### Responses + +- **200**: Configuration value retrieved successfully + - Content-Type: `application/json` + - Example response: ```json { - "type": true + "config": 700 } ``` +- **400**: Bad request +- **500**: Internal server error + +### **Set configuration value** - `POST /api/graph/config/{config}` + +Set the value of a specific configuration parameter. + +#### Headers +- `Authorization: Bearer ` (required) + +#### Parameters +- `config` (path, required): Configuration parameter name + - Example: `MAX_INFO_QUERIES` +- `value` (query, required): Configuration value to set (numeric values will be parsed as integers except for CMD_INFO) + - Example: `700` + #### Responses -- **200**: Node deleted successfully +- **200**: Configuration value set successfully - Content-Type: `application/json` - Example response: ```json { - "message": "Node deleted successfully" + "config": "OK" } ``` +- **400**: Bad request - missing value or invalid value +- **500**: Internal server error + --- -## Schema +## Schema Management + +### **List all schemas** - `GET /api/schema` + +Get a list of all schemas in the FalkorDB instance. + +#### Headers +- `Authorization: Bearer ` (required) + +#### Responses + +- **200**: List of schemas retrieved successfully -### **Create New Schema & Run A Query** - `GET /api/graph/{schemaName}` +### **Get schema information** - `GET /api/schema/{schema}` -This endpoint creates a new schema and runs a query. +Get detailed information about a specific schema. + +#### Headers +- `Authorization: Bearer ` (required) + +#### Parameters +- `schema` (path, required): Schema name + +#### Responses + +- **200**: Schema information retrieved successfully + +### **Create new schema** - `POST /api/schema/{schema}` + +Create a new schema with the specified name. + +#### Headers +- `Authorization: Bearer ` (required) #### Parameters +- `schema` (path, required): Schema name to create + +#### Responses + +- **201**: Schema created successfully -- `schemaName` (path, required): The name of the schema to create. -- `query` (query, required): The query to execute. +### **Rename schema** - `PATCH /api/schema/{schema}` + +Rename an existing schema to a new name. + +#### Headers +- `Authorization: Bearer ` (required) + +#### Parameters +- `schema` (path, required): New schema name +- `sourceName` (query, required): Current schema name to rename #### Responses -- **200**: Schema created and query executed +- **200**: Schema renamed successfully - Content-Type: `application/json` - Example response: ```json { - "result": { - "metadata": [ - "Cached execution: 0", - "Query internal execution time: 0.153307 milliseconds" - ], - "data": [ - { - "1": 1 - } - ] + "data": { + "result": "Schema renamed successfully" } } ``` -### **Delete A Schema** - `DELETE /api/graph/{schemaName}` +- **400**: Bad request - schema already exists or missing sourceName +- **500**: Internal server error -This endpoint deletes a specified schema. +### **Delete schema** - `DELETE /api/schema/{schema}` -#### Parameters +Delete a schema and all its data permanently. -- `schemaName` (path, required): The name of the schema to delete. +#### Headers +- `Authorization: Bearer ` (required) + +#### Parameters +- `schema` (path, required): Schema name to delete #### Responses - **200**: Schema deleted successfully - - Content-Type: `application/json` - - Example response: - ```json - { - "message": "SchemaName schema deleted" - } - ``` +### **Get schema element counts** - `GET /api/schema/{schema}/count` -### **Get Schema Count** - `GET /api/schema/{schemaName}/count` +Get the count of nodes and relationships in a schema. -This endpoint retrieves the count of nodes and edges in a specified schema. +#### Headers +- `Authorization: Bearer ` (required) #### Parameters +- `schema` (path, required): Schema name + +#### Responses -- `cookie` (header, required): Cookie header with session and auth tokens. -- `schemaName` (path, required): The name of the schema to count nodes and edges. +- **200**: Schema element counts retrieved successfully + +### **Duplicate schema** - `PATCH /api/schema/{schema}/duplicate` + +Create a copy of an existing schema with a new name, preserving all data and structure. + +#### Headers +- `Authorization: Bearer ` (required) + +#### Parameters +- `schema` (path, required): New schema name for the duplicate +- `sourceName` (query, required): Source schema name to duplicate from #### Responses -- **200**: Schema count retrieved successfully +- **200**: Schema duplicated successfully - Content-Type: `application/json` - Example response: ```json { "result": { - "data": [ - { - "nodes": 0, - "edges": 0 - } - ] + "status": "Schema duplicated successfully" } } ``` -### **Add Schema Node** - `POST /api/schema/{schemaName}/{id}` +- **400**: Bad request - missing sourceName parameter +- **500**: Internal server error + +### **Create node or relationship in schema** - `POST /api/schema/{schema}/new` -This endpoint adds a node to a schema. +The actual backend endpoint for creating nodes and relationships. Use `type=true` for nodes, `type=false` for relationships. + +#### Headers +- `Authorization: Bearer ` (required) #### Parameters +- `schema` (path, required): Schema name -- `cookie` (header, required): Cookie header with session and auth tokens. -- `schemaName` (path, required): The name of the schema. -- `id` (path, required): The ID of the node to add (use -1 for new nodes). +#### Request Body + +- Content-Type: `application/json` +- Required fields: `type`, `label`, `attributes` + +Example request for node creation: +```json +{ + "type": true, + "label": ["Person", "User"], + "attributes": [ + ["name", ["STRING", "", "false", "true"]], + ["age", ["INTEGER", "0", "false", "false"]] + ] +} +``` + +Example request for relationship creation: +```json +{ + "type": false, + "label": ["KNOWS"], + "attributes": [ + ["since", ["STRING", "2024", "false", "false"]] + ], + "selectedNodes": [{"id": 1}, {"id": 2}] +} +``` + +- `type`: `true` for node creation, `false` for relationship creation +- `label`: For nodes: Multiple labels supported (e.g., `["Person", "User"]`). For relationships: Relationship type (only first label used, e.g., `["KNOWS"]`) +- `attributes`: Attribute definitions: `[[key, [type, default, unique, required]], ...]` +- `selectedNodes`: Required for relationship creation only. Source and target nodes (exactly 2 nodes) + +#### Responses + +- **200**: Node or relationship created successfully + +### **Create node in schema** - `POST /api/schema/{schema}/nodes` + +Create a new node in the specified schema. Multiple labels are supported and will be joined with colons (e.g., `:Person:User`). This endpoint maps to `/api/schema/{schema}/new` with `type=true`. + +#### Headers +- `Authorization: Bearer ` (required) + +#### Parameters +- `schema` (path, required): Schema name #### Request Body - Content-Type: `application/json` -- Example request: +- Required fields: `type`, `label`, `attributes` + +Example request: +```json +{ + "type": true, + "label": ["Person", "User"], + "attributes": [ + ["name", ["STRING", "", "false", "true"]], + ["age", ["INTEGER", "0", "false", "false"]] + ] +} +``` + +- `type`: Must be `true` for node creation +- `label`: Labels for the node (multiple labels supported) +- `attributes`: Attribute definitions: `[[key, [type, default, unique, required]], ...]` - ```json - { - "type": true, - "label": ["your_label_name"], - "attributes": [["attribute_name", ["String", "default_value", "true", "true"]]], - "selectedNodes": [null, null] - } - ``` +#### Responses + +- **200**: Node created successfully + +### **Create relationship in schema** - `POST /api/schema/{schema}/relationships` + +Create a new relationship between two nodes in the specified schema. Only the first label in the array is used as the relationship type. This endpoint maps to `/api/schema/{schema}/new` with `type=false`. + +#### Headers +- `Authorization: Bearer ` (required) + +#### Parameters +- `schema` (path, required): Schema name + +#### Request Body + +- Content-Type: `application/json` +- Required fields: `type`, `label`, `attributes`, `selectedNodes` + +Example request: +```json +{ + "type": false, + "label": ["KNOWS"], + "attributes": [ + ["since", ["STRING", "2024", "false", "false"]] + ], + "selectedNodes": [{"id": 1}, {"id": 2}] +} +``` + +- `type`: Must be `false` for relationship creation +- `label`: Relationship type (only first label used) +- `attributes`: Attribute definitions: `[[key, [type, default, unique, required]], ...]` +- `selectedNodes`: Source and target nodes for the relationship (exactly 2 nodes) #### Responses -- **200**: Schema node added successfully - - Content-Type: `application/json` - - Example response: +- **200**: Relationship created successfully - ```json - { - "result": { - "metadata": [ - "Labels added: 1", - "Nodes created: 1", - "Properties set: 1", - "Cached execution: 0", - "Query internal execution time: 0.987458 milliseconds" - ], - "data": [ - { - "n": { - "id": 0, - "labels": [ - "your_label_name" - ], - "properties": { - "attribute_name": "String!*default_value" - } - } - } - ] - } - } - ``` +### **Delete node from schema** - `DELETE /api/schema/{schema}/{nodeId}` -### **Delete Schema Node** - `DELETE /api/schema/{schemaName}/{id}` +Delete a specific node from the schema by ID. Set `type=true` for node deletion. -This endpoint deletes a node from a schema. +#### Headers +- `Authorization: Bearer ` (required) #### Parameters +- `schema` (path, required): Schema name +- `nodeId` (path, required): Node ID to delete + +#### Request Body + +- Content-Type: `application/json` +- Required field: `type` + +Example request: +```json +{ + "type": true +} +``` + +- `type`: Must be `true` for node deletion + +#### Responses + +- **200**: Node deleted successfully + +### **Delete relationship from schema** - `DELETE /api/schema/{schema}/{relationshipId}` -- `cookie` (header, required): Cookie header with session and auth tokens. -- `schemaName` (path, required): The name of the schema. -- `id` (path, required): The ID of the node to delete. +Delete a specific relationship from the schema by ID. Set `type=false` for relationship deletion. + +#### Headers +- `Authorization: Bearer ` (required) + +#### Parameters +- `schema` (path, required): Schema name +- `relationshipId` (path, required): Relationship ID to delete #### Request Body - Content-Type: `application/json` -- Example request: +- Required field: `type` - ```json - { - "type": true - } - ``` +Example request: +```json +{ + "type": false +} +``` + +- `type`: Must be `false` for relationship deletion #### Responses -- **200**: Schema node deleted successfully - - Content-Type: `application/json` - - Example response: +- **200**: Relationship deleted successfully - ```json - { - "message": "Node deleted successfully" - } - ``` +### **Add label to node** - `POST /api/schema/{schema}/{node}/label` -### **Add Schema Attribute** - `PATCH /api/schema/{schemaName}/{id}/{attribute}` +Add a new label to an existing node in the schema. -This endpoint adds an attribute to a node in a schema. +#### Headers +- `Authorization: Bearer ` (required) #### Parameters +- `schema` (path, required): Schema name +- `node` (path, required): Node ID -- `cookie` (header, required): Cookie header with session and auth tokens. -- `schemaName` (path, required): The name of the schema. -- `id` (path, required): The ID of the node to which the attribute will be added. -- `attribute` (path, required): The name of the attribute to add. +#### Request Body + +- Content-Type: `application/json` +- Required field: `label` + +Example request: +```json +{ + "label": "your_label" +} +``` + +#### Responses + +- **200**: Label added successfully + +### **Remove label from node** - `DELETE /api/schema/{schema}/{node}/label` + +Remove a specific label from an existing node in the schema. + +#### Headers +- `Authorization: Bearer ` (required) + +#### Parameters +- `schema` (path, required): Schema name +- `node` (path, required): Node ID #### Request Body - Content-Type: `application/json` -- Example request: +- Required field: `label` - ```json - { - "type": true, - "attribute": ["String", "default_value", "true", "true"] - } - ``` +Example request: +```json +{ + "label": "your_label" +} +``` #### Responses -- **200**: Schema node attribute added successfully - - Content-Type: `application/json` - - Example response: +- **200**: Label removed successfully - ```json - { - "message": "Attribute updated successfully" - } - ``` +### **Add/Update attribute to node** - `PATCH /api/schema/{schema}/{nodeId}/{key}` + +Add a new attribute or update an existing attribute on a node in the schema. + +#### Headers +- `Authorization: Bearer ` (required) + +#### Parameters +- `schema` (path, required): Schema name (example: `test`) +- `nodeId` (path, required): Node ID (example: `2`) +- `key` (path, required): Attribute key to add/update (example: `attribute_key`) + +#### Request Body + +- Content-Type: `application/json` +- Required fields: `type`, `attribute` + +Example request: +```json +{ + "type": true, + "attribute": ["STRING", "your_description", "false", "true"] +} +``` -### **Delete Schema Attribute** - `DELETE /api/schema/{schemaName}/{id}/{attribute}` +- `type`: Must be `true` for node attributes +- `attribute`: Attribute configuration `[type, default, unique, required]` -This endpoint deletes an attribute from a node in a schema. +#### Responses + +- **200**: Attribute added/updated successfully + +### **Remove attribute from node** - `DELETE /api/schema/{schema}/{nodeId}/{key}` + +Remove a specific attribute from a node in the schema. + +#### Headers +- `Authorization: Bearer ` (required) #### Parameters +- `schema` (path, required): Schema name (example: `test`) +- `nodeId` (path, required): Node ID (example: `2`) +- `key` (path, required): Attribute key to remove (example: `attribute_key`) + +#### Request Body + +- Content-Type: `application/json` +- Required field: `type` + +Example request: +```json +{ + "type": true +} +``` + +- `type`: Must be `true` for node attributes + +#### Responses + +- **200**: Attribute removed successfully + +### **Add/Update attribute to relationship** - `PATCH /api/schema/{schema}/{relationshipId}/{key}` + +Add a new attribute or update an existing attribute on a relationship in the schema. -- `cookie` (header, required): Cookie header with session and auth tokens. -- `schemaName` (path, required): The name of the schema. -- `id` (path, required): The ID of the node from which the attribute will be deleted. -- `attribute` (path, required): The name of the attribute to delete. +#### Headers +- `Authorization: Bearer ` (required) + +#### Parameters +- `schema` (path, required): Schema name (example: `test`) +- `relationshipId` (path, required): Relationship ID (example: `1`) +- `key` (path, required): Attribute key to add/update (example: `since`) #### Request Body - Content-Type: `application/json` -- Example request: +- Required fields: `type`, `attribute` - ```json - { - "type": true - } - ``` +Example request: +```json +{ + "type": false, + "attribute": ["STRING", "2024", "false", "false"] +} +``` + +- `type`: Must be `false` for relationship attributes +- `attribute`: Attribute configuration `[type, default, unique, required]` + +#### Responses + +- **200**: Attribute added/updated successfully + +### **Remove attribute from relationship** - `DELETE /api/schema/{schema}/{relationshipId}/{key}` + +Remove a specific attribute from a relationship in the schema. + +#### Headers +- `Authorization: Bearer ` (required) + +#### Parameters +- `schema` (path, required): Schema name (example: `test`) +- `relationshipId` (path, required): Relationship ID (example: `1`) +- `key` (path, required): Attribute key to remove (example: `since`) + +#### Request Body + +- Content-Type: `application/json` +- Required field: `type` + +Example request: +```json +{ + "type": false +} +``` + +- `type`: Must be `false` for relationship attributes + +#### Responses + +- **200**: Attribute removed successfully + +--- + +## User Management + +### **List all users** - `GET /api/user` + +Get a list of all FalkorDB users. + +#### Headers +- `Authorization: Bearer ` (required) #### Responses -- **200**: Schema node attribute deleted successfully +- **200**: List of users retrieved successfully - Content-Type: `application/json` - Example response: ```json { - "message": "Attribute deleted successfully" + "result": [ + { + "username": "john_doe", + "role": "Read-Write", + "selected": false + }, + { + "username": "admin_user", + "role": "Admin", + "selected": false + } + ] } ``` -### **Add Schema Label** - `POST /api/schema/{schemaName}/{id}/label` +- **400**: Bad request +- **500**: Internal server error -This endpoint adds a label to a node in a schema. +### **Create new user** - `POST /api/user` -#### Parameters +Create a new FalkorDB user with specified username, password, and role. -- `cookie` (header, required): Cookie header with session and auth tokens. -- `schemaName` (path, required): The name of the schema. -- `id` (path, required): The ID of the node to which the label will be added. +#### Headers +- `Authorization: Bearer ` (required) #### Request Body - Content-Type: `application/json` -- Example request: +- Required fields: `username`, `password`, `role` - ```json - { - "label": "your_label_name" - } - ``` +Example request: +```json +{ + "username": "new_user", + "password": "secure_password", + "role": "Read-Write" +} +``` + +- `username`: Username for the new user +- `password`: Password for the new user +- `role`: Role to assign to the user (`Admin`, `Read-Write`, `Read-Only`) #### Responses -- **200**: Schema node label added successfully +- **201**: User created successfully - Content-Type: `application/json` - Example response: ```json { - "result": { - "metadata": [ - "Cached execution: 0", - "Query internal execution time: 0.417250 milliseconds" - ] - } + "message": "Success" } ``` -### **Delete Schema Label** - `DELETE /api/schema/{schemaName}/{id}/label` + - Headers: + - `location`: Location of the created user resource (example: `/api/db/user/new_user`) -This endpoint deletes a label from a node in a schema. +- **400**: Bad request - missing parameters +- **409**: User already exists +- **500**: Internal server error -#### Parameters +### **Delete multiple users** - `DELETE /api/user` -- `cookie` (header, required): Cookie header with session and auth tokens. -- `schemaName` (path, required): The name of the schema. -- `id` (path, required): The ID of the node from which the label will be deleted. +Delete multiple FalkorDB users by providing an array of usernames. + +#### Headers +- `Authorization: Bearer ` (required) #### Request Body - Content-Type: `application/json` -- Example request: +- Required field: `users` - ```json - { - "label": "your_label_name" - } - ``` +Example request: +```json +{ + "users": [ + { "username": "user_1741261105156" }, + { "username": "another_user" } + ] +} +``` + +- `users`: Array of user objects to delete #### Responses -- **200**: Schema node label deleted successfully +- **200**: Users deleted successfully - Content-Type: `application/json` - Example response: ```json { - "result": { - "metadata": [ - "Cached execution: 0", - "Query internal execution time: 0.829917 milliseconds" - ] - } + "message": "Users deleted" } ``` + +- **400**: Bad request +- **500**: Internal server error + +### **Update user role** - `PATCH /api/user/{user}` + +Update the role of a FalkorDB user. + +#### Headers +- `Authorization: Bearer ` (required) + +#### Parameters +- `user` (path, required): Username to update +- `role` (query, required): New role for the user (`Admin`, `Read-Write`, `Read-Only`) + +#### Responses + +- **200**: User role updated successfully + +--- + +## Error Responses + +All endpoints may return the following common error responses: + +- **401**: Unauthorized - Invalid or missing authentication token +- **403**: Forbidden - Insufficient permissions for the requested operation +- **404**: Not Found - Requested resource does not exist +- **500**: Internal Server Error - Unexpected server error + +## Data Types + +### Attribute Types +The following data types are supported for node and relationship attributes: + +- `STRING`: Text values +- `INTEGER`: Numeric integer values +- `FLOAT`: Numeric decimal values +- `BOOLEAN`: True/false values + +### Attribute Configuration +When defining attributes, use the following format: +```json +[type, default_value, unique, required] +``` + +- `type`: One of the supported data types (`STRING`, `INTEGER`, `FLOAT`, `BOOLEAN`) +- `default_value`: Default value for the attribute +- `unique`: `"true"` if the attribute must be unique, `"false"` otherwise +- `required`: `"true"` if the attribute is required, `"false"` otherwise + +Example: +```json +["STRING", "default_name", "false", "true"] +```