Scrolls
7 min read
On this page

SDKs & Developer Experience

An SDK wraps your API in language-native code. Instead of constructing HTTP requests, parsing JSON responses, and handling errors manually, developers call functions and work with typed objects. The SDK handles the HTTP layer, authentication, retries, and error parsing.

The developer experience is the product. The API itself is infrastructure. What developers interact with — the SDK, the documentation, the sandbox, the error messages — determines whether they adopt your platform or choose a competitor.

Why SDKs Matter

Compare making an API call with and without an SDK:

Without an SDK:

import requests

response = requests.post(
    "https://api.example.com/v1/charges",
    headers={
        "Authorization": "Bearer sk_live_abc123",
        "Content-Type": "application/json",
        "Idempotency-Key": "unique_key_123"
    },
    json={
        "amount": 2000,
        "currency": "usd",
        "source": "tok_visa"
    }
)

if response.status_code == 200:
    charge = response.json()
    print(charge["id"])
elif response.status_code == 402:
    error = response.json()["error"]
    if error["code"] == "card_declined":
        print(f"Card declined: {error['message']}")
else:
    print(f"Error: {response.status_code}")

With an SDK:

import stripe

stripe.api_key = "sk_live_abc123"

try:
    charge = stripe.Charge.create(
        amount=2000,
        currency="usd",
        source="tok_visa",
        idempotency_key="unique_key_123"
    )
    print(charge.id)
except stripe.error.CardError as e:
    print(f"Card declined: {e.user_message}")

The SDK version is shorter, more readable, and handles edge cases (retries, connection errors, API versioning) that the raw HTTP version does not. Developers who use the SDK make fewer integration mistakes.

Auto-Generated vs Hand-Crafted SDKs

Auto-Generated SDKs

Tools like openapi-generator, Speakeasy, and Fern generate SDKs from your OpenAPI specification. You maintain the spec, and the generator produces SDKs in 20+ languages automatically.

openapi-generator generate \
  -i openapi.yaml \
  -g python \
  -o ./sdk/python

Advantages:

  • Consistent with the API specification by construction
  • Available in many languages with minimal effort
  • Updates automatically when the spec changes
  • Lower maintenance cost than hand-crafted SDKs

Disadvantages:

  • Generated code often feels unnatural in the target language
  • Method names and class hierarchies may be awkward
  • Error handling may not follow language conventions
  • Limited customization of the developer experience

Hand-Crafted SDKs

Written by developers who know both the API and the target language. Stripe, Twilio, and AWS write their SDKs by hand (or with heavily customized generators).

Advantages:

  • Idiomatic code that feels native to the language
  • Tailored error handling with language-appropriate patterns
  • Helper methods for common workflows
  • Better documentation and examples

Disadvantages:

  • Expensive to maintain across many languages
  • Risk of drift between the SDK and the actual API
  • Requires dedicated SDK engineering teams

The Practical Middle Ground

Start with auto-generated SDKs to cover many languages quickly. Hand-craft SDKs in your top 2-3 languages (the ones most of your consumers use). The auto-generated SDKs provide baseline coverage; the hand-crafted ones provide excellent developer experience where it matters most.

Webhooks for Push Notifications

APIs are pull-based: the client asks, the server answers. Webhooks invert this: the server pushes events to the client when something happens.

Event: charge.succeeded

POST https://your-app.com/webhooks/stripe
Content-Type: application/json
Stripe-Signature: t=1234,v1=abc...

{
  "id": "evt_abc123",
  "type": "charge.succeeded",
  "data": {
    "object": {
      "id": "ch_abc123",
      "amount": 2000,
      "currency": "usd",
      "status": "succeeded"
    }
  }
}

Key webhook design decisions:

Signature verification — every webhook payload should be signed so the receiver can verify it came from your API, not an attacker. Stripe uses HMAC-SHA256 with a shared secret.

Retry policy — if the receiver returns a non-2xx response, retry with exponential backoff. Document the retry schedule (e.g., retry after 1 minute, 5 minutes, 30 minutes, 2 hours, then stop).

Event types — use a clear naming convention. Stripe uses resource.action: charge.succeeded, customer.created, invoice.payment_failed.

Idempotency — receivers may get the same event twice (due to retries). Include an event ID so receivers can deduplicate.

{
  "id": "evt_abc123",
  "type": "invoice.payment_failed",
  "created": 1705312200,
  "data": {
    "object": {
      "id": "in_abc123",
      "customer": "cus_def456",
      "amount_due": 4999,
      "next_payment_attempt": 1705398600
    }
  }
}

Sandbox Environments

A sandbox lets developers test their integration without affecting real data or incurring real charges.

Stripe's Test Mode

Stripe provides test-mode API keys (sk_test_...) that work identically to live keys but never process real payments. Test credit card numbers produce predictable results:

4242424242424242 → Always succeeds
4000000000000002 → Always declines
4000000000009995 → Insufficient funds

Developers build and test their entire integration in test mode, then switch to live keys for production. The API behavior is identical — only the data is fake.

Separate Sandbox Environments

Some APIs provide a separate sandbox URL:

Production: https://api.example.com/v1/
Sandbox:    https://sandbox.api.example.com/v1/

This is simpler to implement (separate database, separate deployment) but creates a risk of behavior differences between sandbox and production. Stripe's approach (same API, different keys) avoids this risk.

Seed Data

Provide pre-populated test data in sandbox environments. New developers should see example users, orders, and transactions immediately, not an empty database.

{
  "id": "user_test_abc123",
  "name": "Test User",
  "email": "test@example.com",
  "created_at": "2025-01-01T00:00:00Z"
}

API Explorer & Playground

An API explorer is an interactive tool where developers make API calls from a web interface, see responses in real time, and experiment with parameters.

API Explorer:
  Endpoint: GET /v1/users
  Parameters:
    limit: [10]
    status: [active ▼]
  Headers:
    Authorization: Bearer [sk_test_abc123]
  
  [Send Request]
  
  Response (200 OK, 45ms):
  {
    "data": [
      {"id": "user_123", "name": "Jane Doe", "status": "active"},
      {"id": "user_456", "name": "Bob Smith", "status": "active"}
    ],
    "has_more": true
  }

GitHub's GraphQL Explorer lets developers build GraphQL queries interactively with autocomplete and schema documentation. Postman collections provide a similar experience for REST APIs.

The explorer reduces the barrier to experimentation. Developers who can try your API without writing code are more likely to adopt it.

Onboarding: Time to First Successful API Call

The most important metric for developer experience is time to first successful API call (TTFSC). This measures how long it takes a new developer to go from "I want to use this API" to "I made a request and got a response."

Stripe targets under 5 minutes. Their onboarding flow:

  1. Sign up (30 seconds)
  2. Get test API key from dashboard (30 seconds)
  3. Copy curl example from quickstart (15 seconds)
  4. Paste in terminal and run (15 seconds)
  5. See successful response (instant)

Total: under 2 minutes for a motivated developer.

What Slows Down TTFSC

  • Account approval — requiring manual approval before issuing API keys. Provide sandbox keys instantly.
  • Complex authentication — OAuth flows, certificate-based auth, or multi-step key generation before the first call. Provide simple API keys for getting started.
  • No quickstart — forcing developers to read comprehensive documentation before their first call.
  • Broken examples — copy-paste examples that do not work due to outdated URLs, missing headers, or wrong data types.
  • Empty sandbox — a sandbox with no data. The first API call returns an empty list, which feels like something is wrong.

Measuring TTFSC

Track the time between account creation and the first successful API call (2xx response) for each new API key. Plot this as a distribution:

TTFSC Distribution:
  < 5 min:   45% of new developers
  5-15 min:  30%
  15-60 min: 15%
  > 60 min:  10%

The developers in the >60 minute bucket are struggling. Investigate why. Is it a documentation gap? An authentication problem? A confusing error message?

Developer Experience Principles

Make the Common Case Easy

The most common API operation should require the least code. If 80% of your users create charges with amount, currency, and a payment method, that should be a one-liner in the SDK:

charge = stripe.Charge.create(amount=2000, currency="usd", source="tok_visa")

Advanced options (metadata, idempotency keys, expand parameters) are available but not required.

Fail Helpfully

When a developer makes a mistake, tell them exactly what went wrong and how to fix it. Do not make them guess.

{
  "error": {
    "code": "parameter_missing",
    "param": "currency",
    "message": "Missing required param: currency. You must specify a three-letter ISO currency code (e.g., 'usd').",
    "doc_url": "https://docs.example.com/api/charges#create"
  }
}

Be Consistent

Use the same patterns everywhere. Same naming conventions, same pagination style, same error format, same authentication method. Developers learn the pattern once and apply it across the entire API.

Provide Escape Hatches

SDKs should make the common case easy but not prevent advanced usage. Let developers access raw HTTP responses, set custom headers, and override default behavior when they need to.

# Normal SDK usage
user = client.users.get("user_123")

# Escape hatch: raw HTTP access
response = client.request("GET", "/v1/users/123", headers={"X-Custom": "value"})

Common Pitfalls

  • No SDK — expecting every developer to make raw HTTP calls. SDKs reduce integration time from hours to minutes.
  • Unmaintained SDKs — publishing SDKs that fall behind the API. An SDK that does not support new endpoints or returns wrong types is worse than no SDK.
  • No sandbox — requiring developers to use production data for testing. This creates risk and slows development.
  • Webhook reliability — sending webhooks without retries, without signatures, or without idempotent event IDs. Webhooks are infrastructure; treat them with the same rigor as the API itself.
  • Complex onboarding — requiring approval, legal agreements, or multi-step configuration before a developer can make their first API call.
  • Ignoring TTFSC — not measuring time to first successful API call. If you do not measure it, you cannot improve it.
  • Documentation separate from SDKs — documentation shows raw HTTP examples but the SDK uses different method names. Align documentation with SDK usage.

Key Takeaways

  • SDKs wrap your API in language-native code, reducing integration time and preventing common mistakes. Start with auto-generated SDKs and hand-craft the top 2-3 languages.
  • Webhooks provide push notifications for asynchronous events. Sign every payload, retry on failure, and include event IDs for deduplication.
  • Sandbox environments let developers test without risk. Stripe's test mode (same API, different keys, fake data) is the best model. Provide seed data so the sandbox is not empty.
  • Time to first successful API call (TTFSC) is the most important developer experience metric. Target under 5 minutes. Measure it, plot the distribution, and investigate the long tail.
  • The developer experience is the product. Optimize for developer happiness: easy onboarding, helpful errors, consistent patterns, and escape hatches for advanced use cases.