How to integrate Drupal with REST/GraphQL and external APIs?

Long Answer

A production-grade strategy for Drupal integration treats external systems as unreliable and your site as the source of truth. The aim is to connect REST, GraphQL, and third-party APIs while managing authentication and data consistency without hurting performance.

1) Architecture & contracts
Wrap vendors behind a service layer (custom module) exposing interfaces for products, profiles, orders, or CRM contacts. Use typed DTOs to map remote payloads to internal models; keep vendor schemas at edges. Version every contract and prefer additive changes. For outbound APIs, publish OpenAPI/GraphQL SDL and validate requests.

2) Authentication & authorization
Use OAuth2/OIDC for user flows, client-credentials for server-to-server, and HMAC signatures for webhooks. Store secrets in a vault; rotate automatically. Accept short-lived JWTs with aud/iss checks and refresh. Gate access via an API gateway enforcing TLS, scopes, quotas, and IP allow-lists. For internal calls, prefer mTLS.

3) Consistency & sync models
Adopt push+pull. Webhooks (push) provide freshness; verify (HMAC+timestamp) and re-fetch by ID (pull) to avoid spoofed or partial payloads. Keep an idempotency table keyed by (source,eventId) to dedupe repeats. For bulk loads, run scheduled backfills/diff jobs to hydrate normalized snapshots in Drupal. Use write-through for authoritative fields and write-behind for enrichments. Reconcile by business keys, not only UUIDs.

4) Performance: caching & snapshots
Split reads: edge CDN, Drupal render/entity cache (cache tags), and persisted snapshots so templates avoid vendor latency. Invalidate by tags on webhook receipt. Coalesce duplicate calls; add request memoization. For GraphQL, prefer persisted queries.

5) Resilience & backpressure
Protect downstreams with timeouts, retries with jittered backoff, and circuit breakers that degrade to snapshots when partners fail. Batch writes, throttle per client/route, and enforce rate limits per token/IP/ASN. For queue-driven work (imports, order sync), use Drupal Queue API or a worker with dead-letters and replay.

6) Migrations & schema evolution
Use migrate/migrate_plus for initial loads; keep mappings declarative and idempotent. For ongoing changes, run expand→migrate→contract: add fields, backfill in chunks, switch reads, then drop legacy columns after cool-down. Document via update hooks and tests.

7) Observability & governance
Emit structured logs with correlation IDs. Track RED metrics, webhook success %, cache hits, and queue age. Alert on fast/slow burn. Add feature flags to disable a shaky integration. Governance: secret scanning, SCA, and role audits.

8) Editor & DX
Expose admin health (last sync, queue depth) and retry actions. Preview renders from snapshots, then hydrates.

Result
These practices make Drupal integration predictable: auth is standards-based, sync is idempotent, pages render from cached snapshots, and failures degrade gracefully; external APIs remain flexible.

‍

Table

‍

Common Mistakes

Treating vendors as always-on and querying live APIs from templates, turning traffic spikes into outages. Using ad-hoc tokens instead of OAuth2/OIDC or HMAC-signed webhooks; secrets linger in code repos. No idempotency table, so webhook retries duplicate orders or profiles. Over-trusting payloads: accepting updates without re-fetching by ID, letting attackers spoof fields. Ignoring cache tags and snapshot layers—pages block on slow partners. Running one giant migration that locks hot tables, rather than expand→migrate→contract with chunked backfills. No breakers or per-route throttles; your site DDoSes a vendor on retries. Opaque logs: no correlation IDs, RED metrics, or alerting on DLQ growth. Finally, mixing vendor schemas throughout code, which multiplies diffs and slows every change; keep Drupal integration boundaries clean.

‍

Sample Answers (Junior / Mid / Senior)

Junior:
“I expose a small Drupal integration service that calls a REST API with OAuth2 client-credentials. I validate inputs, set timeouts, and cache responses using render cache + tags. Webhooks are HMAC-signed; I record event IDs to avoid duplicates.”

Mid:
“I wrap vendors with a module that returns DTOs, not raw payloads. We use OAuth2/OIDC for auth, HMAC webhooks, and a ledger for idempotency. Data is synced by webhook + re-fetch by ID. We serve pages from snapshots and invalidate via cache tags. Migrations use migrate_plus and chunked backfills.”

Senior:
“Contracts are versioned (OpenAPI/SDL) and validated at edges. Auth is standards-based (OAuth2/OIDC, mTLS); secrets live in a vault. We run push+pull sync with idempotency keys, retries with jitter, and circuit breakers. Observability tracks RED metrics, webhook success %, and queue age. Releases ship behind flags and have killswitches per integration. Schema changes follow expand→migrate→contract.”

‍

Evaluation Criteria

Expect a structured plan that covers interfaces, auth, consistency, performance, and safety. Strong answers: (1) clean service layer + DTOs that isolate vendors; (2) standards-based auth—OAuth2/OIDC for users and server-to-server, HMAC-signed webhooks, secrets in a vault, optional mTLS; (3) data consistency via webhook + re-fetch by ID, an idempotency ledger, and scheduled diffs/backfills; (4) performance using CDN, Drupal render/entity cache with cache tags, and persisted snapshots; (5) resilience with timeouts, jittered retries, circuit breakers, and per-route throttles; (6) migrations with migrate/migrate_plus and expand→migrate→contract; (7) observability with correlation IDs, RED metrics, webhook %, cache hit rate, and alerts; (8) governance—flags/killswitches, SCA/secret scanning. Red flags: templates calling live vendors, ad-hoc tokens, no dedupe table, blocking migrations, or logs with no correlation IDs. Bonus: versioned OpenAPI/SDL and Postman collections for partners.

‍

Preparation Tips

Build a mini lab that proves Drupal integration end-to-end. Create a custom module exposing a service layer and DTOs. Publish a tiny OpenAPI/SDL, then consume a mock vendor API via OAuth2 client-credentials; protect webhooks with HMAC. Implement push+pull sync: on webhook receipt, verify signature, then re-fetch by ID; store an idempotency row to dedupe. Add snapshots (JSON per entity) and render/entity cache with tags; invalidate on events. Wire timeouts, retries with jitter, and a circuit breaker falling back to snapshots. Use migrate/migrate_plus to import seed data; run a small expand→migrate→contract change with chunked backfills. Add structured logging with correlation IDs, dashboards for RED metrics, webhook %, queue age; alert on DLQ growth. Include a Postman collection and a README that documents cache tags and a runbook for pausing an integration. Record a short demo tying auth, consistency, caching, and resilience to KPIs.

‍

Real-world Context

A marketplace integrated Drupal with a PIM via REST. Early pages were slow because templates hit the PIM live. Switching to snapshots + cache tags cut p95 by 45% and let editors preview instantly. A fintech receiving KYC webhooks saw duplicates; adding an idempotency ledger and re-fetch-by-ID eliminated double updates and simplified audits. An education platform moved to GraphQL with persisted queries; CDN caching and field-level TTLs dropped origin traffic by 60%. A retailer’s vendor outage once broke PDPs; after circuit breakers and graceful degradation, pages rendered from snapshots with a banner, and revenue held steady. A B2B team standardised OAuth2/OIDC and secret rotation; an expired key auto-refreshed instead of causing a 30-minute incident. Finally, migrations: replacing big-bang changes with expand→migrate→contract and chunked backfills removed nighttime outages and made rollbacks trivial—proving disciplined Drupal integration boosts speed, reliability, and trust. Teams gained clearer dashboards and faster MTTR.

‍

Key Takeaways

• Treat Drupal integration as a contract: service layer, DTOs, versioned schemas.
  
• Use OAuth2/OIDC, HMAC webhooks, short-lived JWTs; store secrets in a vault.
  
• Ensure data consistency with webhook + re-fetch, idempotency keys, and diffs.
  
• Serve from CDN + Drupal cache + snapshots; invalidate by cache tags.
  
• Add retries with jitter, circuit breakers, throttles, and DLQ-backed queues.
  
  

Practice Exercise

Scenario: Your Drupal site must integrate a product catalog (vendor REST), a CRM (webhooks), and a pricing service (GraphQL). Traffic spikes daily; partners rate-limit.

Tasks:

1. Contracts & Service Layer: Build a custom module that wraps each vendor behind interfaces returning DTOs. Publish OpenAPI/SDL for your outbound endpoints and validate at edges.
   
2. Auth: Use OAuth2 client-credentials for REST/GraphQL; protect webhooks with HMAC + timestamp. Store secrets in a vault and rotate.
   
3. Consistency: Implement push+pull: verify webhook, then re-fetch by ID. Create an idempotency table keyed by (source,eventId) storing outcome and checksum.
   
4. Caching & Snapshots: Persist JSON snapshots per product and serve pages from snapshots; invalidate with cache tags when events arrive. Enable CDN caching and coalesce duplicate calls.
   
5. Resilience: Add timeouts, jittered retries, and circuit breakers that fall back to snapshots. Throttle per route and per token.
   
6. Migrations: Use migrate_plus for initial import; execute expand→migrate→contract to add a new attribute; backfill in 5k-row chunks.
   
7. Observability: Emit correlation IDs; dashboard RED metrics, webhook success %, queue age; alert on DLQ growth and SLO burns.
   
8. Drill: Simulate vendor 503s and duplicate webhooks; prove single update, stable p95, and quick disable via killswitch.
   
   

Deliverable: A repository with module code, snapshots, alerts, and a runbook. Include a short demo showing auth, idempotency, caching, and graceful degradation.