DEV Community

Cover image for Reddit's API: A Case Study in How to Destroy Developer Trust
YukioIkeda
YukioIkeda

Posted on

Reddit's API: A Case Study in How to Destroy Developer Trust

#webdev #api #programming

What happens when platform economics clash with API design principles.

In June 2023, thousands of subreddits went dark. The protest wasn't about content moderation or free speech—it was about an API.

Reddit had announced it would charge $0.24 per 1,000 API calls, a change that would cost Apollo (the most popular third-party Reddit client) an estimated $20 million annually. Within weeks, Apollo, Reddit Is Fun, Sync, and dozens of beloved apps announced they were shutting down.

This is more than a story about pricing. It's a masterclass in how API design decisions—both technical and strategic—can make or break a platform's relationship with its developer ecosystem.

Let's dissect what Reddit's API got right, what it got wrong, and what we can learn from the wreckage.

The Technical Foundation: Not Terrible, Not Great

Before the controversy, Reddit's API was... functional. Let's look at the architecture.

What Reddit Got Right

1. RESTful Resource Organization

Reddit's API follows a logical, resource-oriented structure:

GET /r/{subreddit}/hot          # Hot posts in a subreddit
GET /r/{subreddit}/new          # New posts
GET /r/{subreddit}/comments/{id} # Comments on a post
GET /api/v1/me                   # Current user info
Enter fullscreen mode Exit fullscreen mode

The URL patterns are intuitive. If you understand how Reddit works as a user, you can guess the endpoints.

2. The "Thing" System and Fullnames

Reddit has a clever identification system. Every object is a "thing" with a type prefix:

Prefix Type
t1_ Comment
t2_ Account
t3_ Post (Link)
t4_ Message
t5_ Subreddit
t6_ Award

A fullname combines the type with a base-36 ID:

t3_15bfi0  → Post with ID 15bfi0
t1_cvp5afk → Comment with ID cvp5afk
Enter fullscreen mode Exit fullscreen mode

This is actually similar to Stripe's prefixed IDs (ch_, cus_), and it serves the same purpose: instant type recognition without additional context.

3. OAuth 2.0 Implementation

Reddit implemented OAuth 2.0 properly, supporting multiple grant types:

  • Authorization code flow (for web apps)
  • Implicit flow (for client-side apps)
  • Client credentials (for app-only access)
  • Password grant (for scripts—though discouraged)

The token endpoint and scopes are well-defined:

POST https://www.reddit.com/api/v1/access_token
Authorization: Basic {base64(client_id:client_secret)}
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=CODE&redirect_uri=URI
Enter fullscreen mode Exit fullscreen mode

Where Reddit's Design Falls Apart

1. The Listing Wrapper Problem

Every list response in Reddit's API is wrapped in multiple layers:

{
  "kind": "Listing",
  "data": {
    "after": "t3_abc123",
    "before": null,
    "children": [
      {
        "kind": "t3",
        "data": {
          "id": "abc123",
          "title": "Actual post title",
          "author": "username",
          ...
        }
      }
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

To get the title of the first post, you need:

response.data.children[0].data.title
Enter fullscreen mode Exit fullscreen mode

Compare this to Stripe:

response.data[0].title  // Much cleaner
Enter fullscreen mode Exit fullscreen mode

The kind field at every level is theoretically useful for polymorphic parsing, but in practice it creates verbosity without proportional benefit.

2. Inconsistent Response Formats

Different endpoints return data in different shapes:

  • Listing endpoints return the wrapped structure above
  • Single-resource endpoints sometimes return the object directly
  • Some endpoints return arrays without the Listing wrapper
  • Error responses have their own inconsistent formats

This lack of consistency means developers can't build reliable abstractions. Every endpoint feels like a special case.

3. Documentation: A Cautionary Tale

Reddit's API documentation has been described as "notoriously hard to navigate." Key issues:

  • No OpenAPI specification: Unlike modern APIs, you can't generate clients automatically
  • Incomplete examples: Many endpoints lack code samples
  • Outdated information: Parameters that no longer work, deprecated endpoints without clear alternatives
  • Poor organization: Finding the right endpoint often requires trial and error

Here's the official documentation page structure:

reddit.com/dev/api/
├── Account
├── Captcha
├── Collections
├── Emoji
├── Flair
├── Gold
├── Links & Comments
├── Listings
├── Live Threads
├── Misc
├── Moderation
├── Modmail
├── ...
Enter fullscreen mode Exit fullscreen mode

No tutorials. No quickstart. Just a wall of endpoints.

4. Pagination That Makes You Think

Reddit uses cursor-based pagination (good!), but the implementation is confusing:

GET /r/programming/hot?limit=25&after=t3_abc123
Enter fullscreen mode Exit fullscreen mode
  • after: Fullname of the last item (for next page)
  • before: Fullname of the first item (for previous page)
  • limit: Number of items (max 100)

The problems?

  • Cursors are fullnames (visible IDs), not opaque tokens — you can see and manipulate them, which invites mistakes
  • The semantics of after/before aren't immediately obvious: does "after" mean newer or older?
  • No has_more equivalent in older endpoints — you had to check if the returned array was empty

To be fair, Stripe uses a similar two-parameter system (starting_after/ending_before). But Stripe's pagination benefits from better documentation, consistent has_more flags, and SDK auto-pagination helpers that abstract away the complexity.

5. Rate Limiting: The Silent Killer

Reddit's rate limits are reasonable on paper:

  • Authenticated: 100 requests/minute (per OAuth client, averaged over 10-minute window)
  • Unauthenticated: ~10 requests/minute (per IP)

But here's what's not documented well:

  • Different actions have different hidden limits
  • Posting/commenting has stricter limits than reading
  • Rate limit headers exist (X-Ratelimit-Remaining) but aren't consistently returned
  • Getting rate limited returns 429, but the error message doesn't always tell you when to retry

Developers discovered these limits through trial and error, not documentation.

The Real Problem: API Strategy, Not API Design

Reddit's technical API issues are annoying but workable. What killed the developer ecosystem was strategy.

The $20 Million Question

When Reddit announced API pricing in April 2023, the math was brutal:

Apollo's API usage: ~7 billion calls/month
New pricing: $0.24 per 1,000 calls
Monthly cost: $1.68 million
Annual cost: ~$20 million
Apollo's annual revenue: ~$1 million
Enter fullscreen mode Exit fullscreen mode

This wasn't a pricing adjustment. It was an extinction event.

What Reddit Said vs. What Developers Heard

Reddit said:

"Large companies shouldn't get our data for free to train AI models."

Developers heard:

"We're going public soon and need to show revenue growth. Your apps are collateral damage."

The messaging was particularly tone-deaf because:

  1. Third-party apps drove significant user engagement
  2. Many apps provided accessibility features Reddit's official app lacked
  3. Moderators relied on third-party tools (built on the API) to manage communities
  4. The timeline gave developers ~60 days to adapt or die

The Trust Destruction Playbook

Reddit demonstrated several anti-patterns for platform relationships:

  1. No communication before announcement: Developers learned about pricing from a public blog post
  2. Hostile negotiation: When Apollo's developer tried to negotiate, Reddit leadership was unresponsive for months
  3. Moving goalposts: First it was about AI companies, then about "inefficient" apps, then about sustainable business
  4. No migration path: No tiered pricing, no grandfathering, no transition period

Compare this to how Stripe handles API changes:

  • Advance notice (often 12+ months for deprecations)
  • Detailed migration guides
  • Backward compatibility layers
  • Dedicated support for large integrations

Lessons for API Builders

Reddit's API saga is a case study in what not to do. Here are the lessons:

1. Documentation Is Not Optional

If developers can't figure out your API without reading your source code, you've failed. Invest in:

  • OpenAPI/Swagger specifications
  • Interactive documentation (like Stripe's)
  • Tutorials for common use cases
  • Up-to-date code samples in multiple languages

2. Consistency Beats Cleverness

Reddit's nested kind/data structure might have seemed elegant, but it created friction at every turn. Pick a response format and stick with it:

// Stripe's consistent structure
{
  "object": "list",
  "data": [...],
  "has_more": true
}
Enter fullscreen mode Exit fullscreen mode

3. Your Developer Ecosystem Is a Moat, Not a Threat

Third-party apps weren't stealing Reddit's users—they were serving users Reddit couldn't. Apollo had accessibility features. Reddit Is Fun had a better UX for power users. These apps made Reddit more valuable.

When you kill your ecosystem, you kill innovation you couldn't have built yourself.

4. API Pricing Needs a Migration Strategy

If you must monetize your API:

  • Announce changes 6-12 months in advance
  • Offer tiered pricing (free tier for small developers)
  • Grandfather existing integrations
  • Provide clear ROI for the pricing (better service, more features, etc.)

5. Trust Is a One-Way Door

Reddit's relationship with developers will take years to rebuild—if it ever does. The message was clear: "We can change the rules whenever we want, and your business doesn't matter."

No developer wants to build on that foundation.

The Contrast: What Good Looks Like

Aspect Reddit Stripe
Documentation Incomplete, outdated Three-column, interactive, auto-generated API keys
Response consistency Variable structure Predictable across all endpoints
ID format t3_xxx (good!) ch_xxx, cus_xxx (also good!)
Versioning /api/v1/ (unclear strategy) Date-based, account-pinned, backward compatible
Developer communication Blog post announcement Changelog, migration guides, dedicated support
Pricing changes 60 days notice, no tiers Years of stability, granular pricing

Conclusion: APIs Are Promises

An API is a contract between a platform and its developers. Every endpoint is a promise: "Build on this, and we'll keep it working."

Reddit broke that promise. Not because their technical API was terrible—it was mediocre at worst. They broke it by treating developers as an extraction opportunity rather than partners in building value.

The technical lessons are clear: document thoroughly, design consistently, communicate changes early. But the strategic lesson is more important:

Your developers are not your enemies. They're the ones who see possibilities you don't.

Reddit had an ecosystem of passionate developers building better experiences for their users. Now they have a lawsuit, a PR crisis, and a generation of developers who will never trust them again.

That's not an API problem. That's a leadership problem.

At Apidog, we believe great APIs deserve great tools. Design, document, and test your APIs with developer experience in mind. Get started free.

Top comments (0)