API Surface

The gateway exposes a versioned REST API to consumers. The Salesforce spike established the surface; it generalizes to our other resources.

Versioning

All endpoints are prefixed with /v1. Breaking changes ship as /v2. Non-breaking additions (new fields, new endpoints) land in the existing version.

Endpoints (Salesforce Reference)

The spike built the following. All but /healthz are coded but blocked on Salesforce custom field creation.

Health

GET /v1/healthz

No auth. Returns gateway status and live connection state to each of our configured resources.

{
  "status": "ok",
  "salesforce": {
    "connected": true,
    "user": {
      "Id": "0051Q00000HIbamQAD",
      "Name": "Platform Integration User"
    }
  }
}

This is the canary for the entire gateway.

Members

GET /v1/members/:externalId

Look up a Salesforce Contact by external ID. The External_Id__c field is the join key.

Quotes — Full CRUD

POST   /v1/quotes
GET    /v1/quotes/:id
PATCH  /v1/quotes/:id
DELETE /v1/quotes/:id

Maps to our Quote__c custom object.

Bookings — Full CRUD

POST   /v1/bookings
GET    /v1/bookings/:id
PATCH  /v1/bookings/:id
DELETE /v1/bookings/:id

Maps to our Booking__c custom object.

Webhooks (Inbound from Our Resources)

POST /v1/webhooks/salesforce/members

Vendor-side webhooks terminate at the gateway. See Webhooks.

Conventions

External IDs

UUIDs generated server-side. Stored in External_Id__c on our SF side. SF native IDs never leak to consumers — those are our internal identifiers.

Idempotency

POST /v1/quotes
Idempotency-Key: `<uuid>`

Required for all writes. The gateway dedupes by key, with results cached in Redis for 24 hours.

Pagination

List endpoints return a cursor:

{
  "data": [...],
  "next_cursor": "...",
  "has_more": true
}

Cross-Resource Concepts

Some consumer-facing concepts span our resources (e.g., a "reservation" might involve both a dining partner and our SF booking record). The gateway presents a unified resource; the connector layer fans out to the right resources.

OpenAPI

Every endpoint is documented in OpenAPI 3.x and served at /v1/docs.