--- title: How to Add API Integrations Without Deploying Code Using JSON Blueprints slug: how-to-add-api-integrations-without-deploying-code-using-json-blueprints date: 2026-09-01 author: Yuvraj Muley categories: [Guides, Engineering, Product Updates] excerpt: Learn how to architect a generic execution engine that uses JSON blueprints and JSONata mappings to add SaaS API integrations without code deployments. tldr: "By replacing hardcoded API adapters with declarative JSON blueprints and JSONata mappings, engineering teams can ship and update integrations as database operations, eliminating CI/CD bottlenecks." canonical: https://truto.one/blog/how-to-add-api-integrations-without-deploying-code-using-json-blueprints/ --- # How to Add API Integrations Without Deploying Code Using JSON Blueprints If your engineering team is maintaining a directory full of `hubspot-adapter.ts` and `salesforce-adapter.ts` files, you are trapped in a deployment bottleneck. Every time a vendor deprecates an endpoint, changes a pagination strategy, or introduces a new OAuth scope, your team has to write custom logic, open a pull request, wait for CI/CD, and push a deployment. If you want to [add new API integrations without deploying code](https://truto.one/hot-swappable-api-integrations-add-connectors-without-code-deploys/), the answer is to stop treating integrations as compiled adapters and start treating them as **JSON connector blueprints** paired with **declarative mappings**. By moving integration logic—authentication, routing, pagination, and field mapping—out of runtime code and into a database, you can add and update connectors instantly. Every API's base URL, auth scheme, endpoints, pagination style, and field translations lives as configuration data. A single generic runtime reads that data and executes the request. Adding a new connector becomes an insert statement, not a pull request. This comprehensive guide breaks down the architectural shift required to scale B2B SaaS integrations, the exact JSON blueprint schema, deep-dive JSONata mapping examples for both queries and responses, how per-customer overrides work without forking anything, and how the same blueprint can auto-generate Model Context Protocol (MCP) tool definitions for AI agents. If you are dreading your next vendor migration, this is your escape hatch. ## The Deployment Bottleneck: Why Code-First Integrations Fail at Scale Building integrations in-house usually starts with a logical approach: you write a dedicated API client for each provider. An engineer writes a `HubSpotAdapter` class to handle HubSpot's nested `properties` objects and `filterGroups` search syntax. Another engineer writes a `SalesforceAdapter` class to handle Salesforce's SOQL queries and PascalCase field names. Somewhere in a router, you will find a massive switch statement: `if (provider === 'hubspot')`. This is the [**Strategy Pattern** applied to API integrations](https://truto.one/zero-integration-specific-code-how-to-ship-new-api-connectors-as-data-only-operations/). It works fine for three integrations. It becomes a crushing source of technical debt at thirty. That model buckles under two pressures that are only getting worse in the modern SaaS ecosystem. First, the surface area is exploding. In 2025, 82% of organizations surveyed described themselves as API-first to at least some degree, up from 74% in 2024 and 66% in 2023. Every enterprise buyer expects your product to speak to their entire stack on day one. Second, upstream APIs move faster than your release train. Over 63% of teams ship APIs in less than a week, which means the vendors you integrate with are pushing breaking changes at a cadence your quarterly roadmap cannot absorb. When a HubSpot property name changes or Salesforce deprecates an endpoint, your customers do not care that your fix is stuck behind a code review. Industry estimates from API tooling vendors put the cost of a typical custom API build between $10,000 and $50,000 depending on complexity, authentication schemes, and edge case handling. The ongoing annual upkeep sits at 15% to 20% of the initial build cost. This hidden [integration maintenance tax](https://truto.one/how-to-build-a-custom-saas-api-connector-without-code-tutorial/) of code-first integrations shows up in four distinct ways: - **CI/CD lag:** Even a one-line field rename requires PR review, build, test, staging, canary, and rollout. - **Combinatorial testing:** A change to shared pagination logic can silently break any of the dozens of adapters that depend on it. - **Per-customer fragility:** One enterprise wants `account_owner_email` mapped from a custom Salesforce field. You fork the adapter or bolt on feature flags. Both age badly. - **AI agent doubling:** Every REST adapter now needs an equivalent MCP tool server. You are effectively writing every integration twice. The fix is architectural, not tactical. You need to get integration-specific logic out of your runtime entirely. A sensible MVP for extensible platforms is a narrow set of declarative HTTP integrations with strict schemas. Allowing general-purpose custom code for integrations introduces security risks, creates maintenance nightmares, and blocks your product roadmap. ## What is a JSON Connector Blueprint? **A JSON connector blueprint is a declarative configuration document that fully describes how to communicate with a third-party API—including its base URL, authentication scheme, available endpoints, and pagination strategy—without containing any executable code.** Think of it as a machine-readable contract that a generic runtime can execute against any REST or GraphQL provider. A good blueprint captures everything a hand-written adapter would encode: - **Base URL and default headers** for the provider. - **Credential shape** (OAuth2, API key, Basic, custom header) and how those credentials become HTTP auth. - **Resources and methods** with paths, HTTP verbs, query schemas, body schemas, and response paths. - **Pagination strategy** (cursor, page, offset, link header, range, or a JSONata expression). - **Rate limit signaling** (which headers to read, how to normalize them). - **Error extraction** for turning provider-specific error bodies into normalized shapes. Here is an example of what a robust JSON connector blueprint looks like for a CRM integration: ```json { "base_url": "https://api.example-crm.com", "credentials": { "format": "oauth2", "config": { "client_id": "{{context.client_id}}", "client_secret": "{{context.client_secret}}" } }, "authorization": { "format": "bearer", "config": { "path": "oauth.token.access_token" } }, "pagination": { "format": "cursor", "config": { "cursor_field": "paging.next.after", "query_param": "after" } }, "resources": { "contacts": { "list": { "method": "get", "path": "/crm/v3/objects/contacts", "response_path": "results" }, "get": { "method": "get", "path": "/crm/v3/objects/contacts/{{id}}" }, "create": { "method": "post", "path": "/crm/v3/objects/contacts" } } } } ``` Notice what is missing: there is no `fetch()` call, no conditional logic, and no error handling code. That one document is enough for a generic HTTP client to authenticate, paginate, and route CRUD operations. It never gets compiled. There is no `ExampleCrmAdapter` class. Adding a second CRM means inserting a second blueprint with a different `base_url` and different `resources`. > [!NOTE] > This pattern is an instance of the **Interpreter Pattern** applied at platform scale. The blueprint plus mapping expressions form a small domain-specific language (DSL) for API interactions. Your runtime is the interpreter. New integrations are new programs in the DSL, not new features in the interpreter. The security posture also improves dramatically. Restricting integration authors to a well-defined declarative schema (instead of arbitrary Node.js or Python) contains the blast radius, prevents accidental privilege escalation, and makes the entire integration surface auditable. ## How to Add New API Integrations Without Deploying Code Using JSON Connector Blueprints and Mappings To make JSON blueprints work, your architecture needs a **generic execution engine**. Instead of routing a request to a provider-specific handler, every request flows through the exact same code path. The engine reads the configuration data and executes it. Here is the execution pipeline that makes this work. Every step is provider-agnostic. The runtime never asks "which integration is this?" ```mermaid flowchart TB A["Unified API request
GET /crm/contacts"] --> B["Resolve connected account
(credentials + overrides)"] B --> C["Load JSON blueprint
for integration"] C --> D["Load JSONata mappings
for resource + method"] D --> E["Transform unified query
into provider query"] E --> F["Build URL, auth, pagination
from blueprint"] F --> G["Execute HTTP request"] G --> H["Extract results using
response_path"] H --> I["Apply JSONata response mapping"] I --> J["Return unified response"] ``` The steps that matter architecturally: **Step 1: Resolve configuration, not code.** When a request hits your unified API endpoint (e.g., `GET /unified/crm/contacts?account_id=123`), a middleware pulls three records from the database: the connected account (credentials in a generic context column), the integration blueprint, and the resource-method mapping. None of these lookups branch on provider name. **Step 2: Extract and translate mapping expressions.** The engine extracts the declarative mapping expressions. The unified query params (like `limit`, `updated_after`, `email_addresses.email`) get run through a JSONata `query_mapping` expression that produces the provider's native shape—`filterGroups` for one API, a SOQL `WHERE` clause for another. The mapper does not know or care which. **Step 3: Transform and build the HTTP request.** The proxy layer constructs the HTTP request using the JSON blueprint. The URL is `base_url` + `path` with `{{id}}` placeholders resolved from the request. Authorization headers are constructed from the credential path defined in the blueprint. Pagination is applied based on the declared strategy. **Step 4: Execute the call and extract results.** The engine executes the fetch. When the third-party API returns a payload, the engine extracts the relevant data using the `response_path` defined in the blueprint (e.g., `response_path: "results"`). It does not need a custom parser. **Step 5: Transform the response.** Finally, a JSONata `response_mapping` expression evaluates against each item to turn the provider payload into your unified schema. The original payload is preserved under a `remote_data` key for callers that need raw access. This pipeline handles 100 different APIs using the exact same runtime logic. Adding the 101st API is a five-minute database operation: write the blueprint, write the mapping expressions, insert both into the database. No pull requests. No waiting for the next release cycle. ## Data Transformation as Data: Using JSONata for API Mapping Handling authentication and routing via JSON is straightforward. The hard part of API integration is schema normalization. Every SaaS vendor structures their data differently. Field mapping is where hand-coded adapters get ugly fastest. Every provider has a different naming convention, different nesting depth, and different ways of encoding lists, addresses, and custom fields. Writing this as imperative TypeScript produces hundreds of lines per resource. To decouple transformation logic from your codebase, you need a functional query language that can be stored as a string in a database. **JSONata** is the industry standard for this task. It is a declarative, side-effect-free query and transformation language for JSON. It supports conditionals, string manipulation, array transforms, aggregations, custom functions, and recursion—all inside a single expression string that lives in a database column. Let's look at how JSONata handles the massive differences between HubSpot and Salesforce using the same unified schema (for more deep dives, see our [guide to publishing JSONata manifests and mapping examples](https://truto.one/how-to-publish-jsonata-manifests-and-mapping-examples-for-api-integrations/)). ### Example 1: HubSpot Response Mapping HubSpot stores custom fields and standard fields inside a nested `properties` object. To map this to a unified CRM schema, you use a JSONata expression stored in your database: ```jsonata response.{ "id": id.$string(), "first_name": properties.firstname, "last_name": properties.lastname, "title": properties.jobtitle, "email_addresses": [ properties.email ? { "email": properties.email, "is_primary": true }, properties.hs_additional_emails ? properties.hs_additional_emails.$split(";").{ "email": $ } ], "phone_numbers": [ properties.phone ? { "number": properties.phone, "type": "phone" }, properties.mobilephone ? { "number": properties.mobilephone, "type": "mobile" } ], "created_at": createdAt, "updated_at": updatedAt, "custom_fields": properties.$sift(function($v, $k) { $not($k in ["firstname", "lastname", "jobtitle", "email", "phone"]) }) } ``` This expression extracts the standard fields, splits secondary emails into an array, and dynamically sifts the remaining keys into a `custom_fields` object. ### Example 2: Salesforce Query Mapping Salesforce is entirely different. It uses flat PascalCase fields and requires SOQL for complex filtering. Instead of writing a `SalesforceQueryBuilder` class in Node.js, you define a JSONata expression that constructs the SOQL query from a unified request: ```jsonata ( $whereClause := query ? $convertQueryToSql( query.{ "email_addresses": email_addresses ? $firstNonEmpty(email_addresses.email, email_addresses), "name": $firstNonEmpty(name, first_name, last_name) ? { "LIKE": "%" & $firstNonEmpty(name, ...) & "%" }, }, ["email_addresses", "name"], { "email_addresses": "Email", "name": "Name", } ); { "q": query.search_term ? "FIND {" & query.search_term & "} RETURNING Contact(Id, FirstName, LastName)", "where": $whereClause ? "WHERE " & $whereClause, } ) ``` ### Example 3: Salesforce Response Mapping When Salesforce returns that flat, PascalCase payload, you use another JSONata expression to map it back to the exact same unified output shape as HubSpot: ```jsonata response.{ "id": Id, "first_name": FirstName, "last_name": LastName, "title": Title, "account": { "id": AccountId }, "email_addresses": [{ "email": Email }], "phone_numbers": $filter([ { "number": Phone, "type": "phone" }, { "number": MobilePhone, "type": "mobile" }, { "number": HomePhone, "type": "home" } ], function($v) { $v.number }), "created_at": CreatedDate, "updated_at": LastModifiedDate, "custom_fields": $sift($, function($v, $k) { $k ~> /__c$/i }) } ``` Same unified output shape. Two completely different upstream payloads. Zero if-statements in your runtime. The custom-field logic—one API uses a suffix convention (`__c`), the other uses "anything not in the default list"—is expressed declaratively rather than buried in an adapter method. By storing these expressions as data, you empower product managers or implementation engineers to fix mapping bugs in production instantly. If a vendor adds a new required field, you update the JSONata string in your database. No pull requests. No waiting. A few things JSONata gets right for this use case: - **Storable as a string.** An expression is just text in a database column. It can be versioned, diffed, and hot-swapped without a restart. - **Pure functions.** No side effects means expressions are safe to evaluate on untrusted mapping data. - **Composable.** Complex logic (address normalization, phone type inference, custom-field extraction) fits in a single expression instead of five utility files. ## Handling Edge Cases: Custom Fields, Overrides, and Rate Limits The real world of B2B SaaS integrations is messy. Enterprise customers have highly customized Salesforce instances, and upstream APIs have aggressive rate limits. A zero-code architecture must handle these realities without forcing you back into writing custom code. ### The 3-Level Override Hierarchy for Custom Fields One of the biggest failures of early unified API platforms was their rigidity. If an enterprise customer needed to map a custom Salesforce field (`Industry_Vertical__c`) to your unified schema, you had to fork the integration code or build a complex UI. If your architecture cannot absorb this without forking, you have just rebuilt the code-first problem in YAML. When your mappings are just JSONata strings, you can implement a 3-level override hierarchy that is deep-merged at request time: | Level | Scope | What it controls | |-------|-------|-----------------| | **Platform base** | All environments, all accounts | Default mapping for the integration | | **Environment override** | One customer's environment | Tenant-wide changes (extra fields, custom endpoints) | | **Account override** | One connected account | Per-instance quirks (custom fields, alternate objects) | Each level can override any part of the mapping: `response_mapping`, `query_mapping`, `request_body_mapping`, the resolved `resource`, the HTTP `method`, and pre/post request steps. The generic runtime merges them at request time. A concrete example: one Salesforce customer stores their sales rep email in a custom `Owner_Email__c` field. Instead of forking the mapping, you add an account-level override that extends the `response_mapping` with one line attached to their specific account record in the database: ```jsonata { "owner_email": Owner_Email__c } ``` At runtime, the generic execution engine deep-merges these configurations. The core engine remains untouched, and other customers are unaffected. No deploy. No branch. No coordination with the integrations team. ### Radical Honesty on Rate Limits Many integration platforms claim to "handle" rate limits automatically by absorbing them, implementing massive backoff queues, and hiding the reality of the upstream API from you. This is an architectural anti-pattern. If you are building a real-time sync and the upstream API returns an HTTP 429 (Too Many Requests), hiding that error behind a silent retry queue leads to stale data, amplified duplicate writes, broken idempotency, and impossible-to-debug race conditions. Truto takes a brutally honest approach: the platform does not automatically retry, throttle, or apply backoff on rate limit errors. When an upstream API returns an HTTP 429, Truto passes that exact error back to the caller. However, because every API formats rate limit headers differently, Truto's generic engine normalizes the upstream rate limit information into standardized IETF headers before passing it to you: - `ratelimit-limit`: The maximum number of requests permitted. - `ratelimit-remaining`: The number of requests remaining in the current window. - `ratelimit-reset`: The time at which the rate limit window resets. This architectural choice leaves the retry and backoff strategy exactly where it belongs: in the hands of the consuming application, which understands the business context of the failed request—whether this is a user-facing request that should fail fast, a background sync that can back off, or a bulk import that should pause. ## Bonus: Auto-Generating MCP Tools from JSON Blueprints Shifting your integrations from code to data unlocks a massive architectural advantage for the AI era. Gartner predicts that 40% of enterprise applications will be integrated with task-specific AI agents by the end of 2026. The Model Context Protocol (MCP) has become the default contract between AI agents and APIs, with the public registry expanding to over 9,400 servers and SDKs reaching 97 million monthly downloads in early 2026. Furthermore, 51% of organizations have already deployed AI agents, with another 35% planning to do so within two years. If you build integrations using custom TypeScript adapters, you have to write entirely new MCP tool servers to expose those integrations to AI agents. You are building everything twice. Shipping every integration twice (once for humans, once for agents) is not a sustainable engineering budget. When your integrations are defined as JSON blueprints, you get MCP tools for free. Because the blueprint explicitly defines the `resources`, `methods`, `query_schema`, and `body_schema`, the platform can programmatically translate the JSON configuration into an MCP tool definition directly from it—no separate agent-facing codebase. ```mermaid flowchart LR A["JSON Blueprint"] --> B["Generic Runtime"] A --> C["MCP Tool Generator"] C --> D["Tool: crm_contacts_list"] C --> E["Tool: crm_contacts_create"] C --> F["Tool: crm_deals_search"] D --> B E --> B F --> B B --> G["Upstream API"] ``` Each resource-method pair maps to an MCP tool. The tool name becomes something like `crm_contacts_list`. The platform dynamically outputs schemas like this: ```json { "name": "crm_contacts_list", "description": "List contacts from CRM", "inputSchema": { "type": "object", "properties": { "limit": { "type": "integer" }, "search_term": { "type": "string" } } } } ``` Every time you add a new integration via a JSON blueprint, it instantly becomes available as a REST API, a GraphQL endpoint, and an MCP tool for AI agents. The tool's execution is the same generic pipeline that handles REST calls—the agent hits an MCP endpoint, the platform routes the invocation to the exact same runtime, and the response comes back as a normalized unified object. ## Trade-offs Worth Acknowledging Declarative integrations are not a free lunch. Being direct about the trade-offs: - **JSONata has a learning curve.** Engineers used to imperative JavaScript need a week or two to become fluent. The payoff is real, but the ramp is not zero. - **Debugging shifts from stack traces to expression evaluation.** You need good tooling to inspect what an expression evaluated to at a given step. Without a proper mapping playground, this can be frustrating. - **Truly bizarre APIs still exist.** Some vendors ship APIs so hostile (mid-response state changes, undocumented required headers, per-tenant path schemes) that even a declarative engine benefits from a small escape hatch such as pre/post request steps or a proxy-mode passthrough. - **Governance matters more.** When mappings are data, anyone with write access can change production behavior. You need review workflows, versioning, and audit logs on the mapping tables themselves. The honest framing: declarative blueprints reduce the maintenance burden by an order of magnitude, they do not eliminate it. What they eliminate is the deploy step for 95% of changes. ## The Architectural Shift and What to Do Next The era of writing and maintaining dozens of bespoke API clients is over. Hardcoded integrations are too expensive to build, too brittle to maintain, and too slow to deploy when upstream providers make changes. If you take one thing from this piece: **the number of integrations you can support scales with the expressiveness of your configuration schema, not with the size of your engineering team.** Code-first architectures grow linearly with adapters. Configuration-first architectures grow linearly with unique API patterns, and there are far fewer of those than there are integrations. A practical migration path for teams stuck maintaining bespoke adapters: 1. **Audit your current adapters.** Identify the common patterns—REST + OAuth2 + cursor pagination probably covers 70% of them. 2. **Design your blueprint schema.** Nail down how you will express auth, pagination, resources, and error extraction as JSON. 3. **Build the generic runtime once.** One HTTP client, one paginator, one auth applier, one JSONata evaluator. 4. **Migrate the easiest integration first.** Prove the pattern on a well-behaved provider before tackling the hostile ones. 5. **Introduce the override hierarchy.** Even if you have one customer today, design for per-tenant overrides from day one. Retrofitting is painful. 6. **Generate your MCP surface from the same blueprints.** Do not build an agent-facing integration layer separately. By adopting an architecture built on JSON connector blueprints and JSONata mappings, you transform API integration from a software engineering bottleneck into a scalable data operation. You can fix mapping bugs in production instantly, support per-customer custom fields without forking code, and automatically generate tools for AI agents. Stop writing `if (provider === 'hubspot')` and start treating your integrations as data. > If you're rearchitecting your integration layer or evaluating whether a declarative approach fits your product, we'd be happy to walk through the schema design, JSONata patterns, and override model that scales to 100+ integrations without a single provider-specific code path. > > [Talk to us](https://cal.com/truto/partner-with-truto)