sf-agent-framework/sf-core/checklists/api-design-checklist.md

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

# Salesforce API Design Checklist

## Overview

This checklist ensures REST and SOAP APIs built on Salesforce follow best
practices for security, performance, and maintainability.

## API Planning and Design

### Business Requirements

- [ ] Define clear API purpose and scope
- [ ] Identify target consumers (internal/external)
- [ ] Document use cases and user stories
- [ ] Define SLAs and performance requirements
- [ ] Establish versioning strategy
- [ ] Plan for backward compatibility

### API Design Principles

- [ ] Follow RESTful principles for REST APIs
- [ ] Use consistent naming conventions
- [ ] Design resource-oriented endpoints
- [ ] Implement HATEOAS where appropriate
- [ ] Plan for idempotency
- [ ] Design for statelessness

## REST API Development

### Endpoint Design

- [ ] Use nouns for resources (e.g., /accounts, /contacts)
- [ ] Implement proper HTTP methods (GET, POST, PUT, DELETE, PATCH)
- [ ] Use plural names for collections
- [ ] Nest resources logically (e.g., /accounts/{id}/contacts)
- [ ] Keep URLs simple and intuitive
- [ ] Limit nesting to 2-3 levels maximum

### Request/Response Design

- [ ] Use JSON as default format
- [ ] Support content negotiation
- [ ] Include request ID for tracking
- [ ] Implement consistent date/time formats (ISO 8601)
- [ ] Use camelCase for JSON properties
- [ ] Provide meaningful response messages

### HTTP Status Codes

- [ ] 200 OK for successful GET/PUT
- [ ] 201 Created for successful POST
- [ ] 204 No Content for successful DELETE
- [ ] 400 Bad Request for validation errors
- [ ] 401 Unauthorized for authentication failures
- [ ] 403 Forbidden for authorization failures
- [ ] 404 Not Found for missing resources
- [ ] 429 Too Many Requests for rate limiting
- [ ] 500 Internal Server Error for system errors

## SOAP API Development

### WSDL Design

- [ ] Create clear and complete WSDL
- [ ] Define all operations clearly
- [ ] Use appropriate SOAP binding style
- [ ] Include comprehensive type definitions
- [ ] Document all parameters
- [ ] Version WSDL appropriately

### Message Design

- [ ] Use document/literal wrapped style
- [ ] Define clear request/response messages
- [ ] Include fault messages
- [ ] Use consistent naming conventions
- [ ] Implement WS-Security standards
- [ ] Support SOAP headers appropriately

## Authentication and Security

### Authentication Methods

- [ ] Implement OAuth 2.0 for REST APIs
- [ ] Use appropriate OAuth flow
- [ ] Support refresh tokens
- [ ] Implement JWT for stateless auth
- [ ] Use session-based auth for SOAP
- [ ] Never expose credentials in URLs

### Authorization

- [ ] Implement proper permission checks
- [ ] Use Salesforce sharing rules
- [ ] Enforce field-level security
- [ ] Check object-level permissions
- [ ] Implement custom permission sets
- [ ] Validate user context

### Data Security

- [ ] Encrypt sensitive data in transit (TLS 1.2+)
- [ ] Implement field-level encryption where needed
- [ ] Mask sensitive data in responses
- [ ] Prevent SQL/SOQL injection
- [ ] Sanitize all inputs
- [ ] Implement CORS properly

## Error Handling

### Error Response Format

```json
{
  "error": {
    "code": "INVALID_FIELD",
    "message": "The field 'email' has an invalid format",
    "details": [
      {
        "field": "email",
        "issue": "Invalid email format",
        "suggestion": "Please provide a valid email address"
      }
    ],
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}
```

### Error Handling Best Practices

- [ ] Return consistent error format
- [ ] Include error codes for programmatic handling
- [ ] Provide helpful error messages
- [ ] Log errors appropriately
- [ ] Don't expose internal details
- [ ] Include correlation IDs

## Performance Optimization

### Query Optimization

- [ ] Use selective queries
- [ ] Limit fields returned
- [ ] Implement pagination
- [ ] Use indexed fields in WHERE clauses
- [ ] Avoid SOQL in loops
- [ ] Batch operations where possible

### Response Optimization

- [ ] Implement field filtering
- [ ] Support partial responses
- [ ] Use compression (gzip)
- [ ] Implement caching headers
- [ ] Minimize payload size
- [ ] Consider async patterns for long operations

### Rate Limiting

- [ ] Implement rate limiting
- [ ] Return rate limit headers
- [ ] Use sliding window approach
- [ ] Differentiate by client type
- [ ] Provide clear limit information
- [ ] Implement graceful degradation

## API Documentation

### API Reference

- [ ] Document all endpoints
- [ ] Include request/response examples
- [ ] List all parameters
- [ ] Specify required vs optional
- [ ] Document error responses
- [ ] Include authentication details

### Developer Guide

- [ ] Provide getting started guide
- [ ] Include code examples
- [ ] Document common use cases
- [ ] Explain rate limits
- [ ] Provide SDKs or client libraries
- [ ] Include troubleshooting guide

### OpenAPI/Swagger

- [ ] Generate OpenAPI specification
- [ ] Keep spec up to date
- [ ] Include all operations
- [ ] Document security schemes
- [ ] Provide interactive documentation
- [ ] Version API documentation

## Testing

### Unit Testing

- [ ] Test all API methods
- [ ] Mock external dependencies
- [ ] Test error scenarios
- [ ] Validate response formats
- [ ] Test authorization logic
- [ ] Achieve >90% code coverage

### Integration Testing

- [ ] Test end-to-end flows
- [ ] Validate with real data
- [ ] Test concurrent requests
- [ ] Verify rate limiting
- [ ] Test timeout scenarios
- [ ] Validate error handling

### Performance Testing

- [ ] Load test all endpoints
- [ ] Test with expected volumes
- [ ] Measure response times
- [ ] Test under stress conditions
- [ ] Validate resource usage
- [ ] Test scalability

## Versioning and Lifecycle

### Version Strategy

- [ ] Use semantic versioning
- [ ] Version in URL path (/v1/, /v2/)
- [ ] Maintain backward compatibility
- [ ] Document breaking changes
- [ ] Provide migration guides
- [ ] Support multiple versions

### Deprecation Process

- [ ] Announce deprecation early
- [ ] Provide sunset timeline
- [ ] Offer migration path
- [ ] Send deprecation warnings
- [ ] Maintain old version temporarily
- [ ] Document alternatives

## Monitoring and Analytics

### API Monitoring

- [ ] Monitor availability
- [ ] Track response times
- [ ] Alert on errors
- [ ] Monitor rate limit violations
- [ ] Track usage patterns
- [ ] Set up automated alerts

### Analytics and Metrics

- [ ] Track API usage by endpoint
- [ ] Monitor unique consumers
- [ ] Analyze error rates
- [ ] Measure performance trends
- [ ] Track adoption metrics
- [ ] Generate usage reports

## Governance and Compliance

### API Governance

- [ ] Establish API standards
- [ ] Implement review process
- [ ] Maintain API inventory
- [ ] Track API lifecycle
- [ ] Enforce naming conventions
- [ ] Regular architecture reviews

### Compliance Requirements

- [ ] GDPR compliance for PII
- [ ] HIPAA compliance for health data
- [ ] PCI compliance for payment data
- [ ] SOC 2 compliance
- [ ] Data residency requirements
- [ ] Audit logging requirements

## Deployment and Operations

### Deployment Checklist

- [ ] Deploy to sandbox first
- [ ] Run integration tests
- [ ] Verify security settings
- [ ] Update documentation
- [ ] Configure monitoring
- [ ] Plan rollback strategy

### Operational Readiness

- [ ] Create runbooks
- [ ] Set up alerts
- [ ] Define SLAs
- [ ] Plan capacity
- [ ] Configure backups
- [ ] Establish support process

## Best Practices Summary

### Do's

- [ ] Use consistent naming conventions
- [ ] Implement comprehensive error handling
- [ ] Version your APIs
- [ ] Document thoroughly
- [ ] Test extensively
- [ ] Monitor continuously

### Don'ts

- [ ] Don't expose internal IDs
- [ ] Don't return sensitive data
- [ ] Don't ignore rate limiting
- [ ] Don't break backward compatibility
- [ ] Don't skip security reviews
- [ ] Don't neglect documentation