├── LICENSE └── README.md /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2025 Stefan Buck 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # AI-First API Design Strategy 2 | 3 | AI-friendly APIs are designed to optimize interactions for AI agents while maintaining usability for human developers. These APIs require a shift in philosophy, focusing on clear communication, context preservation, and adaptability to support intelligent agents effectively. 4 | 5 | ## Contributing 6 | 7 | I want to acknowledge that I’m not an expert in API design. This document is a living resource, meant to evolve over time. Contributions, suggestions, and discussions are highly encouraged. Other established API best practices still apply! The ideas presented here are additional recommendations to enhance API usability for AI agents. 8 | 9 | ## Principles of AI-Friendly API Design 10 | 11 | ### Explicit Intent Signaling 12 | APIs should guide AI agents by clearly indicating actions, decision points, and success or failure states. 13 | 14 | **Example:** 15 | ```json 16 | { 17 | "status": "email_verification_required", 18 | "recommendedNextAction": "verify_email", 19 | "availableActions": ["resend_verification", "update_email", "cancel"], 20 | "actionPriority": "high" 21 | } 22 | ``` 23 | 24 | ### Context Preservation 25 | To support chain-of-thought reasoning, APIs must track state transitions and dependencies between operations. 26 | 27 | **Example:** 28 | ```json 29 | { 30 | "orderStatus": "payment_processing", 31 | "contextChain": { 32 | "previousStates": ["cart_created", "address_verified", "payment_initiated"], 33 | "dependentOperations": ["inventory_check", "fraud_assessment"] 34 | } 35 | } 36 | ``` 37 | 38 | ### Uncertainty Handling 39 | APIs should quantify confidence levels, offer alternative options, and specify triggers for human intervention. 40 | 41 | **Example:** 42 | ```json 43 | { 44 | "prediction": "fraudulent_transaction", 45 | "confidence": 0.87, 46 | "alternatives": [ 47 | {"prediction": "legitimate_transaction", "confidence": 0.12} 48 | ], 49 | "requiresHumanReview": true 50 | } 51 | ``` 52 | 53 | ### Reasoning Support 54 | APIs should provide decision traces and reasoning chains to explain logic. 55 | 56 | **Example:** 57 | ```json 58 | { 59 | "decision": "loan_denied", 60 | "reasoningChain": { 61 | "primaryFactors": [ 62 | {"factor": "credit_score", "impact": "negative"}, 63 | {"factor": "debt_ratio", "impact": "negative"} 64 | ], 65 | "decisionTrace": "credit_score_check → risk_assessment" 66 | } 67 | } 68 | ``` 69 | 70 | ### Semantic Precision 71 | APIs must eliminate ambiguity with strict typing, enumerated values, and explicit relationships. Clear endpoint and parameter descriptions are essential for understanding functionality. 72 | 73 | **Example:** 74 | ```json 75 | { 76 | "userStatus": { 77 | "type": "enum", 78 | "value": "ACTIVE", 79 | "allowedValues": ["ACTIVE", "SUSPENDED", "PENDING"], 80 | "description": "Indicates the current status of the user account." 81 | }, 82 | "profileCompletion": { 83 | "type": "integer", 84 | "description": "Percentage of profile completed by the user." 85 | } 86 | } 87 | ``` 88 | 89 | ### Adaptive Interaction Patterns 90 | APIs should adjust responses based on the AI agent's needs and capabilities. 91 | 92 | **Example:** 93 | ```json 94 | { 95 | "responseComplexity": "detailed", 96 | "resourceIntensity": { 97 | "cpu": "medium", 98 | "memory": "high" 99 | } 100 | } 101 | ``` 102 | 103 | ### Error Prevention 104 | APIs must include a detailed error descriptions should explain why a call failed and how to correct it in subsequent attempts. 105 | 106 | **Example:** 107 | ```json 108 | { 109 | "error": { 110 | "code": "INVALID_INPUT", 111 | "message": "User ID is missing in one of the entries.", 112 | "remediation": "Ensure all entries include a valid 'userId' field." 113 | } 114 | } 115 | ``` 116 | 117 | ### Recovery 118 | APIs must include validation, dry-run options, and recovery mechanisms. 119 | 120 | **Example:** 121 | ```json 122 | { 123 | "operation": "bulk_user_update", 124 | "validationEndpoint": "/validate/bulk_user_update", 125 | "dryRunOption": "?mode=dry_run", 126 | "rollbackStrategy": { 127 | "available": true, 128 | "window": "24h" 129 | } 130 | } 131 | ``` 132 | 133 | ### Resource Awareness 134 | APIs should communicate resource implications such as cost, rate limits, and allocations. 135 | 136 | **Example:** 137 | ```json 138 | { 139 | "operationCost": { 140 | "creditsCost": 5, 141 | "estimatedDuration": "2s" 142 | }, 143 | "rateLimits": { 144 | "current": 98, 145 | "limit": 100 146 | } 147 | } 148 | ``` 149 | 150 | ### Temporal Awareness 151 | APIs should specify time-related aspects like validity periods and unambiguous time zones. 152 | 153 | **Example:** 154 | ```json 155 | { 156 | "dataTimestamp": "2024-01-06T15:30:00Z", 157 | "validityPeriod": { 158 | "start": "2024-01-06T15:30:00Z", 159 | "end": "2024-01-06T16:30:00Z" 160 | } 161 | } 162 | ``` 163 | 164 | ### Ethical Considerations 165 | APIs must enforce ethical AI behavior by exposing bias metrics, defining constraints, and assessing impacts. 166 | 167 | **Example:** 168 | ```json 169 | { 170 | "ethicalMetrics": { 171 | "biasScore": { 172 | "gender": 0.02 173 | }, 174 | "fairnessMetrics": { 175 | "equalOpportunity": 0.99 176 | } 177 | }, 178 | "impactAssessment": { 179 | "privacyImpact": "medium" 180 | } 181 | } 182 | ``` 183 | 184 | ## Implementation Guidelines 185 | 1. Version APIs with explicit AI-friendly indicators. 186 | 1. Provide machine-readable specifications in OpenAPI format. 187 | 1. Include AI-specific endpoints as necessary. 188 | 1. Maintain backward compatibility. 189 | 1. Document AI-specific features separately. 190 | --------------------------------------------------------------------------------