https://github.com/stefanbuck/ai-api-best-practices

The AI-Friendly API Design provides principles for creating APIs optimized for AI agent consumption while maintaining human usability.
https://github.com/stefanbuck/ai-api-best-practices

ai ai-agents api api-design

Last synced: 5 months ago
JSON representation

The AI-Friendly API Design provides principles for creating APIs optimized for AI agent consumption while maintaining human usability.

Host: GitHub
URL: https://github.com/stefanbuck/ai-api-best-practices
Owner: stefanbuck
License: mit
Created: 2025-01-06T21:47:21.000Z (over 1 year ago)
Default Branch: main
Last Pushed: 2025-01-06T22:09:04.000Z (over 1 year ago)
Last Synced: 2025-06-03T16:25:36.313Z (about 1 year ago)
Topics: ai, ai-agents, api, api-design
Homepage:
Size: 3.91 KB
Stars: 1
Watchers: 1
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

# AI-First API Design Strategy

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.

## Contributing

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.

## Principles of AI-Friendly API Design

### Explicit Intent Signaling
APIs should guide AI agents by clearly indicating actions, decision points, and success or failure states.

**Example:**
```json
{
"status": "email_verification_required",
"recommendedNextAction": "verify_email",
"availableActions": ["resend_verification", "update_email", "cancel"],
"actionPriority": "high"
}
```

### Context Preservation
To support chain-of-thought reasoning, APIs must track state transitions and dependencies between operations.

**Example:**
```json
{
"orderStatus": "payment_processing",
"contextChain": {
"previousStates": ["cart_created", "address_verified", "payment_initiated"],
"dependentOperations": ["inventory_check", "fraud_assessment"]
}
}
```

### Uncertainty Handling
APIs should quantify confidence levels, offer alternative options, and specify triggers for human intervention.

**Example:**
```json
{
"prediction": "fraudulent_transaction",
"confidence": 0.87,
"alternatives": [
{"prediction": "legitimate_transaction", "confidence": 0.12}
],
"requiresHumanReview": true
}
```

### Reasoning Support
APIs should provide decision traces and reasoning chains to explain logic.

**Example:**
```json
{
"decision": "loan_denied",
"reasoningChain": {
"primaryFactors": [
{"factor": "credit_score", "impact": "negative"},
{"factor": "debt_ratio", "impact": "negative"}
],
"decisionTrace": "credit_score_check → risk_assessment"
}
}
```

### Semantic Precision
APIs must eliminate ambiguity with strict typing, enumerated values, and explicit relationships. Clear endpoint and parameter descriptions are essential for understanding functionality.

**Example:**
```json
{
"userStatus": {
"type": "enum",
"value": "ACTIVE",
"allowedValues": ["ACTIVE", "SUSPENDED", "PENDING"],
"description": "Indicates the current status of the user account."
},
"profileCompletion": {
"type": "integer",
"description": "Percentage of profile completed by the user."
}
}
```

### Adaptive Interaction Patterns
APIs should adjust responses based on the AI agent's needs and capabilities.

**Example:**
```json
{
"responseComplexity": "detailed",
"resourceIntensity": {
"cpu": "medium",
"memory": "high"
}
}
```

### Error Prevention
APIs must include a detailed error descriptions should explain why a call failed and how to correct it in subsequent attempts.

**Example:**
```json
{
"error": {
"code": "INVALID_INPUT",
"message": "User ID is missing in one of the entries.",
"remediation": "Ensure all entries include a valid 'userId' field."
}
}
```

### Recovery
APIs must include validation, dry-run options, and recovery mechanisms.

**Example:**
```json
{
"operation": "bulk_user_update",
"validationEndpoint": "/validate/bulk_user_update",
"dryRunOption": "?mode=dry_run",
"rollbackStrategy": {
"available": true,
"window": "24h"
}
}
```

### Resource Awareness
APIs should communicate resource implications such as cost, rate limits, and allocations.

**Example:**
```json
{
"operationCost": {
"creditsCost": 5,
"estimatedDuration": "2s"
},
"rateLimits": {
"current": 98,
"limit": 100
}
}
```

### Temporal Awareness
APIs should specify time-related aspects like validity periods and unambiguous time zones.

**Example:**
```json
{
"dataTimestamp": "2024-01-06T15:30:00Z",
"validityPeriod": {
"start": "2024-01-06T15:30:00Z",
"end": "2024-01-06T16:30:00Z"
}
}
```

### Ethical Considerations
APIs must enforce ethical AI behavior by exposing bias metrics, defining constraints, and assessing impacts.

**Example:**
```json
{
"ethicalMetrics": {
"biasScore": {
"gender": 0.02
},
"fairnessMetrics": {
"equalOpportunity": 0.99
}
},
"impactAssessment": {
"privacyImpact": "medium"
}
}
```

## Implementation Guidelines
1. Version APIs with explicit AI-friendly indicators.
1. Provide machine-readable specifications in OpenAPI format.
1. Include AI-specific endpoints as necessary.
1. Maintain backward compatibility.
1. Document AI-specific features separately.

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/stefanbuck/ai-api-best-practices

Awesome Lists containing this project

README