sf-agent-framework

name: Salesforce API Specification description: Template for documenting REST and SOAP API specifications for Salesforce integrations sections: - name: API Overview content: | ## API Overview ### API Name [API Name and Version] ### Purpose [Describe the business purpose and use cases] ### API Type - [ ] REST API - [ ] SOAP API - [ ] Bulk API - [ ] Streaming API - [ ] Composite API ### Authentication Method - [ ] OAuth 2.0 (Recommended) - [ ] Session ID - [ ] JWT Bearer Token - [ ] Username-Password - name: API Design Principles content: | ## API Design Principles ### RESTful Conventions - Resource-based URLs - HTTP methods for operations - Stateless communication - JSON/XML response formats ### Versioning Strategy - Version in URL: /services/apexrest/v1/resource - Version in header: Accept: application/vnd.company.v1+json ### Error Handling - Consistent error response format - Meaningful error codes - Detailed error messages - HTTP status codes - name: Resource Endpoints content: | ## Resource Endpoints ### Base URL ``` Production: https://[instance].salesforce.com/services/apexrest/ Sandbox: https://[instance]--[sandbox].sandbox.salesforce.com/services/apexrest/ ``` ### Endpoints | Method | Endpoint | Description | Request | Response | |--------|----------|-------------|---------|----------| | GET | /v1/accounts | Get account list | Query params | Account[] | | GET | /v1/accounts/{id} | Get account by ID | Path param | Account | | POST | /v1/accounts | Create account | Account JSON | Account | | PUT | /v1/accounts/{id} | Update account | Account JSON | Account | | DELETE | /v1/accounts/{id} | Delete account | Path param | Success | - name: Request Specifications content: | ## Request Specifications ### Headers ```http Authorization: Bearer {access_token} Content-Type: application/json Accept: application/json X-PrettyPrint: 1 ``` ### Query Parameters | Parameter | Type | Required | Description | Example | |-----------|------|----------|-------------|---------| | limit | integer | No | Records per page | 100 | | offset | integer | No | Starting record | 0 | | fields | string | No | Fields to return | Id,Name | | filter | string | No | Filter criteria | Status='Active' | ### Request Body Schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "name": { "type": "string", "maxLength": 255, "required": true }, "type": { "type": "string", "enum": ["Customer", "Partner", "Prospect"] } } } ``` - name: Response Specifications content: | ## Response Specifications ### Success Response (200 OK) ```json { "success": true, "data": { "id": "001xx000003DHPUAA4", "name": "Acme Corporation", "type": "Customer", "createdDate": "2024-01-15T10:30:00Z" }, "metadata": { "timestamp": "2024-01-15T10:30:00Z", "version": "v1" } } ``` ### Error Response (4xx/5xx) ```json { "success": false, "error": { "code": "INVALID_FIELD", "message": "Field 'email' is not valid for Account object", "details": { "field": "email", "value": "invalid-email" } } } ``` ### HTTP Status Codes | Code | Meaning | Usage | |------|---------|-------| | 200 | OK | Successful GET, PUT | | 201 | Created | Successful POST | | 204 | No Content | Successful DELETE | | 400 | Bad Request | Invalid request | | 401 | Unauthorized | Authentication failed | | 403 | Forbidden | Insufficient permissions | | 404 | Not Found | Resource not found | | 500 | Server Error | Internal error | - name: Security Specifications content: | ## Security Specifications ### Authentication Flow 1. Register Connected App in Salesforce 2. Obtain client_id and client_secret 3. Implement OAuth 2.0 flow 4. Store refresh token securely 5. Use access token for API calls ### Security Requirements - [ ] HTTPS only (TLS 1.2+) - [ ] OAuth 2.0 authentication - [ ] IP whitelisting configured - [ ] Field-level security enforced - [ ] CRUD/FLS checks in Apex - [ ] Input validation - [ ] Output encoding - name: Rate Limits and Quotas content: | ## Rate Limits and Quotas ### API Limits | Limit Type | Enterprise | Unlimited | Performance | |------------|------------|-----------|-------------| | Daily API Requests | 1,000 + (users × 100) | 5,000 + (users × 100) | Contact Salesforce | | Concurrent Requests | 25 | 25 | 25 | | Timeout | 120 seconds | 120 seconds | 120 seconds | ### Best Practices - Implement exponential backoff - Use bulk operations when possible - Cache frequently accessed data - Monitor API usage - Plan for limits - name: Testing and Examples content: | ## Testing and Examples ### cURL Examples ```bash # Get Account curl -X GET \ https://instance.salesforce.com/services/apexrest/v1/accounts/001xx000003DHPUAA4 \ -H "Authorization: Bearer {token}" \ -H "Accept: application/json" # Create Account curl -X POST \ https://instance.salesforce.com/services/apexrest/v1/accounts \ -H "Authorization: Bearer {token}" \ -H "Content-Type: application/json" \ -d '{ "name": "New Account", "type": "Customer" }' ``` ### Postman Collection - Import URL: [Collection Link] - Environment variables required - Test scripts included - name: Implementation Guide content: | ## Implementation Guide ### Apex REST Class Example ```apex @RestResource(urlMapping='/v1/accounts/*') global with sharing class AccountRestService { @HttpGet global static Account getAccount() { RestRequest req = RestContext.request; String accountId = req.requestURI.substringAfterLast('/'); try { return [SELECT Id, Name, Type FROM Account WHERE Id = :accountId]; } catch (Exception e) { RestContext.response.statusCode = 404; return null; } } @HttpPost global static Account createAccount(Account account) { insert account; return account; } } ``` processing-instructions: | When using this template: 1. Follow RESTful design principles 2. Use consistent naming conventions 3. Document all endpoints thoroughly 4. Include example requests/responses 5. Specify error scenarios 6. Consider API versioning from start 7. Plan for security and limits 8. Test with various clients metadata: version: "1.0" category: integration complexity: medium estimated-time: "2-3 days" review-required: true