Procore Contract-Preserving REST Client
Overview
Keep the client transport-focused and endpoint versions explicit. Procore resources use multiple REST versions, endpoint-specific page limits, company routing requirements, and actionable response headers that a generic JSON wrapper must not erase.
Prerequisites
- Enumerated public endpoints and their current reference versions
- Token-provider interface that never exposes client secrets to callers
- Typed error, pagination, rate-budget, and redaction contracts
Instructions
Step 1: Model requests explicitly
Represent HTTP method, full documented route, API version, company ID, project ID, query parameters, and body separately. Reject private or guessed routes.
Step 2: Centralize safe headers
Add the Bearer token at dispatch time. Carry Procore-Company-Id from explicit request context where required, and never infer company routing from a cached payload.
Step 3: Preserve response metadata
Return status, parsed body, request correlation data, Link, Total, Per-Page, X-Rate-Limit-*, and Retry-After to higher layers.
Step 4: Bound retries
Retry only safe reads or mutations with a proven idempotency design. Honor reset or retry headers, add jitter, cap attempts, and surface the final provider response.
Step 5: Test endpoint adapters
Give each resource adapter contract fixtures for success, pagination, permission denial, validation errors, throttling, and server failure. Keep business workflows outside the transport.
Authentication
The client receives OAuth 2.0 Bearer tokens from an external token provider and injects them only at request dispatch. It must not accept client secrets as ordinary endpoint parameters or log authorization headers.
Tool Discipline
Use Read and Grep to inspect existing transports, endpoint references, and call sites. Use Write or Edit only for the approved client, adapter, tests, or receipt; do not silently rewrite business workflows or provider data.
Output
- Typed transport and endpoint adapter boundary
- Pagination, throttling, error, and redaction tests
- Endpoint-version inventory and upgrade ownership
Return which response contracts are preserved and which endpoints remain outside the client.
Examples
A submittals adapter selects the documented submittals version explicitly and returns Link-header pagination to the caller. The shared transport adds routing and auth headers, but it does not pretend all resources share that version or page size.
Error Handling
| Failure | Response |
|---|---|
| Undocumented route requested | Reject locally and require a public API reference. |
| Company context missing | Fail before dispatch when the endpoint requires company routing. |
| 429 or 503 response | Honor provider timing headers, enqueue work, and retry only within the bounded policy. |
| Ambiguous mutation outcome | Stop automatic retry and reconcile the resource before another write. |