> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.itential.com/itential-platform/2023-2/best-practices/adapters-vs-integrations/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server. # Adapters vs. integrations > Understand the differences between adapters and integrations and choose the right approach for your use case. Itential Platform offers two ways to connect to external systems: adapters and integrations. Both can make API calls to third-party systems, but they differ significantly in how they are built, deployed, and maintained. This guide explains those differences to help you choose the right approach. ## Quick comparison | | Adapters | Integrations | | --------------- | ---------------------------------------------------- | ----------------------------------------------- | | Build method | Code-driven (Node.js) | Model-driven (OpenAPI/Swagger) | | Deployment | Installed on the file system of each Platform server | Stored in MongoDB; no file system installation | | Server restart | Required on initial deployment | Not required | | Customization | Full — modify or extend API calls in code | Limited to the OpenAPI/Swagger specification | | Memory | \~130 MB per instance, even when idle | No resource usage when idle; scales on demand | | CPU | Single process | Multi-process; scales on demand | | Protocols | REST, SOAP, gRPC | REST, SOAP | | Authentication | Basic, OAuth, static tokens, and others | Basic, OAuth, API Key (including AWS) | | SSL | Supported, including self-signed certificates | Supported for publicly-signed certificates only | | Version control | Update code and restart | Create and manage multiple versions via UI | | Migration | Requires reinstall on each server | Portable; no reinstall required | | Health checks | Yes — configurable as startup or intermediate | No | | Logs | Yes — info, warn, debug, trace, error | Yes — info, warn, debug, trace, error | ## When to use each **Use an adapter when:** * Your integration requires gRPC or a non-HTTP protocol * You need to add custom logic or transform API responses * You are working with a self-signed SSL certificate * You need health check monitoring against the external system * You are running on-premise with no resource constraints **Use an integration when:** * An OpenAPI 3.0 or Swagger 2.0 specification is available for the target system * No customization beyond the spec is required * You are deploying on cloud infrastructure where memory and CPU are constrained * You want deployment without a server restart or file system access * You need to run multiple versions of the same integration concurrently ## Building adapters and integrations ### Adapters Adapters are code-driven Node.js packages. Over 200 open-source adapters are available. To build a new adapter, use [Adapter Builder](https://adapters.itential.io/), which generates a Node.js adapter from an OpenAPI 3.0 or Swagger 2.0 document. The generated code can be modified to suit your requirements. ### Integrations Integrations are model-driven. To build an integration, upload an OpenAPI 3.0 or Swagger 2.0 document via the Platform UI. Platform validates the document and creates an Integration Model stored in a MongoDB collection. No code is generated or placed on the file system. ## Deploy adapters and integrations ### Adapters To deploy an adapter, copy the adapter code onto the Platform server file system, run `npm install`, then restart Platform. In a multi-server environment, repeat this process on each server — or copy the installed adapter directory and restart. Open-source adapters are pre-installed in Itential cloud infrastructure. See [adapters overview](/adapters/introduction/overview) for more information. ### Integrations Integration deployment is UI-based—no file system access or restart is required. In a multi-server environment, all Platform servers sync automatically when an integration is deployed. See [integrations overview](/admin-essentials/integrations/overview) for more information. ## Customization Adapters can be customized at the code level. You can modify existing API calls, add new calls, and transform responses. For example, if an API call returns a large nested object, you can customize the adapter to return only the value at `status.result.data` rather than the full response. Integrations are limited to the operations defined in the uploaded OpenAPI or Swagger specification. Response payloads cannot be transformed — your workflow receives the full response from the external system. ## Resource usage Adapter instances each hold a process ID (PID) and consume approximately 130 MB of memory even when idle. Each adapter instance runs as a single process. Integrations consume no system resources when idle and scale across multiple processes on demand. This makes integrations better suited for cloud environments where memory and CPU are constrained or metered. ## Authentication Adapters support a wide range of authentication mechanisms including Basic, OAuth, static tokens, and other methods that do not require manual intervention. Adapters can also authenticate against different endpoints for different calls. Integrations support API Key (including AWS Signature), HTTP Basic, and OAuth 2.0. OpenID Connect is not currently supported for integrations. ## SSL and certificates Adapters support SSL for all certificate types, including self-signed certificates. Integrations support SSL for publicly-signed certificates only. To use a self-signed certificate with an integration, you must manually add the certificate to the Platform key store. ## Version control When a new adapter version is available, pull the updated code, reinstall the node modules, and restart the adapter. Integrations support multiple concurrent versions. Each version can have multiple independent instances. Switching to a new integration version requires updating the workflows that reference it. ## Health checks Adapters support configurable health checks, which run as timed polls against the external system. Health checks can be configured as startup checks (run when the adapter starts) or intermediate checks (run at a configured interval). Health check calls do not count against rate limits or active call totals. Integrations do not support health checks. The availability of an external system cannot be checked through an integration. ## Logging Both adapters and integrations support log levels: `info`, `warn`, `debug`, `trace`, and `error`. Use `warn` or `info` in non-production environments and `error` in production to limit log volume. `debug` and `trace` are useful for troubleshooting but generate significant log output and should not be left enabled in production. > Understand the differences between adapters and integrations and choose the right approach for your use case.