Api contract documentation
Skill PranavNagrecha/AwesomeSalesforceSkills/skills/admin/api-contract-documentation
Produce or review API contract documentation for Salesforce integrations: versioning policy artifacts, request/response schema specs, error code catalogs, rate limit documentation, OpenAPI generation for sObjects. Trigger keywords: Salesforce API versioning policy, API end-of-life policy, document API endpoints, REST API rate limits, OpenAPI sObjects. NOT for building the endpoint or writing the Apex REST service — use apex/apex-rest-services. NOT for upgrading the API version on your own Apex, LWC or sfdx-project.json — use devops/api-version-management.From its SKILL.md
npx -y skills add PranavNagrecha/AwesomeSalesforceSkills --skill api-contract-documentationAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
SKILL.md
11.6 KB, as published. Nobody here has run it
API Contract Documentation
Use this skill when producing documentation artifacts for Salesforce REST API integrations — versioning policies, error code catalogs, rate limit specifications, and request/response schema documentation. Distinct from API implementation: this skill addresses the documentation layer that consumer teams use to build integrations safely.
Before Starting
Gather this context before working on anything in this domain:
- What API version is the integration using? (e.g., v60.0). Is there a risk this version is approaching end-of-life?
- Does the integration use standard sObjects REST API, custom Apex REST (@RestResource) endpoints, or both?
- What are the daily API request limits for this org? (Check
/services/data/vXX.0/limitsor the Sforce-Limit-Info response header.) - Is an OpenAPI 3.0 document required? Note: Salesforce's OpenAPI beta covers sObjects REST API only — custom Apex REST endpoints must be hand-authored.
Core Concepts
Salesforce API Versioning Policy
Salesforce REST API versioning uses integer version numbers (e.g., v60.0, v61.0). The official policy guarantees:
- A minimum 3-year support window for each released version
- At least 1 year's advance notice before a version is retired
- The
/services/data/endpoint enumerates all currently live API versions with theirversion,label, andurlproperties
The API end-of-life (EOL) policy is documented at developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/api_rest_eol.htm. Integrations should document the API version in use and set calendar reminders to check the EOL list with each Salesforce seasonal release.
Rate Limits and the Sforce-Limit-Info Header
Salesforce API request limits are tracked in a rolling 24-hour window. Two indicators:
Sforce-Limit-Inforesponse header — Every REST API response includes this header with the format:api-usage=XXXX/YYYYwhere XXXX is the number of calls used and YYYY is the daily limit. Consumer systems should log this header to track consumption trends./services/data/vXX.0/limitsresource — Returns the current org's limits across all limit types includingDailyApiRequests. Poll this endpoint to proactively detect approaching exhaustion.
When the daily limit is exhausted:
- HTTP 403 with error code
REQUEST_LIMIT_EXCEEDED(Salesforce REST API behavior) - HTTP 429 (rate limit response — also used in some contexts)
The exact numeric daily limit depends on the org edition and add-on licenses — it is NOT a fixed published value. Retrieve it dynamically from the /limits resource or from the Salesforce Developer Limits Quick Reference cheatsheet at developer.salesforce.com/docs/atlas.en-us.salesforce_app_limits_cheatsheet.meta/salesforce_app_limits_cheatsheet/.
OpenAPI 3.0 for sObjects REST API (Beta)
Salesforce provides a beta OpenAPI 3.0 document generator for the sObjects REST API (standard Create/Read/Update/Delete operations on SObjects). Access via:
GET /services/data/vXX.0/sobjects/{SObjectName}/describe/openapi3_0
Critical limitation: This beta feature generates OpenAPI specs only for standard sObjects REST endpoints. It does NOT cover:
- Custom Apex REST endpoints (
@RestResourceclasses) - Composite API resources (
/composite,/composite/batch) - Connect REST API (Chatter, Experience Cloud)
Custom Apex REST endpoints must have their request/response contracts hand-authored using OpenAPI 3.0 or another specification format.
Common Patterns
Pattern: API Versioning Policy Documentation
When to use: When onboarding a new integration consumer team or producing architecture documentation for an existing integration.
How it works:
- Enumerate live API versions:
GET /services/data/— returns an array of available versions. - Record the integration's pinned version and its
labelfrom the response. - Document the retirement policy: 3-year support window, 1-year advance notice.
- Add a recurring review step (quarterly) to check the Salesforce EOL notice list: check Release Notes and
api_rest_eol.htmwith each seasonal release. - Define the version upgrade SLA for the integration team (e.g., "upgrade within 6 months of deprecation notice").
Pattern: Rate Limit Documentation and Monitoring
When to use: When consumer teams need to understand how to avoid API limit exhaustion during bulk operations or high-frequency integrations.
How it works:
- Document the daily limit retrieval method:
GET /limitsreturnsDailyApiRequests.Maxfor the org. - Establish a monitoring pattern: log the
Sforce-Limit-Info: api-usage=X/Yheader from every response and alert when X/Y > 80%. - Document the error: HTTP 403
REQUEST_LIMIT_EXCEEDEDmeans daily limit is exhausted; HTTP 429 is transient rate throttling. These have different recovery patterns: 403 requires waiting until the 24-hour window resets; 429 requires exponential backoff retry. - For bulk operations, recommend Bulk API 2.0 which has a separate request budget from the REST API limit.
Decision Guidance
| Situation | Recommended Approach | Reason |
|---|---|---|
| Documenting standard CRUD API endpoints | Use sObjects OpenAPI beta + hand-authored supplement | Beta covers CRUD; manually document composite and custom endpoints |
| Documenting custom Apex REST endpoints | Hand-author OpenAPI 3.0 spec | Beta does not cover @RestResource endpoints |
| Consumer needs rate limit ceiling | Retrieve from /limits dynamically, not from documentation | Limit varies by org edition and license |
| Integration hitting REQUEST_LIMIT_EXCEEDED | Wait for 24-hour window reset; switch to Bulk API 2.0 for bulk ops | Daily limit resets on rolling 24-hour basis |
| Checking if API version is near retirement | Check api_rest_eol.htm with each seasonal release | EOL list is updated per Salesforce release cycle |
Recommended Workflow
Step-by-step instructions for an AI agent or practitioner working on this task:
- Enumerate live API versions —
GET /services/data/to record available versions and confirm the integration's version is active. - Retrieve org limits —
GET /services/data/vXX.0/limitsand document theDailyApiRequests.Maxvalue for the org. - Document error codes — Catalog the HTTP status codes the integration must handle: 200/201/204 (success), 400 (malformed request), 401 (authentication), 403 (REQUEST_LIMIT_EXCEEDED or insufficient access), 404 (record not found), 429 (rate throttle), 500 (server error).
- Generate sObjects OpenAPI spec (if applicable) — Use the beta endpoint
GET /sobjects/{SObjectName}/describe/openapi3_0. Save the response as the baseline schema document. - Hand-author Apex REST contracts — For any
@RestResourceendpoints, write the OpenAPI 3.0 spec manually based on the Apex class definition. Include request body schema, response schema, and all error responses. - Document versioning policy — Record pinned API version, support window, and the team's version upgrade SLA.
- Establish limit monitoring — Define how the
Sforce-Limit-Infoheader is logged and at what threshold an alert is triggered.
Review Checklist
Run through these before marking work in this area complete:
- API version documented and checked against EOL list
- Daily API limit retrieved from /limits resource (not hardcoded)
- Error code catalog includes 400, 401, 403 (REQUEST_LIMIT_EXCEEDED), 404, 429, 500
- Sforce-Limit-Info header monitoring pattern documented
- OpenAPI spec covers all endpoints (standard + hand-authored for Apex REST)
- Version upgrade SLA defined for integration team
- No hardcoded rate limit numbers that could become stale
Salesforce-Specific Gotchas
-
Fabricating specific numeric rate limits is dangerous — API request limits are NOT a fixed universal number. They vary by org edition, add-on licenses, and Salesforce's adjustments. Never document a specific hardcoded number. Always reference the
/limitsresource or the developer limits quick reference cheatsheet. -
OpenAPI beta does not cover custom Apex REST — Teams often assume the OpenAPI endpoint generates documentation for all their APIs. Custom
@RestResourceendpoints have no auto-generated spec. They must be hand-authored. -
SLA uptime commitments are not in developer docs — API SLA percentages (uptime, latency) are in trust.salesforce.com and Order of Service agreements, not in the developer documentation. Do not document SLA percentages from developer docs — they do not exist there.
-
REQUEST_LIMIT_EXCEEDED (403) vs 429 rate throttling have different recovery — 403 means the 24-hour allocation is exhausted and requires waiting for the rolling window reset. 429 is a transient throttle that responds to exponential backoff retry. Treating them identically (e.g., immediate retry on 403) will not work.
Output Artifacts
| Artifact | Description |
|---|---|
| API versioning policy document | Pinned version, support window, EOL check cadence, upgrade SLA |
| Rate limit specification | DailyApiRequests.Max from /limits, Sforce-Limit-Info monitoring pattern |
| Error code catalog | All HTTP status codes the integration must handle with recovery guidance |
| OpenAPI 3.0 spec | Generated for sObjects endpoints, hand-authored for Apex REST |
Related Skills
apex/apex-rest-services— Use for implementing custom Apex REST endpoints (@RestResource) — the implementation layer this skill documentsintegration/oauth-flows-and-connected-apps— Use for OAuth flow selection and Connected App configuration for API consumersintegration/api-led-connectivity— Use for designing the API layer architecture before documenting individual endpoints