Redefining our SDKs Developer Experience

At Apideck, we are passionate about delivering the best tools to help developers build integrations effortlessly. Today, we’re thrilled to announce the release of our new generation of Apideck Unify SDKs, now powered by Speakeasy. These SDKs mark a significant leap forward in developer experience, reliability, and ease of use.

Why SDKs Matter in the API Ecosystem

SDKs (Software Development Kits) are more than just tools; they are a gateway to seamless integrations. While APIs expose the core functionalities, SDKs simplify the implementation by providing pre-built methods, abstractions, and tools that accelerate development. They bridge the gap between raw API endpoints and developer-friendly code, saving time and reducing errors.

With Unified APIs like ours, which integrate services such as Accounting (e.g., QuickBooks, Xero), HRIS (e.g., Workday, Personio), and CRM (e.g., Salesforce, HubSpot), the need for robust and intuitive SDKs becomes even more critical. Our goal is to help our customers focus on building their products, not wrestling with integration complexities.

Challenges with Previous SDKs

Until now, we relied on an open-source OpenAPI generator to build our SDKs. While it served us well, the maintenance and scalability challenges became apparent as we expanded our platform. Key pain points included:

• High Maintenance Overhead: Over 4k unresolved issues in the open-source generator created friction.
• Non-idiomatic Code: Generated code often lacked the language-specific nuances that developers expect.
• Security Concerns: Open-source dependencies added uncertainties around updates and vulnerabilities.

Why Speakeasy?

After evaluating multiple vendors, including Speakeasy, Fern and Liblab, we selected Speakeasy as our strategic partner. Speakeasy’s philosophy aligns with our mission to deliver an outstanding developer experience. Here’s why we’re excited about this partnership:

Speakeasy provides:

• Type Safety: Fully typed SDKs ensure errors are caught early, boosting developer confidence.
• Human Readability: Intuitive, language-idiomatic code makes SDKs easier to debug and adopt.
• Batteries Included: Features like telemetry, retries, and pagination are built-in.
• Fault Tolerance: Speakeasy’s generator validates OpenAPI specs, ensuring the SDKs are robust.
• Minimal Dependencies: Lightweight SDKs reduce overhead and improve performance.

Key Features of the New Apideck Unify SDKs

1. Improved Method Naming

We’ve reimagined method names to make them more intuitive:

const { crm } = apideck;
const response = await crm.contacts.list({
  limit: 10
});
const contact = await crm.contacts.create({
  contact: { /* contact data */ }
});

Instead of

const { crm } = apideck;
const response = await crm.contactsAll({
  limit: 10
});
const contact = await crm.contactsAdd({
  contact: { /* contact data */ }
});

2. Enhanced HTTP Debugging

Every response now includes a httpMeta object, providing raw HTTP request and response details. This transparency simplifies troubleshooting:

const result = await apideck.crm.contacts.list();
console.log(result.httpMeta.response.status);
console.log(result.httpMeta.response.headers);

3. Streamlined Pagination

Async iterables make handling paginated responses seamless:

To use pagination in the new Typescript SDK for example, you make your SDK calls as usual, but the returned response object will also be an async iterable that can be consumed using the for await...ofsyntax.

import { Apideck } from "@apideck/unify";

const apideck = new Apideck({
  apiKey: process.env["APIDECK_API_KEY"] ?? "",
  consumerId: "<YOUR_CONSUMER_ID>",
  appId: "<YOUR_APP_ID>",
});

async function run() {
  const result = await apideck.accounting.taxRates.list({
    serviceId: "salesforce",
    filter: {
      assets: true,
      equity: true,
      expenses: true,
      liabilities: true,
      revenue: true,
    },
    passThrough: {
      "search": "San Francisco",
    },
    fields: "id,updated_at",
  });

  for await (const page of result) {
    // Handle the page
    console.log(page);
  }
}

run();

4. Sophisticated Error Handling

Language-specific exceptions ensure precise error management:

For example, in our TypeScript SDK:

import { Apideck } from "@apideck/unify";
import {
  BadRequestResponse,
  NotFoundResponse,
  PaymentRequiredResponse,
  SDKValidationError,
  UnauthorizedResponse,
  UnprocessableResponse,
} from "@apideck/unify/models/errors";

const apideck = new Apideck({
  apiKey: process.env["APIDECK_API_KEY"] ?? "",
  consumerId: "<YOUR_CONSUMER_ID>",
  appId: "<YOUR_APP_ID>",
});

async function run() {
  let result;
  try {
    result = await apideck.accounting.taxRates.list({
      serviceId: "salesforce",
      filter: {
        assets: true,
        equity: true,
        expenses: true,
        liabilities: true,
        revenue: true,
      },
      passThrough: {
        "search": "San Francisco",
      },
      fields: "id,updated_at",
    });

    for await (const page of result) {
      // Handle the page
      console.log(page);
    }
  } catch (err) {
    switch (true) {
      // The server response does not match the expected SDK schema
      case (err instanceof SDKValidationError): {
        // Pretty-print will provide a human-readable multi-line error message
        console.error(err.pretty());
        // Raw value may also be inspected
        console.error(err.rawValue);
        return;
      }
      case (err instanceof BadRequestResponse): {
        // Handle err.data$: BadRequestResponseData
        console.error(err);
        return;
      }
      case (err instanceof UnauthorizedResponse): {
        // Handle err.data$: UnauthorizedResponseData
        console.error(err);
        return;
      }
      case (err instanceof PaymentRequiredResponse): {
        // Handle err.data$: PaymentRequiredResponseData
        console.error(err);
        return;
      }
      case (err instanceof NotFoundResponse): {
        // Handle err.data$: NotFoundResponseData
        console.error(err);
        return;
      }
      case (err instanceof UnprocessableResponse): {
        // Handle err.data$: UnprocessableResponseData
        console.error(err);
        return;
      }
      default: {
        // Other errors such as network errors, see HTTPClientErrors for more details
        throw err;
      }
    }
  }
}

run();

5. Retry Support

Requests automatically retry on network failures, with customizable configuration.

For example, in our TypeScript SDK:

import { Apideck } from "@apideck/unify";

const apideck = new Apideck({
  apiKey: process.env["APIDECK_API_KEY"] ?? "",
  consumerId: "<YOUR_CONSUMER_ID>",
  appId: "<YOUR_APP_ID>",
});

async function run() {
  const result = await apideck.accounting.taxRates.list({
    ...
  }, {
    retries: {
      strategy: "backoff",
      backoff: {
        initialInterval: 1,
        maxInterval: 50,
        exponent: 1.1,
        maxElapsedTime: 100,
      },
      retryConnectionErrors: false,
    },
  });

  for await (const page of result) {
    // Handle the page
    console.log(page);
  }
}

run();

6. Custom API Clients

Developers can now use their preferred API clients, integrating seamlessly with hooks for customization:

For example, in our TypeScript SDK:

import { Apideck } from "@apideck/unify";
import { HTTPClient } from "@apideck/unify/lib/http";

const httpClient = new HTTPClient({
  // fetcher takes a function that has the same signature as native `fetch`.
  fetcher: (request) => {
    return fetch(request);
  }
});

httpClient.addHook("beforeRequest", (request) => {
  const nextRequest = new Request(request, {
    signal: request.signal || AbortSignal.timeout(5000)
  });

  nextRequest.headers.set("x-custom-header", "custom value");

  return nextRequest;
});

httpClient.addHook("requestError", (error, request) => {
  console.group("Request Error");
  console.log("Reason:", `${error}`);
  console.log("Endpoint:", `${request.method} ${request.url}`);
  console.groupEnd();
});

const sdk = new Apideck({ httpClient });

7. Self-Documenting SDKs

Language-specific examples and in-SDK documentation significantly streamline the onboarding process for developers by providing clear, tailored guidance in their preferred programming language. These examples eliminate the need to translate generic code snippets, allowing developers to focus on building their applications rather than deciphering SDK usage. By showcasing idiomatic, best-practice implementations, they instill confidence in developers, ensuring a smoother and faster path to achieving their first successful integration.

Moreover, in our developer portal, every operation now includes your favorite code example, making it even easier to understand and implement unify APIs and speed up your integration.

Transition Plan

We are excited to announce the next generation of our SDKs and invite all customers to transition to the new SDKs by May 31, 2025. After this date, legacy SDKs will be officially archived and will no longer receive updates or support.

To ensure a seamless migration process, all current SDKs have been marked as deprecated. We encourage you to begin migrating to the new SDKs today by following our comprehensive Migration Guide. This guide provides step-by-step instructions to help you transition smoothly and unlock the benefits of our updated SDKs.

For more detailed guidance, you can refer to the respective SDK documentation:

• NodeJS SDK: View Documentation
• Python SDK: View Documentation
• PHP SDK: View Documentation
• .Net SDK: View Documentation

If you have any questions or need further assistance, feel free to contact our Support team at support[at]apideck.com. We’re here to help ensure a smooth migration.

Looking Ahead

The new Apideck Unify SDKs represent our commitment to removing friction for developers and delivering a superior integration experience. We’re confident these changes will empower our customers to achieve their goals faster and more efficiently.

Ready to elevate your integration experience? Start exploring the new Apideck Unify SDKs today!