When two systems need to share data, there are usually two paths available: connect directly to the underlying database, or go through the system's API (where one exists). Both are legitimate choices — the right one depends on what you're building and how long it needs to keep working.
Direct database access: when it's the right call
- Internal, one-off reporting where you control both ends and can tolerate rebuilding the query if the schema changes.
- Read-only access where you're not at risk of bypassing validation or business logic that matters.
- Performance-sensitive bulk operations where an API's request/response overhead genuinely doesn't fit.
The tradeoff: a direct connection bypasses whatever validation, business logic, or workflow rules live in the application layer. It's also brittle — an internal schema is usually not a supported contract, and it can (and will) change without notice across upgrades, especially with vendor-managed systems like SAP Business One, where the supported integration paths are the Service Layer and DI API, not the raw database.
API integration: when it's the right call
- Anything that writes data, especially in a system with business logic you don't want to bypass (order validation, inventory rules, approval workflows).
- Integrations another team, vendor, or customer-facing system depends on long-term. APIs are a much more stable contract to build against than an internal schema.
- Cross-system integrations spanning different vendors, where a database connection either isn't available or isn't supported.
The tradeoff: APIs take more upfront work to design and integrate against, and they're only as good as the API surface the vendor actually provides. Some legacy systems simply don't have one worth using, which pushes you back toward direct access by necessity rather than preference.
A practical way to decide
- Does it write data, or just read it? Writes should almost always go through an API or supported integration layer, not a direct database write.
- Who else depends on this integration, and for how long? A quick internal report can tolerate a brittle connection. A production integration another team or customer relies on cannot.
- Is there a supported API at all? If not, you're choosing between direct access and not integrating — which is its own decision worth making explicitly, not by default.
- What happens when the underlying system is upgraded? A documented API is far more likely to survive a vendor upgrade unchanged than an assumption about table structure.
Neither approach is inherently correct — the mistake is defaulting to whichever one is fastest to build today without considering who's going to depend on it in a year.
TODO: Add any client-approved integration examples that illustrate this decision in practice, once available.