PranavNagrecha Use this skill when Salesforce itself is exposing a custom HTTP contract through Apex. The point is to keep the REST resource thin, explicit about sharing and validation, and predictable in its status codes and JSON behavior. A custom endpoint should be a deliberate choice, not the default substitute for standard APIs or internal Apex calls.
Before Starting
- Is custom Apex REST actually required, or would the standard REST API, Composite API, or an invocable/action pattern be simpler?
- What authentication model and sharing behavior should the caller get?
- How will the URL, payload schema, and response schema evolve without breaking clients?
Core Concepts
@RestResource Is An Adapter Layer
A REST resource should parse the request, validate inputs, delegate to a service, and shape the response. It should not become the only place business logic lives. Thin resources are easier to version, easier to secure, and easier to test by setting RestContext.request and RestContext.response.
Status Codes And Error Bodies Are Part Of The Contract
If an endpoint always returns 200 with a loosely structured body, clients cannot behave reliably. Set explicit status codes, return consistent JSON error shapes, and distinguish validation failures, not-found cases, and server-side exceptions.
Version The URL Mapping Deliberately
Versioning should be visible and explicit, often in the URL mapping or path contract. This keeps older consumers from being broken by incompatible payload changes. Versioning is an operational strategy, not just a naming convention.
Security Must Be Declared And Enforced
REST classes still need explicit sharing decisions and secure data access patterns. Authentication into Salesforce is only one half of the problem; the Apex code must still enforce the right record, object, and field boundaries. Never infer that boundary from the org's release: what a resource class does with no sharing keyword and no query clause is set by the apiVersion in its .cls-meta.xml, and it inverted at 67.0 (Summer '26). Read agents/_shared/AGENT_CONTRACT.md § Apex security idiom by API version before scoring an endpoint's posture.
Common Patterns
Thin Resource + Service Layer
When to use: A custom endpoint handles business logic on Salesforce data.
How it works: Parse request data in the resource class, delegate the real workflow to a service, then set RestContext.response deliberately.
Why not the alternative: Fat resource classes are hard to version and tend to hide security mistakes.
Consistent Error Envelope
When to use: Consumers need stable machine-readable errors.
How it works: Return a simple JSON structure with code, message, and optional correlation ID.
Versioned URL Mapping
When to use: The API contract may evolve incompatibly.
How it works: Include versioning in the URL contract and keep old behavior stable until clients migrate.
Decision Guidance
| Situation | Recommended Approach | Reason |
|---|---|---|
| External system needs a custom business API in Salesforce | Apex REST | Salesforce exposes a deliberate custom contract |
| Consumer only needs standard data CRUD/query access | Prefer standard Salesforce APIs | Less code and less custom maintenance |
| Contract may change incompatibly over time | Versioned URL mapping and payload contract | Safer client evolution |
| Endpoint updates Salesforce data | Thin REST resource + secure service layer | Better maintainability and security review |
Recommended Workflow
Step-by-step instructions for an AI agent or practitioner activating this skill:
- Gather context — confirm the org edition, relevant objects, and current configuration state
- Review official sources — check the references in this skill's well-architected.md before making changes
- Implement or advise — apply the patterns from Core Concepts and Common Patterns sections above
- Validate — run the skill's checker script and verify against the Review Checklist below
- Document — record any deviations from standard patterns and update the template if needed
Review Checklist
- A custom Apex REST endpoint is justified over standard APIs.
- The resource class is thin and delegates business logic.
- Status codes and JSON error bodies are explicit and consistent.
- Sharing and data-access enforcement are deliberate, not assumed.
- URL mapping or payload versioning is defined.
- Tests set
RestContext.requestandRestContext.responseexplicitly.
Salesforce-Specific Gotchas
RestContextis only populated in REST execution or tests that set it — do not assume it exists in ordinary Apex contexts.- Apex REST security is not automatic beyond authentication — data access still needs explicit review.
- Returning raw exceptions as response bodies leaks internals — map failures to stable error contracts.
- Resource classes become brittle fast if business logic lives directly inside them — versioning pain follows.
Output Artifacts
| Artifact | Description |
|---|---|
| REST endpoint review | Findings on contract design, status handling, security, and versioning |
| Resource scaffold | Thin @RestResource class with explicit request parsing and response shaping |
| Versioning notes | Guidance for evolving the endpoint without breaking consumers |
Related Skills
apex/apex-security-patterns— use when the main risk is the sharing or CRUD/FLS posture of the endpoint.apex/exception-handling— use when the error contract and internal failure mapping need refinement.apex/test-class-standards— use when REST resource tests are weak or missing request/response assertions.