.do SDK vs. Direct API Calls: Which Should You Choose?

Integrating external platforms into your applications can significantly boost functionality and efficiency. When working with the powerful .do platform for workflow automation, agentic AI, and business-as-code solutions, you'll face a common choice: use the official .do Software Development Kit (SDK) or interact directly with the .do API?

While both approaches allow you to connect with the .do platform, they offer distinct advantages and disadvantages. Understanding these differences is crucial for making the best decision for your project.

What is the .do SDK?

The .do SDK is a pre-built library designed to simplify interaction with the .do platform's API. It provides a set of functions and methods that abstract away the complexities of making raw HTTP requests, handling authentication, and managing data formats. Think of it as a developer-friendly wrapper around the underlying API.

Example using the .do SDK (TypeScript):

import { DoSDK } from '@do/sdk';

const sdk = new DoSDK({
  apiKey: 'YOUR_API_KEY', // Securely manage your API key!
});

async function listAgents() {
  try {
    const agents = await sdk.agents.list(); // Simple method call
    console.log('Available Agents:', agents);
  } catch (error) {
    console.error('Error listing agents:', error);
  }
}

listAgents();

This example demonstrates how the SDK simplifies fetching a list of available agents with a single, clear method call.

What are Direct API Calls?

Direct API calls involve making raw HTTP requests (GET, POST, PUT, DELETE, etc.) to the .do platform's API endpoints using standard libraries available in your programming language (like fetch in JavaScript, requests in Python, or HttpClient in C#). This approach requires you to build the request URLs, headers (including authentication), and request bodies yourself.

Conceptual Example of a Direct API Call (JavaScript):

async function listAgentsDirect() {
  const apiKey = 'YOUR_API_KEY'; // Securely manage your API key!
  const apiUrl = 'https://api.do.platform/v1/agents'; // Example API endpoint

  try {
    const response = await fetch(apiUrl, {
      method: 'GET',
      headers: {
        'Authorization': `Bearer ${apiKey}`, // Handling authentication
        'Content-Type': 'application/json',
      },
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const agents = await response.json();
    console.log('Available Agents:', agents);
  } catch (error) {
    console.error('Error listing agents:', error);
  }
}

listAgentsDirect();

This example shows the manual effort involved in constructing the request, including handling authentication headers and parsing the response.

.do SDK vs Direct API Calls: A Feature-by-Feature Comparison

Let's break down the pros and cons of each approach across key areas:

When to Choose the .do SDK

The .do SDK is generally the recommended approach for most use cases due to its significant advantages in ease of use, development speed, and maintainability. Choose the SDK when:

• You prioritize rapid development: Get your integrations up and running quickly.
• You value code clarity and readability: The SDK's methods are more semantic and easier to understand.
• You want to reduce boilerplate code: Avoid writing repetitive code for requests and responses.
• You need robust error handling: Leverage the SDK's built-in error management.
• You prefer abstraction: Focus on the business logic of your application rather than low-level API details.
• You want to ensure compatibility with future API updates: The SDK team maintains compatibility with the latest API changes.

Develop with Ease Leveraging the SDK allows you to focus on building powerful solutions on top of the .do platform without getting bogged down in the intricacies of API communication.

When to Choose Direct API Calls

While the SDK is often preferred, there are situations where direct API calls might be necessary or advantageous:

• You need to access cutting-edge or undocumented features: If the API has new endpoints or features not yet covered by the SDK.
• You have very specific performance requirements: In highly performance-sensitive scenarios, you might have fine-grained control over the request structure.
• You are working in a language not officially supported by the SDK: Although the underlying API is accessible from any language, an official SDK provides the best developer experience.
• You have minimal dependencies: In environments where adding external libraries is restricted.
• You require complete control over every aspect of the API interaction: For deep customization or specific edge cases.

Conclusion

For most developers integrating with the .do platform, the official .do SDK offers a significantly smoother and more efficient development experience. Its abstraction, ease of use, and built-in features like authentication handling and structured error reporting lead to faster development, more maintainable code, and a reduced likelihood of errors.

Direct API calls provide maximum flexibility and control but come with the cost of increased complexity, more boilerplate code, and a higher maintenance overhead.

Unless you have a compelling reason to interact directly with the API (such as needing access to features not yet included in the SDK), start with the .do SDK. It's designed to empower you to build custom solutions, automate workflows, and connect your services with the .do platform with unparalleled ease.

Ready to get started?

• What is the .do SDK? The .do SDK allows developers to programmatically interact with the .do platform, enabling them to build custom applications, automate workflows, and integrate with existing services.
• How do I get started with the .do SDK? You can install the .do SDK via npm or yarn package managers. Detailed installation instructions and documentation are available on our developer portal.
• What programming languages does the .do SDK support? The .do SDK is designed to be used with a variety of programming languages. We primarily provide examples and support for TypeScript/JavaScript, but the underlying API can be accessed from any language capable of making HTTP requests.