REST API Integration

<h2 id="rest-api-integration" class="position-relative d-flex align-items-center group"> REST API Integration <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="rest-api-integration" aria-haspopup="dialog" aria-label="Share link: REST API Integration"> Share link </button> </h2><div id="headingShareModal" class="heading-share-modal" role="dialog" aria-modal="true" aria-labelledby="headingShareTitle" hidden> <div class="hsm-dialog" role="document"> <div class="hsm-header"> <h2 id="headingShareTitle" class="h6 mb-0 fw-bold">Share this section</h2> <button type="button" class="hsm-close" aria-label="Close"> </button> </div> <div class="hsm-body"> <label for="headingShareInput" class="form-label small text-muted mb-1 text-uppercase fw-bold" style="font-size: 0.7rem; letter-spacing: 0.5px;">Permalink</label> <div class="input-group mb-4 hsm-url-group"> <input id="headingShareInput" type="text" class="form-control font-monospace" readonly aria-readonly="true" style="font-size: 0.85rem;" /> <button class="btn btn-primary hsm-copy" type="button" aria-label="Copy" title="Copy"> </button> </div> <div class="small fw-bold mb-2 text-muted text-uppercase" style="font-size: 0.7rem; letter-spacing: 0.5px;">Share via</div> <div class="hsm-share-grid"> <a id="share-twitter" class="btn btn-outline-secondary w-100" target="_blank" rel="noopener noreferrer"> Twitter </a> <a id="share-linkedin" class="btn btn-outline-secondary w-100" target="_blank" rel="noopener noreferrer"> LinkedIn </a> <a id="share-facebook" class="btn btn-outline-secondary w-100" target="_blank" rel="noopener noreferrer"> Facebook </a> </div> </div> </div> </div> <style> .heading-share-modal { position: fixed; inset: 0; display: flex; justify-content: center; align-items: center; background: rgba(0, 0, 0, 0.6); z-index: 1050; padding: 1rem; backdrop-filter: blur(4px); -webkit-backdrop-filter: blur(4px); } .heading-share-modal[hidden] { display: none !important; } .hsm-dialog { max-width: 420px; width: 100%; background: var(--bs-body-bg, #fff); color: var(--bs-body-color, #212529); border: 1px solid var(--bs-border-color, rgba(0,0,0,0.1)); border-radius: 1rem; box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.25); overflow: hidden; animation: hsm-fade-in 0.2s ease-out; } @keyframes hsm-fade-in { from { opacity: 0; transform: scale(0.95); } to { opacity: 1; transform: scale(1); } } [data-bs-theme="dark"] .hsm-dialog { background: #1e293b; border-color: rgba(255,255,255,0.1); color: #f8f9fa; } .hsm-header { display: flex; justify-content: space-between; align-items: center; padding: 1rem 1.5rem; border-bottom: 1px solid var(--bs-border-color, rgba(0,0,0,0.1)); background: rgba(0,0,0,0.02); } [data-bs-theme="dark"] .hsm-header { background: rgba(255,255,255,0.02); border-color: rgba(255,255,255,0.1); } .hsm-close { background: transparent; border: none; color: inherit; opacity: 0.5; padding: 0.25rem 0.5rem; border-radius: 0.25rem; font-size: 1.2rem; line-height: 1; transition: opacity 0.2s; } .hsm-close:hover { opacity: 1; } .hsm-body { padding: 1.5rem; } .hsm-url-group { display: flex !important; align-items: stretch; } .hsm-url-group .form-control { flex: 1; min-width: 0; margin: 0; background: var(--bs-secondary-bg, #f8f9fa); border-color: var(--bs-border-color, #dee2e6); border-top-right-radius: 0; border-bottom-right-radius: 0; height: 42px; } .hsm-url-group .btn { flex: 0 0 auto; margin: 0; margin-left: -1px; border-top-left-radius: 0; border-bottom-left-radius: 0; height: 42px; display: flex; align-items: center; justify-content: center; padding: 0 1.25rem; z-index: 2; } [data-bs-theme="dark"] .hsm-url-group .form-control { background: #0f172a; border-color: #334155; color: #e2e8f0; } .hsm-share-grid { display: flex; flex-direction: column; gap: 0.5rem; } .hsm-share-grid .btn { display: flex; align-items: center; justify-content: center; font-size: 0.9rem; padding: 0.6rem; border-color: var(--bs-border-color); width: 100%; } [data-bs-theme="dark"] .hsm-share-grid .btn { color: #e2e8f0; border-color: #475569; } [data-bs-theme="dark"] .hsm-share-grid .btn:hover { background: #334155; border-color: #cbd5e1; } </style> <script> (function(){ const modal = document.getElementById('headingShareModal'); if(!modal) return; const input = modal.querySelector('#headingShareInput'); const copyBtn = modal.querySelector('.hsm-copy'); const twitter = modal.querySelector('#share-twitter'); const linkedin = modal.querySelector('#share-linkedin'); const facebook = modal.querySelector('#share-facebook'); const closeBtn = modal.querySelector('.hsm-close'); let lastFocus=null; let trapBound=false; function buildUrl(id){ return window.location.origin + window.location.pathname + '#' + id; } function isOpen(){ return !modal.hasAttribute('hidden'); } function hydrate(id){ const url=buildUrl(id); input.value=url; const enc=encodeURIComponent(url); const text=encodeURIComponent(document.title); if(twitter) twitter.href=`https://twitter.com/intent/tweet?url=${enc}&text=${text}`; if(linkedin) linkedin.href=`https://www.linkedin.com/sharing/share-offsite/?url=${enc}`; if(facebook) facebook.href=`https://www.facebook.com/sharer/sharer.php?u=${enc}`; } function openModal(id){ lastFocus=document.activeElement; hydrate(id); if(!isOpen()){ modal.removeAttribute('hidden'); } requestAnimationFrame(()=>{ input.focus(); }); trapFocus(); } function closeModal(){ if(!isOpen()) return; modal.setAttribute('hidden',''); if(lastFocus && typeof lastFocus.focus==='function') lastFocus.focus(); } function copyCurrent(){ try{ navigator.clipboard.writeText(input.value).then(()=>feedback(true),()=>fallback()); } catch(e){ fallback(); } } function fallback(){ input.select(); try{ document.execCommand('copy'); feedback(true);}catch(e){ feedback(false);} } function feedback(ok){ if(!copyBtn) return; const icon=copyBtn.querySelector('i'); if(!icon) return; const prev=copyBtn.getAttribute('data-prev')||icon.className; if(!copyBtn.getAttribute('data-prev')) copyBtn.setAttribute('data-prev',prev); icon.className= ok ? 'fa-duotone fa-clipboard-check':'fa-duotone fa-circle-exclamation'; setTimeout(()=>{ icon.className=prev; },1800); } function handleShareClick(e){ e.preventDefault(); const btn=e.currentTarget; const id=btn.getAttribute('data-share-target'); if(id) openModal(id); } function bindShareButtons(){ document.querySelectorAll('.h-share').forEach(btn=>{ if(!btn.dataset.hShareBound){ btn.addEventListener('click', handleShareClick); btn.dataset.hShareBound='1'; } }); } bindShareButtons(); if(document.readyState==='loading'){ document.addEventListener('DOMContentLoaded', bindShareButtons); } else { requestAnimationFrame(bindShareButtons); } document.addEventListener('click', function(e){ const shareBtn=e.target.closest && e.target.closest('.h-share'); if(shareBtn && !shareBtn.dataset.hShareBound){ handleShareClick.call(shareBtn, e); } }, true); document.addEventListener('click', e=>{ if(e.target===modal) closeModal(); if(e.target.closest && e.target.closest('.hsm-close')){ e.preventDefault(); closeModal(); } if(copyBtn && (e.target===copyBtn || (e.target.closest && e.target.closest('.hsm-copy')))) { e.preventDefault(); copyCurrent(); } }); document.addEventListener('keydown', e=>{ if(e.key==='Escape' && isOpen()) closeModal(); }); function trapFocus(){ if(trapBound) return; trapBound=true; modal.addEventListener('keydown', f=>{ if(f.key==='Tab' && isOpen()){ const focusable=[...modal.querySelectorAll('a[href],button,input,textarea,select,[tabindex]:not([tabindex="-1"])')].filter(el=>!el.hasAttribute('disabled')); if(!focusable.length) return; const first=focusable[0]; const last=focusable[focusable.length-1]; if(f.shiftKey && document.activeElement===first){ f.preventDefault(); last.focus(); } else if(!f.shiftKey && document.activeElement===last){ f.preventDefault(); first.focus(); } } }); } if(closeBtn) closeBtn.addEventListener('click', e=>{ e.preventDefault(); closeModal(); }); })(); </script>Geode provides a comprehensive REST API for HTTP-based integration, enabling access from any platform or language that can make HTTP requests. While native QUIC clients offer optimal performance, the REST API provides broad compatibility, ease of use, and standardized error handling for web services and microservices architectures. <h3 id="introduction-to-geode-rest-api" class="position-relative d-flex align-items-center group"> Introduction to Geode REST API <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="introduction-to-geode-rest-api" aria-haspopup="dialog" aria-label="Share link: Introduction to Geode REST API"> Share link </button> </h3>The REST API exposes all core Geode functionality through HTTP endpoints, following RESTful design principles. The API is designed for: <ul> <li>Cross-Platform Integration: Access Geode from any language or platform</li> <li>Web Application Development: Direct integration with frontend applications</li> <li>Microservices Architecture: Service-to-service communication over HTTP</li> <li>Legacy System Integration: Connect systems that cannot use QUIC protocol</li> <li>Development and Testing: Easy exploration using curl, Postman, or similar tools</li> </ul> All endpoints return JSON responses and accept JSON request bodies. The API uses standard HTTP status codes and follows ISO/IEC 39075:2024 error code conventions. <h3 id="base-url-and-versioning" class="position-relative d-flex align-items-center group"> Base URL and Versioning <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="base-url-and-versioning" aria-haspopup="dialog" aria-label="Share link: Base URL and Versioning"> Share link </button> </h3>The REST API is versioned to ensure backward compatibility: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-fallback" data-lang="fallback">https://geode.example.com/api/v1/ </code></pre></div>Current version: <code>v1</code> (stable) All endpoints should be prefixed with <code>/api/v1/</code>. Future API versions will use <code>/api/v2/</code>, etc., allowing clients to upgrade at their own pace. <h3 id="authentication" class="position-relative d-flex align-items-center group"> Authentication <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="authentication" aria-haspopup="dialog" aria-label="Share link: Authentication"> Share link </button> </h3> <h4 id="bearer-token-authentication" class="position-relative d-flex align-items-center group"> Bearer Token Authentication <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="bearer-token-authentication" aria-haspopup="dialog" aria-label="Share link: Bearer Token Authentication"> Share link </button> </h4>The recommended authentication method for production applications: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash">curl -X POST https://geode.example.com/api/v1/query \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \ -H "Content-Type: application/json" \ -d '{"query": "MATCH (n) RETURN n LIMIT 10"}' </code></pre></div>Tokens can be obtained via the authentication endpoint: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Obtain token curl -X POST https://geode.example.com/api/v1/auth/token \ -H "Content-Type: application/json" \ -d '{ "username": "admin", "password": "secure_password" }' # Response { "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "refresh_token_abc123" } </code></pre></div> <h4 id="api-key-authentication" class="position-relative d-flex align-items-center group"> API Key Authentication <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="api-key-authentication" aria-haspopup="dialog" aria-label="Share link: API Key Authentication"> Share link </button> </h4>For service-to-service communication, API keys provide simpler authentication: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash">curl -X POST https://geode.example.com/api/v1/query \ -H "X-API-Key: geode_key_abc123def456" \ -H "Content-Type: application/json" \ -d '{"query": "MATCH (n) RETURN n LIMIT 10"}' </code></pre></div> <h4 id="basic-authentication" class="position-relative d-flex align-items-center group"> Basic Authentication <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="basic-authentication" aria-haspopup="dialog" aria-label="Share link: Basic Authentication"> Share link </button> </h4>Supported for development and testing (not recommended for production): <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash">curl -X POST https://geode.example.com/api/v1/query \ -u username:password \ -H "Content-Type: application/json" \ -d '{"query": "MATCH (n) RETURN n LIMIT 10"}' </code></pre></div> <h3 id="core-endpoints" class="position-relative d-flex align-items-center group"> Core Endpoints <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="core-endpoints" aria-haspopup="dialog" aria-label="Share link: Core Endpoints"> Share link </button> </h3> <h4 id="execute-query" class="position-relative d-flex align-items-center group"> Execute Query <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="execute-query" aria-haspopup="dialog" aria-label="Share link: Execute Query"> Share link </button> </h4>Execute a GQL query and return results. Endpoint: <code>POST /api/v1/query</code> Request: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-json" data-lang="json">{ "query": "MATCH (p:Person)-[:KNOWS]->(friend:Person) WHERE p.name = $name RETURN friend.name, friend.age", "parameters": { "name": "Alice" }, "timeout": 30000, "explain": false, "profile": false } </code></pre></div>Response: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-json" data-lang="json">{ "schema": { "fields": [ {"name": "friend.name", "type": "STRING"}, {"name": "friend.age", "type": "INTEGER"} ] }, "data": [ {"friend.name": "Bob", "friend.age": 30}, {"friend.name": "Charlie", "friend.age": 35} ], "metadata": { "rows_returned": 2, "execution_time_ms": 15, "rows_scanned": 150 } } </code></pre></div>Example with curl: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash">curl -X POST https://geode.example.com/api/v1/query \ -H "Authorization: Bearer token_abc123" \ -H "Content-Type: application/json" \ -d '{ "query": "MATCH (p:Person {name: $name}) RETURN p", "parameters": {"name": "Alice"} }' </code></pre></div>Example with Python: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python">import requests def execute_query(query, parameters=None): response = requests.post( 'https://geode.example.com/api/v1/query', headers={ 'Authorization': 'Bearer token_abc123', 'Content-Type': 'application/json' }, json={ 'query': query, 'parameters': parameters or {} } ) response.raise_for_status() return response.json() result = execute_query( "MATCH (p:Person)-[:KNOWS]->(f:Person) WHERE p.name = $name RETURN f.name", {"name": "Alice"} ) for row in result.rows['data']: print(row['f.name']) </code></pre></div>Example with JavaScript/Node.js: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-javascript" data-lang="javascript">const axios = require('axios'); async function executeQuery(query, parameters = {}) { const response = await axios.post( 'https://geode.example.com/api/v1/query', { query, parameters }, { headers: { 'Authorization': 'Bearer token_abc123', 'Content-Type': 'application/json' } } ); return response.data; } // Usage const result = await executeQuery( 'MATCH (p:Person {name: $name}) RETURN p', { name: 'Alice' } ); console.log(result.data); </code></pre></div> <h4 id="query-explanation" class="position-relative d-flex align-items-center group"> Query Explanation <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="query-explanation" aria-haspopup="dialog" aria-label="Share link: Query Explanation"> Share link </button> </h4>Get query execution plan without executing the query. Endpoint: <code>POST /api/v1/query/explain</code> Request: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-json" data-lang="json">{ "query": "MATCH (p:Person)-[:KNOWS*1..3]->(friend) WHERE p.age > 25 RETURN friend.name" } </code></pre></div>Response: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-json" data-lang="json">{ "plan": { "operator": "Project", "columns": ["friend.name"], "children": [ { "operator": "VariableLengthExpand", "pattern": "[:KNOWS*1..3]", "estimated_cost": 1500, "children": [ { "operator": "NodeScan", "label": "Person", "filter": "age > 25", "index_used": "Person.age", "estimated_rows": 1000 } ] } ] }, "estimated_total_cost": 2500, "estimated_rows": 500 } </code></pre></div> <h4 id="query-profiling" class="position-relative d-flex align-items-center group"> Query Profiling <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="query-profiling" aria-haspopup="dialog" aria-label="Share link: Query Profiling"> Share link </button> </h4>Execute query and return detailed performance metrics. Endpoint: <code>POST /api/v1/query/profile</code> Request: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-json" data-lang="json">{ "query": "MATCH (p:Person)-[:KNOWS]->(f) RETURN f.name", "parameters": {} } </code></pre></div>Response: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-json" data-lang="json">{ "data": [...], "profile": { "total_time_ms": 125, "operators": [ { "name": "Project", "time_ms": 5, "rows_processed": 100, "db_hits": 100 }, { "name": "Expand", "time_ms": 80, "rows_processed": 100, "db_hits": 500 }, { "name": "NodeScan", "time_ms": 40, "rows_processed": 50, "db_hits": 50, "index": "Person.name" } ] } } </code></pre></div> <h3 id="transaction-management" class="position-relative d-flex align-items-center group"> Transaction Management <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="transaction-management" aria-haspopup="dialog" aria-label="Share link: Transaction Management"> Share link </button> </h3> <h4 id="begin-transaction" class="position-relative d-flex align-items-center group"> Begin Transaction <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="begin-transaction" aria-haspopup="dialog" aria-label="Share link: Begin Transaction"> Share link </button> </h4>Start a new transaction and receive a transaction ID. Endpoint: <code>POST /api/v1/transaction/begin</code> Request: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-json" data-lang="json">{ "isolation_level": "READ_COMMITTED", "timeout": 300000 } </code></pre></div>Response: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-json" data-lang="json">{ "transaction_id": "tx_abc123def456", "expires_at": "2025-01-24T15:30:00Z" } </code></pre></div> <h4 id="execute-in-transaction" class="position-relative d-flex align-items-center group"> Execute in Transaction <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="execute-in-transaction" aria-haspopup="dialog" aria-label="Share link: Execute in Transaction"> Share link </button> </h4>Execute a query within an existing transaction. Endpoint: <code>POST /api/v1/transaction/{transaction_id}/query</code> Request: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-json" data-lang="json">{ "query": "CREATE (p:Person {name: $name, age: $age})", "parameters": { "name": "David", "age": 40 } } </code></pre></div>Response: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-json" data-lang="json">{ "schema": {...}, "data": [...], "metadata": { "rows_affected": 1, "execution_time_ms": 8 } } </code></pre></div> <h4 id="commit-transaction" class="position-relative d-flex align-items-center group"> Commit Transaction <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="commit-transaction" aria-haspopup="dialog" aria-label="Share link: Commit Transaction"> Share link </button> </h4>Commit all changes in a transaction. Endpoint: <code>POST /api/v1/transaction/{transaction_id}/commit</code> Response: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-json" data-lang="json">{ "status": "committed", "transaction_id": "tx_abc123def456", "committed_at": "2025-01-24T15:25:00Z" } </code></pre></div> <h4 id="rollback-transaction" class="position-relative d-flex align-items-center group"> Rollback Transaction <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="rollback-transaction" aria-haspopup="dialog" aria-label="Share link: Rollback Transaction"> Share link </button> </h4>Rollback all changes in a transaction. Endpoint: <code>POST /api/v1/transaction/{transaction_id}/rollback</code> Request: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-json" data-lang="json">{ "to_savepoint": "savepoint_1" } </code></pre></div>Response: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-json" data-lang="json">{ "status": "rolled_back", "transaction_id": "tx_abc123def456", "rolled_back_at": "2025-01-24T15:25:00Z" } </code></pre></div> <h4 id="transaction-example" class="position-relative d-flex align-items-center group"> Transaction Example <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="transaction-example" aria-haspopup="dialog" aria-label="Share link: Transaction Example"> Share link </button> </h4>Complete transaction workflow: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python">import requests class GeodeTransaction: def __init__(self, base_url, auth_token): self.base_url = base_url self.headers = { 'Authorization': f'Bearer {auth_token}', 'Content-Type': 'application/json' } self.tx_id = None def begin(self): response = requests.post( f'{self.base_url}/api/v1/transaction/begin', headers=self.headers, json={'isolation_level': 'READ_COMMITTED'} ) response.raise_for_status() self.tx_id = response.json()['transaction_id'] return self def execute(self, query, parameters=None): response = requests.post( f'{self.base_url}/api/v1/transaction/{self.tx_id}/query', headers=self.headers, json={'query': query, 'parameters': parameters or {}} ) response.raise_for_status() return response.json() def commit(self): response = requests.post( f'{self.base_url}/api/v1/transaction/{self.tx_id}/commit', headers=self.headers ) response.raise_for_status() return response.json() def rollback(self): response = requests.post( f'{self.base_url}/api/v1/transaction/{self.tx_id}/rollback', headers=self.headers ) response.raise_for_status() return response.json() # Usage tx = GeodeTransaction('https://geode.example.com', 'token_abc123') tx.begin() try: tx.execute( "CREATE (p:Person {name: $name, age: $age})", {"name": "Eve", "age": 28} ) tx.execute( "MATCH (p:Person {name: $name}) CREATE (p)-[:KNOWS]->(:Person {name: $friend})", {"name": "Eve", "friend": "Frank"} ) tx.commit() except Exception as e: tx.rollback() raise </code></pre></div> <h3 id="batch-operations" class="position-relative d-flex align-items-center group"> Batch Operations <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="batch-operations" aria-haspopup="dialog" aria-label="Share link: Batch Operations"> Share link </button> </h3>Execute multiple queries in a single request for efficiency. Endpoint: <code>POST /api/v1/batch</code> Request: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-json" data-lang="json">{ "queries": [ { "query": "CREATE (p:Person {name: $name})", "parameters": {"name": "Alice"} }, { "query": "CREATE (p:Person {name: $name})", "parameters": {"name": "Bob"} }, { "query": "MATCH (a:Person {name: $a}), (b:Person {name: $b}) CREATE (a)-[:KNOWS]->(b)", "parameters": {"a": "Alice", "b": "Bob"} } ], "transaction": true } </code></pre></div>Response: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-json" data-lang="json">{ "results": [ { "index": 0, "status": "success", "data": [...], "metadata": {"rows_affected": 1} }, { "index": 1, "status": "success", "data": [...], "metadata": {"rows_affected": 1} }, { "index": 2, "status": "success", "data": [...], "metadata": {"rows_affected": 1} } ], "total_time_ms": 45 } </code></pre></div> <h3 id="health-and-status-endpoints" class="position-relative d-flex align-items-center group"> Health and Status Endpoints <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="health-and-status-endpoints" aria-haspopup="dialog" aria-label="Share link: Health and Status Endpoints"> Share link </button> </h3> <h4 id="health-check" class="position-relative d-flex align-items-center group"> Health Check <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="health-check" aria-haspopup="dialog" aria-label="Share link: Health Check"> Share link </button> </h4>Check database health and connectivity. Endpoint: <code>GET /api/v1/health</code> Response: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-json" data-lang="json">{ "status": "healthy", "version": "0.2.18", "uptime_seconds": 86400, "checks": { "database": "ok", "storage": "ok", "replication": "ok" } } </code></pre></div> <h4 id="server-status" class="position-relative d-flex align-items-center group"> Server Status <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="server-status" aria-haspopup="dialog" aria-label="Share link: Server Status"> Share link </button> </h4>Get detailed server status and statistics. Endpoint: <code>GET /api/v1/status</code> Response: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-json" data-lang="json">{ "version": "0.2.18", "uptime_seconds": 86400, "node_id": "node_abc123", "role": "primary", "statistics": { "total_nodes": 1500000, "total_relationships": 3000000, "queries_per_second": 1250, "active_connections": 150 }, "storage": { "total_bytes": 10737418240, "used_bytes": 5368709120, "free_bytes": 5368709120 } } </code></pre></div> <h4 id="metrics" class="position-relative d-flex align-items-center group"> Metrics <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="metrics" aria-haspopup="dialog" aria-label="Share link: Metrics"> Share link </button> </h4>Prometheus-compatible metrics endpoint. Endpoint: <code>GET /api/v1/metrics</code> Response (text/plain): <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-fallback" data-lang="fallback"># HELP geode_queries_total Total number of queries executed # TYPE geode_queries_total counter geode_queries_total 1500000 # HELP geode_query_duration_seconds Query execution duration # TYPE geode_query_duration_seconds histogram geode_query_duration_seconds_bucket{le="0.01"} 100000 geode_query_duration_seconds_bucket{le="0.05"} 450000 geode_query_duration_seconds_bucket{le="0.1"} 700000 # HELP geode_connections_active Active connections # TYPE geode_connections_active gauge geode_connections_active 150 </code></pre></div> <h3 id="error-handling" class="position-relative d-flex align-items-center group"> Error Handling <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="error-handling" aria-haspopup="dialog" aria-label="Share link: Error Handling"> Share link </button> </h3> <h4 id="error-response-format" class="position-relative d-flex align-items-center group"> Error Response Format <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="error-response-format" aria-haspopup="dialog" aria-label="Share link: Error Response Format"> Share link </button> </h4>All errors follow a consistent format with ISO/IEC 39075:2024 status codes: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-json" data-lang="json">{ "error": { "code": "42000", "category": "SYNTAX_ERROR", "message": "Syntax error near line 1, column 15", "details": { "query": "MATCH (n:Person RETURN n", "position": { "line": 1, "column": 15 }, "suggestion": "Expected ')' after label expression" } } } </code></pre></div> <h4 id="common-error-codes" class="position-relative d-flex align-items-center group"> Common Error Codes <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="common-error-codes" aria-haspopup="dialog" aria-label="Share link: Common Error Codes"> Share link </button> </h4><table> <thead> <tr> <th>HTTP Status</th> <th>ISO Code</th> <th>Category</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td>200</td> <td>00000</td> <td>SUCCESS</td> <td>Query executed successfully</td> </tr> <tr> <td>400</td> <td>42000</td> <td>SYNTAX_ERROR</td> <td>Invalid GQL syntax</td> </tr> <tr> <td>400</td> <td>22000</td> <td>DATA_EXCEPTION</td> <td>Invalid data value</td> </tr> <tr> <td>401</td> <td>08001</td> <td>AUTH_FAILED</td> <td>Authentication required or failed</td> </tr> <tr> <td>403</td> <td>42501</td> <td>PERMISSION_DENIED</td> <td>Insufficient privileges</td> </tr> <tr> <td>404</td> <td>02000</td> <td>NOT_FOUND</td> <td>Resource not found</td> </tr> <tr> <td>409</td> <td>23000</td> <td>CONSTRAINT_VIOLATION</td> <td>Constraint violation</td> </tr> <tr> <td>408</td> <td>40003</td> <td>TIMEOUT</td> <td>Query timeout exceeded</td> </tr> <tr> <td>500</td> <td>40000</td> <td>TRANSACTION_ERROR</td> <td>Transaction error</td> </tr> <tr> <td>503</td> <td>08006</td> <td>CONNECTION_FAILURE</td> <td>Database unavailable</td> </tr> </tbody> </table> <h4 id="error-handling-example" class="position-relative d-flex align-items-center group"> Error Handling Example <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="error-handling-example" aria-haspopup="dialog" aria-label="Share link: Error Handling Example"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python">import requests from requests.exceptions import HTTPError def execute_with_retry(query, parameters, max_retries=3): for attempt in range(max_retries): try: response = requests.post( 'https://geode.example.com/api/v1/query', headers={ 'Authorization': 'Bearer token_abc123', 'Content-Type': 'application/json' }, json={'query': query, 'parameters': parameters} ) response.raise_for_status() return response.json() except HTTPError as e: if e.response.status_code == 503: # Service unavailable if attempt < max_retries - 1: time.sleep(2 ** attempt) # Exponential backoff continue raise elif e.response.status_code == 408: # Timeout if attempt < max_retries - 1: continue raise else: # Parse error response error = e.response.json()['error'] print(f"Error {error['code']}: {error['message']}") raise </code></pre></div> <h3 id="rate-limiting" class="position-relative d-flex align-items-center group"> Rate Limiting <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="rate-limiting" aria-haspopup="dialog" aria-label="Share link: Rate Limiting"> Share link </button> </h3>The REST API implements rate limiting to prevent abuse: Headers: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-fallback" data-lang="fallback">X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 999 X-RateLimit-Reset: 1706112000 </code></pre></div>Rate Limit Exceeded Response (HTTP 429): <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-json" data-lang="json">{ "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit of 1000 requests per hour exceeded", "retry_after": 3600 } } </code></pre></div> <h3 id="cors-support" class="position-relative d-flex align-items-center group"> CORS Support <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="cors-support" aria-haspopup="dialog" aria-label="Share link: CORS Support"> Share link </button> </h3>The REST API supports Cross-Origin Resource Sharing (CORS) for browser-based applications: Preflight Request: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash">curl -X OPTIONS https://geode.example.com/api/v1/query \ -H "Origin: https://app.example.com" \ -H "Access-Control-Request-Method: POST" </code></pre></div>Response: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-fallback" data-lang="fallback">Access-Control-Allow-Origin: https://app.example.com Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS Access-Control-Allow-Headers: Authorization, Content-Type Access-Control-Max-Age: 86400 </code></pre></div> <h3 id="websocket-support" class="position-relative d-flex align-items-center group"> WebSocket Support <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="websocket-support" aria-haspopup="dialog" aria-label="Share link: WebSocket Support"> Share link </button> </h3>For real-time updates and streaming queries, the API supports WebSocket connections: Endpoint: <code>wss://geode.example.com/api/v1/stream</code> JavaScript Example: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-javascript" data-lang="javascript">const ws = new WebSocket('wss://geode.example.com/api/v1/stream'); ws.onopen = () => { // Authenticate ws.send(JSON.stringify({ type: 'AUTH', token: 'Bearer token_abc123' })); // Subscribe to changes ws.send(JSON.stringify({ type: 'SUBSCRIBE', patterns: ['(n:Person)', '()-[r:KNOWS]->()'] })); }; ws.onmessage = (event) => { const message = JSON.parse(event.data); if (message.type === 'CHANGE') { console.log('Change detected:', message.data); } }; </code></pre></div> <h3 id="best-practices" class="position-relative d-flex align-items-center group"> Best Practices <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="best-practices" aria-haspopup="dialog" aria-label="Share link: Best Practices"> Share link </button> </h3><ol> <li>Use HTTPS: Always use HTTPS in production for encrypted communication</li> <li>Token Management: Implement token refresh before expiration</li> <li>Connection Pooling: Reuse HTTP connections with keep-alive</li> <li>Parameterization: Always use parameterized queries to prevent injection</li> <li>Error Handling: Implement comprehensive error handling with retries</li> <li>Rate Limiting: Respect rate limits and implement exponential backoff</li> <li>Timeouts: Set appropriate request timeouts (default: 30 seconds)</li> <li>Monitoring: Track API usage, latency, and error rates</li> </ol> <h3 id="performance-considerations" class="position-relative d-flex align-items-center group"> Performance Considerations <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="performance-considerations" aria-haspopup="dialog" aria-label="Share link: Performance Considerations"> Share link </button> </h3><ul> <li>Batch Requests: Use batch endpoint for multiple operations</li> <li>Connection Reuse: Enable HTTP keep-alive for connection pooling</li> <li>Compression: Enable gzip compression for large responses</li> <li>Pagination: Use LIMIT and OFFSET for large result sets</li> <li>Field Selection: Only request fields you need in RETURN clause</li> </ul> <h3 id="related-topics" class="position-relative d-flex align-items-center group"> Related Topics <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="related-topics" aria-haspopup="dialog" aria-label="Share link: Related Topics"> Share link </button> </h3><ul> <li><a href="/tags/api/" >API Development</a> - Complete API guide</li> <li><a href="/tags/authentication/" >Authentication</a> - Authentication methods</li> <li><a href="/tags/client-libraries/" >Client Libraries</a> - Native client libraries</li> <li><a href="/tags/protocol/" >Protocol</a> - QUIC protocol details</li> <li><a href="/tags/security/" >Security</a> - Security best practices</li> </ul> <h3 id="further-reading" class="position-relative d-flex align-items-center group"> Further Reading <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="further-reading" aria-haspopup="dialog" aria-label="Share link: Further Reading"> Share link </button> </h3><ul> <li><a href="/docs/api-reference/" >API Reference</a> - Complete API documentation</li> <li><a href="/docs/security/authentication/" >Authentication Guide</a> - Detailed auth setup</li> <li><a href="/docs/reference/error-codes/" >Error Codes</a> - Complete error code list</li> <li><a href="/docs/architecture/wire-protocol/" >Wire Protocol</a> - Protocol specification</li> </ul>

Popular

Related Articles