From cURL to SDK Examples

In this tutorial, you will learn about From cURL to SDK Examples. We cover key concepts, practical examples, and best practices to help you master this topic.

Teach developers to translate cURL API examples into SDK code in their preferred language by showing paired cURL and SDK examples side by side, demonstrating how HTTP methods, headers, parameters, and request bodies map to idiomatic SDK method calls.

What You'll Learn

How to write paired cURL and SDK examples, how to map HTTP concepts to SDK method calls, how to show authentication differences between raw HTTP and SDK usage, and how to help developers transition from testing with cURL to building production integrations with SDKs.

Why It Matters

cURL is the universal language of API documentation. Every developer can read and run a cURL command. But developers build production integrations using SDKs in their language of choice. Showing both helps developers understand the mapping between raw HTTP and idiomatic SDK code.

Real-World Use

The DodaTech API documentation shows every endpoint in cURL first, then in Python and JavaScript SDK examples. Developers often start with cURL to test the API manually, then switch to SDK code for their production integration. The paired examples make this transition seamless.

The cURL to SDK Mapping

flowchart TD
  A[cURL Command] --> B[HTTP Method]
  A --> C[URL]
  A --> D[Headers]
  A --> E[Request Body]
  B --> F[SDK Method Name]
  C --> G[SDK Endpoint Path]
  D --> H[SDK Authentication]
  E --> I[SDK Parameters]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Mapping cURL to SDK

Show the same API call in cURL and in the SDK.

# cURL: compress a file
curl -X POST https://api.dodatech.com/v2/files/compress \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_url": "https://example.com/report.pdf",
    "format": "zip",
    "level": 6
  }'

# Python SDK: same operation
from dodatech import Client

client = Client(api_key="YOUR_API_KEY")
result = client.files.compress(
    file_url="https://example.com/report.pdf",
    format="zip",
    level=6
)
print(result.job_id)

// JavaScript SDK: same operation
const client = new Client({apiKey: "YOUR_API_KEY"});
const result = await client.files.compress({
  fileUrl: "https://example.com/report.pdf",
  format: "zip",
  level: 6,
});
console.log(result.jobId);

Explanation of the Mapping

Explain how each part of the cURL command maps to the SDK code.

## How the Mapping Works

| cURL Component | SDK Equivalent |
|----------------|----------------|
| `-X POST` | Method call: `client.files.compress()` |
| `https://api.dodatech.com/v2/files/compress` | SDK handles the base URL. The method name determines the endpoint |
| `-H "Authorization: Bearer ..."` | SDK reads the API key from the client constructor |
| `-H "Content-Type: application/json"` | SDK automatically sets Content-Type for JSON payloads |
| `-d '{"file_url": "...", "format": "zip"}'` | Method parameters: `file_url="...", format="zip"` |

## From cURL Testing to Production SDK

Show the progression from quick testing to production code.

```bash
# Step 1: Test with cURL (quick, no setup needed)
curl https://api.dodatech.com/v2/files \
  -H "Authorization: Bearer YOUR_KEY"

# Step 2: Simple Python script (adds error handling)
import os
import requests

api_key = os.environ["DODATECH_API_KEY"]
response = requests.get(
    "https://api.dodatech.com/v2/files",
    headers={"Authorization": f"Bearer {api_key}"}
)

if response.status_code == 200:
    print(response.json())
else:
    print(f"Error: {response.status_code} - {response.text}")

# Step 3: Production code with SDK (proper error handling + retry)
from dodatech import Client
from dodatech.exceptions import RateLimitError

client = Client(api_key=os.environ["DODATECH_API_KEY"])

def list_files_with_retry(max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.files.list(per_page=50)
        except RateLimitError:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)

Handling Authentication in Both

Show the authentication mapping clearly.

# cURL: Authentication goes in the header
curl -H "Authorization: Bearer YOUR_KEY" https://api.dodatech.com/v2/files

# Python SDK: Authentication goes in the client constructor
client = Client(api_key="YOUR_KEY")
# All subsequent requests automatically include the auth header

// JavaScript SDK: Authentication in configuration
const client = new Client({apiKey: "YOUR_KEY"});

Common Mistakes

1. Showing cURL Without SDK

Showing only cURL examples forces developers who do not use cURL to translate manually. Always include at least one SDK example.

2. Inconsistent Data Between cURL and SDK

Using different values in cURL and SDK examples for the same operation. Keep all data consistent across examples.

3. No Explanation of the Mapping

Showing cURL and SDK code side by side without explaining how they relate. Some developers may not see the connection.

4. Missing SDK Initialization

Showing SDK method calls without showing client initialization. Developers cannot use the example as-is.

5. Assuming cURL Knowledge

Using advanced cURL features like --data-binary without explanation. Keep cURL examples simple and readable.

6. Not Showing Error Handling Differences

cURL shows raw error responses. SDKs typically raise exceptions. Document this difference so developers know what to expect.

7. Ignoring SDK-Specific Features

SDKs often provide features like automatic retry and pagination that cURL does not. Highlight these SDK advantages in the documentation.

Practice Questions

1. Why show both cURL and SDK examples for each endpoint?

cURL is universal and shows the raw HTTP request. SDK examples show idiomatic code for the developer's language. Both are needed: cURL for testing and understanding, SDK for production integration.

2. How does authentication differ between cURL and SDK usage?

In cURL, authentication goes in the request header. In the SDK, it goes in the client constructor and the SDK manages the header automatically for every request.

3. What is the benefit of using SDK over raw cURL?

SDKs handle authentication, retry logic, error handling, Serialization, and pagination automatically. They provide type-safe, idiomatic code with autocomplete support in IDEs.

4. What should stay consistent between cURL and SDK examples?

Request data values, endpoint path, authentication method, and expected response. Only the syntax should differ between languages.

5. Challenge: Write three versions of the same API operation: cURL, Python SDK, and JavaScript SDK. Explain how each part of the cURL command maps to the SDK equivalents.

FAQ

Mini Project: cURL to SDK Translation Guide

Pick three API endpoints from different categories (list, create, async operation). Write each endpoint as a cURL command and as SDK examples in Python and JavaScript. Create a mapping table showing how each cURL component translates to SDK code. Include progression from simple cURL testing to production SDK code.

What's Next

Translate HTTP concepts to SDK code. Now learn to organize endpoints logically with Organizing Endpoints. Then explore Writing Changelogs.