AIBTC Working Group
  • AIBTC
  • Prompt2DAO
  • AIBTC Contracts
    • DAO Base Layer
    • DAO Extensions
      • Action Proposal Voting
      • DAO Charter
      • DAO Epoch
      • DAO Users
      • Onchain Messaging
      • Rewards Account
      • Token Owner
      • Treasury
    • DAO Proposals
      • Action Proposals
    • Agent Account
  • Agent Tools
    • Overview
    • Available Tools
      • Agent Account Tools
      • Agent Wallet Tools
      • DAO Tools
      • Database Tools
      • Faktory Tools
  • AIBTC Cache
    • Overview
    • Contract Calls
      • API Design
      • Endpoints
        • Decode Clarity Value
        • Read-Only Function Calls
        • Contract ABI
        • Known ABI Contracts
      • Clarity Value Types
      • Integration Examples
    • Cache Services
    • Error Handling
    • Utilities
  • Prompting
    • Action Proposal Prompts
    • Agent Account Prompts
  • Links
    • Common Terms
    • Our App
    • Discord
    • GitHub
    • Prompt2DAO on X
    • AIBTC on X
  • Templates
    • Template Style Guide
  • Documentation Templates
    • Smart Contract Documentation
    • Cache Service Documentation
    • Cache Endpoint Documentation
    • Agent Tool Documentation
    • Prompting Documentation
  • Example Implementations
    • Agent Account Example
    • Cache Service Example
    • Cache Endpoint Example
    • Agent Tool Example
Powered by GitBook
On this page
  • Cache Endpoint Documentation Template
  • [Endpoint Name]
  • Request Flow
  • Request Format
  • Response Format
  • Common Error Codes
  • Example Requests
  • Integration Examples
  • Caching Details
  • Performance Notes
  • Review Checklist
  1. Documentation Templates

Cache Endpoint Documentation

Template for documenting cache service endpoints

PreviousCache Service DocumentationNextAgent Tool Documentation

Last updated 1 month ago

Cache Endpoint Documentation Template

Use this template when documenting individual endpoints of a cache service.

[Endpoint Name]

Purpose: [What this endpoint does]

Path: /[path]/[endpoint-name]

Method: [HTTP Method]

Request Flow

Request Format

Path Parameters

  • [pathParam1]: [Description]

  • [pathParam2]: [Description]

Query Parameters

  • [queryParam1]: (optional) [Description]

  • [queryParam2]: [Description]

Request Body

{
  "param1": "value1",
  "param2": "value2",
  "cacheControl": {
    "bustCache": false,
    "skipCache": false,
    "ttl": 3600
  }
}

Request Body Parameters

  • param1: [Type] - [Description]

  • param2: [Type] - [Description]

  • cacheControl: (optional) Object - Options to control caching behavior:

    • bustCache: (optional) Boolean - If true, bypass the cache and force a fresh request

    • skipCache: (optional) Boolean - If true, don't cache the result of this request

    • ttl: (optional) Number - Custom time-to-live in seconds for this specific request

Response Format

Success Response

{
  "success": true,
  "data": {
    "key1": "value1",
    "key2": "value2"
  }
}

Error Response

{
  "success": false,
  "error": {
    "id": "unique-error-id",
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {
      // Optional additional error details
    }
  }
}

Common Error Codes

  • [ERROR_CODE_1] - [Description and when it occurs]

  • [ERROR_CODE_2] - [Description and when it occurs]

Example Requests

cURL

curl -X [METHOD] \
  https://cache.aibtc.dev/[path]/[endpoint-name] \
  -H "Content-Type: application/json" \
  -d '{"param1": "value1", "param2": "value2"}'

JavaScript

async function callEndpoint(param1, param2) {
  const response = await fetch(
    'https://cache.aibtc.dev/[path]/[endpoint-name]',
    {
      method: '[METHOD]',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        param1,
        param2
      })
    }
  );
  
  const result = await response.json();
  
  if (result.success) {
    return result.data;
  } else {
    throw new Error(`API Error: ${result.error.code} - ${result.error.message}`);
  }
}

Python

import requests
import json

def call_endpoint(param1, param2):
    url = 'https://cache.aibtc.dev/[path]/[endpoint-name]'
    
    payload = {
        "param1": param1,
        "param2": param2
    }
    
    response = requests.post(
        url,
        headers={'Content-Type': 'application/json'},
        data=json.dumps(payload)
    )
    
    response.raise_for_status()
    result = response.json()
    
    if result.get('success'):
        return result['data']
    else:
        error = result.get('error', {})
        raise Exception(f"API Error: {error.get('code')} - {error.get('message')}")

Integration Examples

[Example Use Case 1]

// Example of how to use this endpoint for a specific use case
async function exampleUseCase() {
  try {
    const data = await callEndpoint('value1', 'value2');
    console.log('Success:', data);
    // Process data...
  } catch (error) {
    console.error('Error:', error);
    // Handle error...
  }
}

[Example Use Case 2 with Error Handling and Retries]

async function callWithRetry(param1, param2, maxRetries = 3) {
  let retries = 0;
  let delay = 1000; // Start with 1 second
  
  while (true) {
    try {
      const response = await fetch(
        'https://cache.aibtc.dev/[path]/[endpoint-name]',
        {
          method: '[METHOD]',
          headers: {
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({
            param1,
            param2,
            cacheControl: {
              bustCache: retries > 0 // Bust cache on retries
            }
          })
        }
      );
      
      const result = await response.json();
      
      if (result.success) {
        return result.data;
      } else if (
        ['UPSTREAM_API_ERROR', 'TIMEOUT', 'RATE_LIMIT_EXCEEDED'].includes(result.error.code) && 
        retries < maxRetries
      ) {
        retries++;
        console.log(`Retrying after error: ${result.error.code} (attempt ${retries}/${maxRetries})`);
        await new Promise(resolve => setTimeout(resolve, delay));
        delay *= 2; // Exponential backoff
        continue;
      } else {
        throw new Error(`API Error: ${result.error.code} - ${result.error.message}`);
      }
    } catch (error) {
      if (retries < maxRetries) {
        retries++;
        console.log(`Request failed, retrying (attempt ${retries}/${maxRetries})`);
        await new Promise(resolve => setTimeout(resolve, delay));
        delay *= 2; // Exponential backoff
        continue;
      }
      throw error;
    }
  }
}

Caching Details

  • Default TTL: [Time in seconds for this specific endpoint]

  • Cache Key Components: [What makes up the cache key for this endpoint]

  • Recommended Cache Settings: [Best practices for this endpoint]

Performance Notes

  • Typical Response Time: [Expected response time range]

  • Rate Limit Impact: [How this endpoint affects rate limits]

  • Heavy Operation Warning: [Any warnings about resource-intensive operations]

Review Checklist

Before submitting documentation: