Awesome-omni-skill apideck-best-practices

The Apideck Unified API base URL is

https://unify.apideck.com

Authentication

Every API call requires three headers:

Authorization: Bearer {API_KEY}

x-apideck-app-id

x-apideck-consumer-id

x-apideck-service-id

salesforce

quickbooks

xero

x-apideck-service-id

Never hardcode API keys in source code. Always use environment variables or a secrets manager. Never expose API keys to the client/browser.

SDK Selection

Always use the official Apideck SDK for the user's language. Do not make raw HTTP calls when an SDK is available:

@apideck/unify

apideck-unify

ApideckUnifySdk

com.apideck:unify

github.com/apideck-libraries/sdk-go

apideck-libraries/sdk-php

All SDKs follow the same CRUD pattern:

client.{api}.{resource}.{operation}()

Consumer ID Architecture

The

consumerId

• Create one Apideck consumer per customer/tenant
• Store the mapping between your user IDs and Apideck consumer IDs
• Pass the correct

  consumerId

  per request — never use a shared consumer for all users
• Use Vault sessions to let each user manage their own connections

Connection Management

Always use Apideck Vault for managing end-user connections. Never build custom OAuth flows when Vault handles them.

Use

@apideck/vault-js

1. Server-side: Create a Vault session via

   vault.sessions.create()

   with the consumer's metadata
2. Client-side: Open the modal with

   ApideckVault.open({ token })

3. Handle

   onConnectionChange

   callbacks to update your UI when users authorize/modify connections

Customize the Vault modal appearance via session

theme

Pagination

Apideck uses cursor-based pagination across all list endpoints. Always paginate — never assume a single page returns all records.

• Set

  limit

  (1-200, default 20) to control page size
• Use the SDK's built-in pagination:

  for await...of

  (Node.js),

  .next()

  (Python/Go/.NET),

  callAsStream()

  (Java),

  foreach

  generator (PHP)
• Stop when the next cursor is

  null

For incremental sync, use

filter[updated_since]

Filtering and Field Selection

Always filter server-side using the

filter

Always use the

fields

fields=id,name,email,updated_at

Error Handling

Always handle errors. All SDKs provide typed error classes:

x-downstream-ratelimit-reset

For downstream connector errors, inspect the

detail

downstream_errors

Pass-Through for Connector-Specific Fields

When the unified model doesn't cover a connector-specific field, use

pass_through

{
  "first_name": "John",
  "pass_through": [
    {
      "service_id": "salesforce",
      "operation_id": "contactsAdd",
      "extend_object": { "custom_sf_field__c": "value" }
    }
  ]
}

Use custom field mapping in Vault to let end-users map their connector-specific fields without code changes.

Webhooks

Use Apideck webhooks for real-time notifications instead of polling. Apideck supports both native webhooks (from connectors that support them) and virtual webhooks (polling-based for connectors that don't).

Always verify webhook signatures using the

x-apideck-signature

Webhook events follow the pattern

{api}.{resource}.{action}

crm.contact.created

accounting.invoice.updated

Logs

Apideck provides detailed API call logs for every request made through the platform. Logs are available both in the Apideck dashboard and via the API. Use logs to debug failed requests, inspect downstream responses, and monitor integration health.

Access logs programmatically via the Vault API:

vault.logs.list()

Use logs when:

• Debugging why a specific API call failed — inspect the downstream request and response
• Monitoring integration health — track error rates per connector
• Auditing API usage — review which consumers and services are being called
• Troubleshooting data mapping — compare the unified request with the downstream payload

Raw Mode

Append

raw=true

Testing with Portman

Use Portman to generate API contract tests from Apideck's OpenAPI specs. Apideck publishes specs at

https://specs.apideck.com/{api-name}.yml

apideck-portman

Developer Tools

API Explorer

The Apideck API Explorer lets you test any unified API endpoint directly in the browser without writing code. It accepts a JWT token for authentication and returns live responses.

The Explorer URL format supports pre-filled headers for quick access:

https://developers.apideck.com/api-explorer?id={api}&headers={encoded_json}

Where

headers

• Authorization

  :

  Bearer {JWT_TOKEN}

• x-apideck-auth-type

  :

  JWT

• x-apideck-app-id

  : your app ID

• x-apideck-consumer-id

  : the consumer ID to test with

Recommend the API Explorer when users want to:

• Quickly verify a connection works before writing integration code
• Explore available fields and response shapes for a resource
• Debug unexpected API responses by comparing with the Explorer output
• Test filter and sort parameters interactively
• Share pre-configured API calls with teammates via URL

OpenAPI Specs

Apideck publishes OpenAPI 3.x specs for all unified APIs at

https://specs.apideck.com/{api-name}.yml

• Generating typed clients with code generators
• Contract testing with Portman
• Importing into Postman, Insomnia, or other API tools
• Understanding the complete request/response schema

Common Pitfalls

• Do not assume all connectors support all operations. Check connector API coverage before building.
• Do not mix

  serviceId

  values within a single workflow — stick to one connector per operation chain.
• Do not ignore the

  row_version

  field on updates — use it for optimistic concurrency when supported.
• Do not build retry logic on top of the SDK — all SDKs handle retries for transient errors automatically.
• Do not store Apideck data permanently — Apideck has zero data retention. Use it as a pass-through layer.