agentsclimarketplace

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

Install
npx -y skills add PranavNagrecha/AwesomeSalesforceSkills --skill api-contract-documentation

Assembled 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/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

SituationRecommended ApproachReason
Documenting standard CRUD API endpointsUse sObjects OpenAPI beta + hand-authored supplementBeta covers CRUD; manually document composite and custom endpoints
Documenting custom Apex REST endpointsHand-author OpenAPI 3.0 specBeta does not cover @RestResource endpoints
Consumer needs rate limit ceilingRetrieve from /limits dynamically, not from documentationLimit varies by org edition and license
Integration hitting REQUEST_LIMIT_EXCEEDEDWait for 24-hour window reset; switch to Bulk API 2.0 for bulk opsDaily limit resets on rolling 24-hour basis
Checking if API version is near retirementCheck api_rest_eol.htm with each seasonal releaseEOL list is updated per Salesforce release cycle

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

ArtifactDescription
API versioning policy documentPinned version, support window, EOL check cadence, upgrade SLA
Rate limit specificationDailyApiRequests.Max from /limits, Sforce-Limit-Info monitoring pattern
Error code catalogAll HTTP status codes the integration must handle with recovery guidance
OpenAPI 3.0 specGenerated 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 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

Keep looking

Skills are one crate of 613,531. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.