Integrations • Vendor API Orchestration
Automotive Data Orchestration: Carfax, KBB, and FTP Imaging
Quick Links
Integration work is rarely glamorous, but it’s where a lot of real engineering lives: every vendor has a different protocol, a different idea of authentication, and a different set of edge cases. This service absorbs all of that — Carfax over GraphQL with managed OAuth, KBB over SOAP/XML, imagery over FTP — and gives the rest of the platform a single, stable contract to build on.
Summary
- Problem: Dealer inventory needs data from several third-party systems, each with its own protocol, auth model, and quirks — GraphQL, SOAP/XML, FTP.
- Solution: A single Spring Boot service that owns each vendor integration and exposes one consistent internal API to the rest of the platform.
- Impact: The DMS consumes vehicle history, valuations, and imagery through one contract instead of five vendor-specific ones, with token and file handling centralized.
Context
This is the inventory backend for an automotive dealer management system. Vehicle records are enriched from multiple external providers, and dealers upload imagery that has to be processed and served. Each provider speaks a different protocol and has a different auth and billing model, so the service's job is to absorb that heterogeneity and present one stable internal API.
Goals, Requirements, Constraints
Goals
- Expose one internal API over several different vendor protocols
- Centralize OAuth token acquisition and refresh so callers never deal with vendor auth
- Handle dealer image uploads end to end — store, thumbnail, reorder, delete
- Support per-dealer vendor billing models
Constraints
- Vendors differ in protocol (GraphQL vs SOAP/XML), auth (OAuth vs none), and billing
- Imagery is delivered and stored over FTP with a fixed path convention
- Long-lived production service (Spring Boot 2.4, Java 11)
Approach
Each vendor gets its own service class encapsulating that provider's protocol and auth, behind controllers that present a uniform internal API. Carfax uses GraphQL with an OAuth login flow whose access token is persisted and refreshed before expiry; KBB valuations are fetched from downstream SOAP/XML endpoints and reshaped into the internal format; image operations are implemented against an FTP server with a deterministic path scheme, including thumbnail selection and reordering via a temp directory.
Key Design Decisions
- Decision: One internal contract over many vendor protocols
Why: Callers (the DMS) shouldn't know or care that Carfax is GraphQL and KBB is SOAP. Wrapping each vendor in its own service behind a uniform controller keeps that complexity in one place.
Alternatives: Letting each consumer call vendors directly would scatter auth, retries, and protocol quirks across the codebase. - Decision: Persist and refresh the Carfax OAuth token centrally
Why: The access token is stored with its expiry and refreshed before it lapses, so every request has a valid token without each caller re-authenticating.
Alternatives: Re-authenticating per request is slower and hammers the vendor's auth endpoint. - Decision: Deterministic FTP image paths + temp-dir reordering
Why: A fixed path convention (keyed by dealer, location, and VIN) makes images addressable and lets reordering happen via a temporary subdirectory so the live set is never left half-renamed.
Alternatives: Ad-hoc paths or in-place renaming risk broken image URLs mid-operation.
Implementation
Components / Modules
- Carfax integration: GraphQL client with an OAuth login flow; access token persisted with expiry and refreshed; supports the dealer charge models the vendor offers.
- KBB valuation: Fetches vehicle values from downstream SOAP/XML endpoints (VIN decode + value) and reshapes the response into the internal format consumed by the DMS.
- Imaging over FTP: Upload, thumbnail selection, reordering (via a temp subdirectory), deletion, and renaming against a deterministic FTP path scheme.
- Inventory costs + AutoCheck: Inventory cost tracking persisted in the database; AutoCheck history exposed alongside Carfax.
Security
- Vendor credential exposure: OAuth tokens stored server-side and refreshed centrally, never handed to clients
- Broken image state during reordering: operations staged in a temp directory so the live image set stays consistent
Controls Implemented
- Centralized server-side storage and refresh of vendor OAuth tokens
- Vendor protocol details (GraphQL/SOAP/FTP) encapsulated behind internal controllers
Verification
- Token refresh exercised against expiry handling before requests
Operations
Observability
- Per-vendor error surfaces mapped to consistent internal responses
Incident Response
- Vendor outage: failures isolated per integration so one provider's downtime doesn't take out the others
- Expired/invalid token: central refresh re-acquires; manual re-auth path available
Results
Outcomes
- Simplicity: The DMS consumes history, valuations, and imagery through one internal API instead of five vendor-specific integrations.
- Maintainability: Each vendor's protocol, auth, and quirks live in one service class, so changes stay contained.
- Correctness: Centralized token refresh and staged image operations avoid expired-auth failures and broken image URLs.
Tradeoffs
- A single integration service is a shared dependency for inventory features — it has to stay reliable
- Wrapping every vendor in a uniform contract adds a translation layer per provider
Next Steps
- Add per-vendor circuit breakers and richer retry policies
- Surface integration health metrics per provider