sf-agent-framework/sf-core/tasks/api-design.md

AI Agent Orchestration Framework for Salesforce Development - Two-phase architecture with 70% context reduction

# API Design

## Purpose

Design robust and scalable APIs for Salesforce integrations, following REST and
SOAP best practices while adhering to Salesforce API limits and patterns.

## Instructions

1. **API Requirements Analysis**
   - Identify integration touchpoints and data flows
   - Document API consumers and their use cases
   - Define data volume and frequency requirements
   - Establish performance and scalability targets

2. **API Architecture Design**
   - Choose appropriate API pattern (REST, SOAP, Bulk, Streaming)
   - Design resource hierarchy and naming conventions
   - Plan authentication and authorization strategy
   - Define API versioning approach

3. **Salesforce API Implementation**
   - Design custom REST APIs using Apex REST
   - Implement SOAP web services where required
   - Configure Connected Apps for OAuth flows
   - Set up appropriate API limits and throttling

4. **Data Contract Definition**
   - Create detailed API specifications (OpenAPI/Swagger)
   - Define request/response schemas
   - Document error handling and status codes
   - Establish data validation rules

5. **Integration Patterns**
   - Implement appropriate integration patterns:
     - Request-Reply for synchronous operations
     - Fire-and-Forget for asynchronous processing
     - Batch Data Sync for large volumes
     - Remote Call-In for external system updates

6. **Security Implementation**
   - Configure OAuth 2.0 flows
   - Implement API key management
   - Set up IP restrictions and CORS policies
   - Design field-level security for API access

## Input Requirements

- Integration requirements document
- System landscape and touchpoints
- Data volume projections
- Security and compliance requirements
- Performance SLAs

## Output Format

- API Design Document
- OpenAPI/Swagger specifications
- Implementation guide with code samples
- Security configuration checklist
- API testing scenarios

## Best Practices

- Follow RESTful design principles
- Use meaningful HTTP status codes
- Implement proper pagination for large datasets
- Design for idempotency where applicable
- Monitor API usage against governor limits
- Implement comprehensive error handling
- Use Platform Events for real-time integrations
- Document all APIs thoroughly