Skip to content
HeadlessWP Pro

API flows and examples

End-to-end flows and patterns for building stable headless apps.

API flows and examples

This guide summarizes practical request patterns for building on HeadlessWP Pro while preserving the secure proxy boundary used by this site.

Use this page for flow-level guidance. For endpoint-specific request/response contracts, use the endpoint docs under /docs/api/endpoints.

Canonical first request flow

For a browser client, the first request should validate that upstream services are healthy before any authenticated action.

  1. Browser calls a same-origin Next.js route.
  2. Next.js route proxies through /api/secure/**.
  3. Proxy forwards only allowlisted upstream routes and query keys.
  4. Client receives the normalized JSON envelope and correlation metadata.

In this repo, typical first checks are health, store offers, or capability checks routed through the secure proxy.

Cookie session + nonce flow

When using a cookie-backed user session:

  1. Sign in via the secure proxy login flow.
  2. Read the nonce from the nonce endpoint.
  3. Include X-WP-Nonce on all mutating requests and on user-specific reads enforced by the proxy policy.
  4. Route every browser request through Next.js /api/secure/** handlers (never direct browser calls to the WordPress origin).

This mirrors the CSRF model documented in docs/SECURITY.md.

API key flow (server-side)

For server-rendered or backend automation flows, use service account API keys on server-side requests only.

Recommended sequence:

  1. Server receives incoming app request.
  2. Server loads API key from secure environment configuration.
  3. Server sends allowlisted upstream request through the secure client/proxy chain.
  4. Server returns a sanitized response to the browser without exposing the key.

Do not expose service account keys in client bundles or browser storage.

Checkout -> post-purchase -> account narrative

A common buyer journey in this repo follows this pattern:

  1. Read storefront data (offers/products) to render plan selection.
  2. Create or update the checkout/cart state through secure proxy routes.
  3. Complete purchase and redirect to post-purchase confirmation.
  4. Guide the user into account pages for ongoing access and entitlements.

Implementation guidance:

  • Treat checkout/cart operations as user-specific and non-cacheable.
  • Preserve session cookies and nonce requirements for protected operations.
  • Use account endpoints as the source of truth for what the user can access after purchase.

Debug flow with correlation id

When troubleshooting failed requests:

  1. Capture response status and standard error envelope (error, meta).
  2. Record the correlation id returned by the proxied response metadata/headers.
  3. Match that correlation id with proxy/server logs to trace the exact request path.
  4. Re-run with the same flow order (auth, nonce, mutation) to detect ordering issues.

Correlation ids are the fastest way to connect UI failures to proxy and upstream logs without exposing sensitive request data.