API Contract Documentation

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/limits or 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 their version, label, and url properties

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:

1. Sforce-Limit-Info response header — Every REST API response includes this header with the format: api-usage=XXXX/YYYY where XXXX is the number of calls used and YYYY is the daily limit. Consumer systems should log this header to track consumption trends.
2. /services/data/vXX.0/limits resource — Returns the current org's limits across all limit types including DailyApiRequests. 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 (@RestResource classes)
• 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:

1. Enumerate live API versions: GET /services/data/ — returns an array of available versions.
2. Record the integration's pinned version and its label from the response.
3. Document the retirement policy: 3-year support window, 1-year advance notice.
4. Add a recurring review step (quarterly) to check the Salesforce EOL notice list: check Release Notes and api_rest_eol.htm with each seasonal release.
5. 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:

1. Document the daily limit retrieval method: GET /limits returns DailyApiRequests.Max for the org.
2. Establish a monitoring pattern: log the Sforce-Limit-Info: api-usage=X/Y header from every response and alert when X/Y > 80%.
3. Document the error: HTTP 403 REQUEST_LIMIT_EXCEEDED means 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.
4. For bulk operations, recommend Bulk API 2.0 which has a separate request budget from the REST API limit.

Decision Guidance

Recommended Workflow

Step-by-step instructions for an AI agent or practitioner working on this task:

1. Enumerate live API versions — GET /services/data/ to record available versions and confirm the integration's version is active.
2. Retrieve org limits — GET /services/data/vXX.0/limits and document the DailyApiRequests.Max value for the org.
3. 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).
4. Generate sObjects OpenAPI spec (if applicable) — Use the beta endpoint GET /sobjects/{SObjectName}/describe/openapi3_0. Save the response as the baseline schema document.
5. Hand-author Apex REST contracts — For any @RestResource endpoints, write the OpenAPI 3.0 spec manually based on the Apex class definition. Include request body schema, response schema, and all error responses.
6. Document versioning policy — Record pinned API version, support window, and the team's version upgrade SLA.
7. Establish limit monitoring — Define how the Sforce-Limit-Info header 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

1. 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 /limits resource or the developer limits quick reference cheatsheet.

2. OpenAPI beta does not cover custom Apex REST — Teams often assume the OpenAPI endpoint generates documentation for all their APIs. Custom @RestResource endpoints have no auto-generated spec. They must be hand-authored.

3. 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.

4. 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

Related Skills

• apex/apex-rest-services — Use for implementing custom Apex REST endpoints (@RestResource) — the implementation layer this skill documents
• integration/oauth-flows-and-connected-apps — Use for OAuth flow selection and Connected App configuration for API consumers
• integration/api-led-connectivity — Use for designing the API layer architecture before documenting individual endpoints