API Development

<h2 id="api-development" class="position-relative d-flex align-items-center group"> API Development <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-development" aria-haspopup="dialog" aria-label="Share link: API Development"> 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>API development encompasses the design, implementation, and documentation of interfaces for accessing Geode’s graph database functionality. Well-designed APIs enable developers to build powerful applications while maintaining security, performance, and backward compatibility. <h3 id="geode-client-libraries" class="position-relative d-flex align-items-center group"> Geode Client Libraries <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="geode-client-libraries" aria-haspopup="dialog" aria-label="Share link: Geode Client Libraries"> Share link </button> </h3> <h4 id="native-protocol" class="position-relative d-flex align-items-center group"> Native Protocol <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="native-protocol" aria-haspopup="dialog" aria-label="Share link: Native Protocol"> Share link </button> </h4>Geode’s native protocol uses QUIC over TLS for efficient, secure communication: Transport - QUIC (UDP-based, multiplexed) Security - TLS 1.3 required Format - Protobuf wire protocol Port - 3141 (standard) or 8443 (alternative) <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-fallback" data-lang="fallback">Client Message Format: {"type": "RUN_GQL", "query": "MATCH (n) RETURN n LIMIT 10"} Server Response Format: {"type": "SCHEMA", "columns": ["n"]} {"type": "BINDINGS", "row": [{"id": "1", "labels": ["Person"]}]} {"type": "BINDINGS", "row": [{"id": "2", "labels": ["Person"]}]} </code></pre></div> <h4 id="go-client-library" class="position-relative d-flex align-items-center group"> Go Client Library <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="go-client-library" aria-haspopup="dialog" aria-label="Share link: Go Client Library"> Share link </button> </h4>Full-featured Go client with <code>database/sql</code> compatibility: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-go" data-lang="go">import ( "database/sql" _ "geodedb.com/geode" ) // Open connection db, err := sql.Open("geode", "quic://localhost:3141?tls=true") if err != nil { log.Fatal(err) } defer db.Close() // Execute query rows, err := db.Query("MATCH (p:Person) WHERE p.age > ? RETURN p", 18) if err != nil { log.Fatal(err) } defer rows.Close() // Process results for rows.Next() { var person Person if err := rows.Scan(&person); err != nil { log.Fatal(err) } fmt.Printf("Person: %+v\n", person) } </code></pre></div>Features: <ul> <li>Connection pooling</li> <li>Prepared statements</li> <li>Transaction support</li> <li>Context-aware operations</li> <li>Type-safe query builders</li> </ul> <h4 id="python-client-library" class="position-relative d-flex align-items-center group"> Python Client Library <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="python-client-library" aria-haspopup="dialog" aria-label="Share link: Python Client Library"> Share link </button> </h4>Async Python client built on aioquic: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python">import asyncio from geode_client import Client async def main(): # Connect to database client = Client("localhost", 3141, use_tls=True) async with client.connection() as client: # Execute query result, _ = await client.query( "MATCH (p:Person) WHERE p.age > $age RETURN p", {"age": 18} ) # Process results for row in result.rows: print(f"Person: {row['p']}") asyncio.run(main()) </code></pre></div>Features: <ul> <li>Full async/await support</li> <li>Connection pooling (workload-dependent throughput)</li> <li>Query builders</li> <li>Row-Level Security policy management</li> <li>Savepoint support</li> </ul> <h4 id="rust-client-library" class="position-relative d-flex align-items-center group"> Rust Client Library <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="rust-client-library" aria-haspopup="dialog" aria-label="Share link: Rust Client Library"> Share link </button> </h4>High-performance Rust client with tokio: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-rust" data-lang="rust">use geode_client::{Client, Query}; #[tokio::main] async fn main() -> Result<(), Box<dyn std::error::Error>> { // Connect to database let client = Client::connect("localhost:3141").await?; // Execute query let query = Query::new("MATCH (p:Person) WHERE p.age > $age RETURN p") .param("age", 18); let mut result = client.execute(query).await?; // Process results while let Some(row) = result.next().await? { println!("Person: {:?}", row.get::<Person>("p")?); } Ok(()) } </code></pre></div>Features: <ul> <li>Zero-cost abstractions</li> <li>Type-safe query builders</li> <li>Connection pooling (workload-dependent throughput)</li> <li>Transaction support</li> <li>Compile-time query validation</li> </ul> <h4 id="zig-client-library" class="position-relative d-flex align-items-center group"> Zig Client Library <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="zig-client-library" aria-haspopup="dialog" aria-label="Share link: Zig Client Library"> Share link </button> </h4>Native Zig client for systems programming: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-zig" data-lang="zig">const geode = @import("geode"); pub fn main() !void { var gpa = std.heap.GeneralPurposeAllocator(.{}){}; defer _ = gpa.deinit(); // Connect to database var client = try geode.Client.connect( gpa.allocator(), "localhost", 3141, .{ .tls = true } ); defer client.deinit(); // Execute query var result = try client.execute( "MATCH (p:Person) WHERE p.age > $age RETURN p", .{ .age = 18 } ); defer result.deinit(); // Process results while (try result.next()) |row| { const person = try row.get("p", Person); std.debug.print("Person: {}\n", .{person}); } } </code></pre></div> <h3 id="rest-api-design" class="position-relative d-flex align-items-center group"> REST API Design <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-design" aria-haspopup="dialog" aria-label="Share link: REST API Design"> Share link </button> </h3> <h4 id="restful-endpoints" class="position-relative d-flex align-items-center group"> RESTful 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="restful-endpoints" aria-haspopup="dialog" aria-label="Share link: RESTful Endpoints"> Share link </button> </h4>Design clean, resource-oriented APIs: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-fallback" data-lang="fallback">GET /api/v1/graphs # List graphs POST /api/v1/graphs # Create graph GET /api/v1/graphs/{id} # Get graph details DELETE /api/v1/graphs/{id} # Delete graph GET /api/v1/graphs/{id}/nodes # List nodes POST /api/v1/graphs/{id}/nodes # Create node GET /api/v1/graphs/{id}/nodes/{nid} # Get node PUT /api/v1/graphs/{id}/nodes/{nid} # Update node DELETE /api/v1/graphs/{id}/nodes/{nid} # Delete node POST /api/v1/graphs/{id}/query # Execute GQL query </code></pre></div> <h4 id="requestresponse-format" class="position-relative d-flex align-items-center group"> Request/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="requestresponse-format" aria-haspopup="dialog" aria-label="Share link: Request/Response Format"> Share link </button> </h4>Use consistent JSON format: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-json" data-lang="json">// Request POST /api/v1/graphs/social/query { "query": "MATCH (p:Person) WHERE p.age > $age RETURN p", "parameters": { "age": 18 }, "consistency": "strong" } // Response { "status": "success", "schema": { "columns": [ {"name": "p", "type": "node"} ] }, "data": [ { "p": { "id": "person:123", "labels": ["Person"], "properties": { "name": "Alice", "age": 25 } } } ], "metadata": { "rows": 1, "execution_time_ms": 12, "cached": false } } </code></pre></div> <h4 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> </h4>Return meaningful error responses: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-json" data-lang="json">// Error Response { "status": "error", "error": { "code": "INVALID_QUERY", "message": "Syntax error at line 1, column 15", "details": { "line": 1, "column": 15, "expected": "WHERE or RETURN", "got": "FROM" } }, "request_id": "req_abc123" } </code></pre></div>Standard error codes: <ul> <li>400 - Bad Request (invalid syntax)</li> <li>401 - Unauthorized (authentication required)</li> <li>403 - Forbidden (insufficient permissions)</li> <li>404 - Not Found (resource doesn’t exist)</li> <li>409 - Conflict (constraint violation)</li> <li>429 - Too Many Requests (rate limited)</li> <li>500 - Internal Server Error</li> </ul> <h3 id="graphql-api" class="position-relative d-flex align-items-center group"> GraphQL 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="graphql-api" aria-haspopup="dialog" aria-label="Share link: GraphQL API"> Share link </button> </h3> <h4 id="schema-definition" class="position-relative d-flex align-items-center group"> Schema Definition <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="schema-definition" aria-haspopup="dialog" aria-label="Share link: Schema Definition"> Share link </button> </h4>Define GraphQL schema for graph access: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-graphql" data-lang="graphql">type Person { id: ID! name: String! age: Int! friends: [Person!]! posts: [Post!]! } type Post { id: ID! title: String! content: String! author: Person! comments: [Comment!]! } type Query { person(id: ID!): Person people(filter: PersonFilter, limit: Int): [Person!]! post(id: ID!): Post posts(filter: PostFilter, limit: Int): [Post!]! } type Mutation { createPerson(input: CreatePersonInput!): Person! updatePerson(id: ID!, input: UpdatePersonInput!): Person! deletePerson(id: ID!): Boolean! createPost(input: CreatePostInput!): Post! } input PersonFilter { minAge: Int maxAge: Int name: String } </code></pre></div> <h4 id="resolver-implementation" class="position-relative d-flex align-items-center group"> Resolver Implementation <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="resolver-implementation" aria-haspopup="dialog" aria-label="Share link: Resolver Implementation"> Share link </button> </h4>Map GraphQL to GQL queries: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-javascript" data-lang="javascript">const resolvers = { Query: { person: async (_, { id }, { geode }) => { const result = await geode.execute( 'MATCH (p:Person {id: $id}) RETURN p', { id } ); return result.rows[0]?.p; }, people: async (_, { filter, limit = 100 }, { geode }) => { let query = 'MATCH (p:Person)'; const params = {}; if (filter?.minAge) { query += ' WHERE p.age >= $minAge'; params.minAge = filter.minAge; } query += ' RETURN p LIMIT $limit'; params.limit = limit; const result = await geode.execute(query, params); return result.rows.map(row => row.p); } }, Person: { friends: async (person, _, { geode }) => { const result = await geode.execute( 'MATCH (p:Person {id: $id})-[:FRIEND]->(f:Person) RETURN f', { id: person.id } ); return result.rows.map(row => row.f); } } }; </code></pre></div> <h4 id="query-optimization" class="position-relative d-flex align-items-center group"> Query Optimization <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-optimization" aria-haspopup="dialog" aria-label="Share link: Query Optimization"> Share link </button> </h4>Optimize GraphQL queries: DataLoader - Batch and cache database requests Query Depth Limiting - Prevent excessive nesting Complexity Analysis - Estimate query cost Persisted Queries - Pre-approve query patterns <h3 id="api-versioning" class="position-relative d-flex align-items-center group"> API 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="api-versioning" aria-haspopup="dialog" aria-label="Share link: API Versioning"> Share link </button> </h3> <h4 id="versioning-strategies" class="position-relative d-flex align-items-center group"> Versioning Strategies <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="versioning-strategies" aria-haspopup="dialog" aria-label="Share link: Versioning Strategies"> Share link </button> </h4>Support multiple API versions: URL Versioning - <code>/api/v1/</code>, <code>/api/v2/</code> Header Versioning - <code>Accept: application/vnd.geode.v2+json</code> Content Negotiation - Different formats per version <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-fallback" data-lang="fallback">// URL versioning (recommended) GET /api/v1/graphs/social/nodes GET /api/v2/graphs/social/nodes // Header versioning GET /api/graphs/social/nodes Accept: application/vnd.geode.v2+json // Query parameter versioning GET /api/graphs/social/nodes?version=2 </code></pre></div> <h4 id="deprecation-policy" class="position-relative d-flex align-items-center group"> Deprecation Policy <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="deprecation-policy" aria-haspopup="dialog" aria-label="Share link: Deprecation Policy"> Share link </button> </h4>Gracefully deprecate old versions: <ol> <li>Announce - Notify users of deprecation timeline</li> <li>Warn - Include deprecation headers in responses</li> <li>Support - Maintain old version for grace period (6-12 months)</li> <li>Sunset - Remove support with final notice</li> </ol> <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-fallback" data-lang="fallback">Deprecation: true Sunset: Sat, 31 Dec 2026 23:59:59 GMT Link: <https://docs.geode.io/api/v3>; rel="successor-version" </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> <h4 id="rate-limit-configuration" class="position-relative d-flex align-items-center group"> Rate Limit Configuration <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-limit-configuration" aria-haspopup="dialog" aria-label="Share link: Rate Limit Configuration"> Share link </button> </h4>Protect API from abuse: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml">rate_limiting: enabled: true strategies: - name: per_user limit: 1000 window: 1h - name: per_ip limit: 100 window: 1m - name: burst limit: 50 window: 1s </code></pre></div> <h4 id="rate-limit-headers" class="position-relative d-flex align-items-center group"> Rate Limit Headers <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-limit-headers" aria-haspopup="dialog" aria-label="Share link: Rate Limit Headers"> Share link </button> </h4>Communicate limits to clients: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-fallback" data-lang="fallback">X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 742 X-RateLimit-Reset: 1640995200 Retry-After: 3600 </code></pre></div> <h4 id="rate-limit-response" class="position-relative d-flex align-items-center group"> Rate Limit Response <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-limit-response" aria-haspopup="dialog" aria-label="Share link: Rate Limit Response"> Share link </button> </h4>Return clear error when limited: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-json" data-lang="json">{ "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Retry after 3600 seconds.", "limit": 1000, "window": "1h", "reset_at": "2026-01-24T12:00:00Z" } } </code></pre></div> <h3 id="authentication-and-authorization" class="position-relative d-flex align-items-center group"> Authentication and Authorization <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-and-authorization" aria-haspopup="dialog" aria-label="Share link: Authentication and Authorization"> Share link </button> </h3> <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>Simple authentication for service accounts: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Include API key in request curl -H "X-API-Key: gd_live_abc123..." \ https://api.geode.io/v1/graphs </code></pre></div> <h4 id="oauth-20" class="position-relative d-flex align-items-center group"> OAuth 2.0 <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="oauth-20" aria-haspopup="dialog" aria-label="Share link: OAuth 2.0"> Share link </button> </h4>Standard OAuth flow for user authorization: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-fallback" data-lang="fallback">1. Client redirects to authorization endpoint GET /oauth/authorize?client_id=...&response_type=code 2. User authenticates and grants permission 3. Client receives authorization code GET /callback?code=abc123 4. Client exchanges code for access token POST /oauth/token { "code": "abc123", "grant_type": "authorization_code" } 5. Client uses access token GET /api/v1/graphs Authorization: Bearer eyJhbGc... </code></pre></div> <h4 id="jwt-tokens" class="position-relative d-flex align-items-center group"> JWT Tokens <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="jwt-tokens" aria-haspopup="dialog" aria-label="Share link: JWT Tokens"> Share link </button> </h4>Use JWT for stateless authentication: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-javascript" data-lang="javascript">// Verify JWT token const jwt = require('jsonwebtoken'); function authenticate(req, res, next) { const token = req.headers.authorization?.split(' ')[1]; try { const decoded = jwt.verify(token, process.env.JWT_SECRET); req.user = decoded; next(); } catch (err) { res.status(401).json({ error: 'Invalid token' }); } } </code></pre></div> <h3 id="api-documentation" class="position-relative d-flex align-items-center group"> API Documentation <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-documentation" aria-haspopup="dialog" aria-label="Share link: API Documentation"> Share link </button> </h3> <h4 id="openapi-specification" class="position-relative d-flex align-items-center group"> OpenAPI Specification <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="openapi-specification" aria-haspopup="dialog" aria-label="Share link: OpenAPI Specification"> Share link </button> </h4>Document REST APIs with OpenAPI: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml">openapi: 3.0.0 info: title: Geode Graph Database API version: 1.0.0 description: RESTful API for Geode graph database paths: /graphs/{graphId}/query: post: summary: Execute GQL query parameters: - name: graphId in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: query: type: string parameters: type: object responses: '200': description: Query results content: application/json: schema: $ref: '#/components/schemas/QueryResult' </code></pre></div> <h4 id="interactive-documentation" class="position-relative d-flex align-items-center group"> Interactive Documentation <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="interactive-documentation" aria-haspopup="dialog" aria-label="Share link: Interactive Documentation"> Share link </button> </h4>Provide interactive API exploration: Swagger UI - Browse and test REST endpoints GraphiQL - Interactive GraphQL IDE Postman Collections - Pre-built API requests <h4 id="sdk-documentation" class="position-relative d-flex align-items-center group"> SDK Documentation <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="sdk-documentation" aria-haspopup="dialog" aria-label="Share link: SDK Documentation"> Share link </button> </h4>Generate client library documentation: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Generate Go documentation godoc -http=:6060 # Generate Python documentation pdoc --html geode_client # Generate Rust documentation cargo doc --open </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> <h4 id="api-design-principles" class="position-relative d-flex align-items-center group"> API Design Principles <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-design-principles" aria-haspopup="dialog" aria-label="Share link: API Design Principles"> Share link </button> </h4>Follow REST best practices: <ul> <li>Use nouns for resources, verbs for actions</li> <li>Return appropriate HTTP status codes</li> <li>Support filtering, sorting, and pagination</li> <li>Version APIs from the start</li> <li>Use HTTPS for all endpoints</li> </ul> <h4 id="performance-optimization" class="position-relative d-flex align-items-center group"> Performance Optimization <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-optimization" aria-haspopup="dialog" aria-label="Share link: Performance Optimization"> Share link </button> </h4>Optimize API performance: Caching - Cache GET responses with ETags Compression - Enable gzip/brotli compression Connection Pooling - Reuse database connections Pagination - Limit result set sizes Field Selection - Allow clients to specify needed fields <h4 id="error-handling-1" 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-1" aria-haspopup="dialog" aria-label="Share link: Error Handling"> Share link </button> </h4>Provide helpful error messages: <ul> <li>Include error codes for programmatic handling</li> <li>Provide human-readable messages</li> <li>Include request IDs for debugging</li> <li>Suggest corrective actions</li> <li>Log errors for analysis</li> </ul> <h4 id="security-considerations" class="position-relative d-flex align-items-center group"> Security 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="security-considerations" aria-haspopup="dialog" aria-label="Share link: Security Considerations"> Share link </button> </h4>Secure API endpoints: <ul> <li>Require authentication for all endpoints</li> <li>Use HTTPS exclusively</li> <li>Validate and sanitize inputs</li> <li>Implement rate limiting</li> <li>Audit API access</li> <li>Rotate credentials regularly</li> </ul> <h3 id="testing-apis" class="position-relative d-flex align-items-center group"> Testing APIs <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="testing-apis" aria-haspopup="dialog" aria-label="Share link: Testing APIs"> Share link </button> </h3> <h4 id="unit-testing" class="position-relative d-flex align-items-center group"> Unit Testing <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="unit-testing" aria-haspopup="dialog" aria-label="Share link: Unit Testing"> Share link </button> </h4>Test API handlers in isolation: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-javascript" data-lang="javascript">describe('POST /graphs/{id}/query', () => { it('executes valid GQL query', async () => { const response = await request(app) .post('/api/v1/graphs/social/query') .send({ query: 'MATCH (n) RETURN n LIMIT 1' }); expect(response.status).toBe(200); expect(response.body.status).toBe('success'); }); it('returns error for invalid query', async () => { const response = await request(app) .post('/api/v1/graphs/social/query') .send({ query: 'INVALID QUERY' }); expect(response.status).toBe(400); expect(response.body.error.code).toBe('INVALID_QUERY'); }); }); </code></pre></div> <h4 id="integration-testing" class="position-relative d-flex align-items-center group"> Integration Testing <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="integration-testing" aria-haspopup="dialog" aria-label="Share link: Integration Testing"> Share link </button> </h4>Test end-to-end API flows: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python">def test_user_workflow(): # Create user response = client.post('/api/v1/users', json={ 'name': 'Alice', 'email': '[email protected]' }) assert response.status_code == 201 user_id = response.json()['id'] # Get user response = client.get(f'/api/v1/users/{user_id}') assert response.status_code == 200 assert response.json()['name'] == 'Alice' # Delete user response = client.delete(f'/api/v1/users/{user_id}') assert response.status_code == 204 </code></pre></div> <h4 id="contract-testing" class="position-relative d-flex align-items-center group"> Contract Testing <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="contract-testing" aria-haspopup="dialog" aria-label="Share link: Contract Testing"> Share link </button> </h4>Verify API contracts: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"># Pact contract test interactions: - description: Get person by ID request: method: GET path: /api/v1/persons/123 response: status: 200 body: id: 123 name: string age: integer </code></pre></div> <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/client-libraries" >Client Libraries</a> - Native client implementations</li> <li><a href="/tags/security" >Security</a> - API security best practices</li> <li><a href="/tags/performance" >Performance</a> - API optimization techniques</li> <li><a href="/tags/rest" >REST</a> - RESTful API design</li> </ul> <h3 id="learn-more" class="position-relative d-flex align-items-center group"> Learn More <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="learn-more" aria-haspopup="dialog" aria-label="Share link: Learn More"> Share link </button> </h3><ul> <li><a href="https://restfulapi.net/" aria-label="REST API Design Best Practices – opens in new window" target="_blank" rel="noopener noreferrer" >REST API Design Best Practices ↗ </a> </li> <li><a href="https://graphql.org/learn/best-practices/" aria-label="GraphQL Best Practices – opens in new window" target="_blank" rel="noopener noreferrer" >GraphQL Best Practices ↗ </a> </li> <li><a href="https://swagger.io/specification/" aria-label="OpenAPI Specification – opens in new window" target="_blank" rel="noopener noreferrer" >OpenAPI Specification ↗ </a> </li> <li><a href="https://oauth.net/2/" aria-label="OAuth 2.0 – opens in new window" target="_blank" rel="noopener noreferrer" >OAuth 2.0 ↗ </a> </li> </ul>

Popular

Related Articles

Client Libraries

Complete GQL API Reference

Reference