Buy @ Amazon

Mind the Gap: Common Pitfalls in API Design and Developer Experience

on

Documentation is the UI of your API. Yet, while we obsess over millisecond latency and 99.99% uptime, we often ignore the very interface our users interact with first. Taking a look at the current landscape—specifically within the Indian stock-broking sector—it’s clear that many platforms are treating APIs as a "feature checkmark" rather than a product.

Here is a breakdown of where the industry is failing and how to fix it. 

1. The Sandbox: A Non-Negotiable Requirement

In fintech, code doesn't live in a vacuum—it lives near capital. Expecting a developer to test their integration against a live production environment (and live funds) is a catastrophic failure in DX. 
Sandbox is an established norm of providing a playground for its API end-users to both increase adoption and enrich their onboarding experience. Most Stock Broking platforms in India don't really have one. Of the few that has it, most are broken.
  • The Problem: Most Indian brokers offer "Production-only" access.
  • The Standard: A high-parity Sandbox environment that mimics production behavior without the financial risk. Without this, your onboarding funnel has a giant leak.

2. The SDK Gap: Do Not Make The End-User Re-Invent The Wheel

If you only provide REST endpoints, you are offloading the burden of authentication, retry logic, and pagination onto every single customer. SDKs simplify API integration (auth, retries, errors, pagination, language-native) and thus increase the scope for adoption. Unless you have only a few endpoints to expose, you shouldn't think of skipping their development.
  • The Insight: Engineering leaders must identify the languages that dominate their ecosystem (Python, Node.js, Go) and provide native wrappers.
  • The Goal: An SDK should allow a developer to go from `pip install` to their first successful request in under 5 minutes. How cool is that? Isn't that the kind of goal that is worth pursuing? 

3. The Primitive SDK: You Sure Can Do Better

An SDK that simply passes strings and integers into a flat function is just a "glorified CURL request" to be polite. SDK with Primitive APIs that is not encapsulated well enough and is too raw having endpoints that take too many parameters of primitive datatypes instead of one well defined meaningful Object type is nearly as bad as not having one at all. 
  • The Critique: Many SDKs suffer from a "namesake" implementation.
  • The Fix: Use Strongly Typed Objects. Instead of a function taking 15 primitive arguments, use well-defined Request Objects. This enables IDE autocomplete and compile-time safety, reducing the "trial and error" loop for the end user.

4. The Stale SDK: Do Not Trap Your End-User

Nothing erodes trust faster than a mismatch between the documentation and the SDK. This is often the result of "Performative Engineering"—building a tool once for the launch announcement but never funding its maintenance.
  • The Expert Take: If your SDK is not auto-generated from your OpenAPI/Swagger spec, it is destined to become stale. Engineering teams must treat SDK maintenance as a core part of the CI/CD pipeline, not an afterthought. Warning again, simple auto-generation will give Primitive SDK. Leverage right tools like Fern, SpeakEasy, Stainless Docs, and such.

5. Bad API Doc Tool: Reflects Engineering's Over-sight Of Real Problem

If you have worked on REST API long enough as a developer, the snapshot of the Dhan API page should tell something is off-putting - the page structure.
Dhan API - Homepage
Interestingly enough, Zerodha's API page as well is similar as can be seen below:
Zerodha's Kite API - Homepage
Based on Kite API's homepage, I deduce that these pages are likely generated from MkDocs-Material. It is a fantastic tool for static site generation, just that API Docs is not one of them. Zerodha as leading broker adopted it, and then others possibly followed it hoping to compete with them making the same mistake they did. Okay, not all but some aped it. Below are some stock brokering entities that chose right tooling in the sense of standardized and defacto approach:
There always have been this pattern where companies like cult followers, copy market leaders or trends without understanding the underlying technical requirements.
  • The Tooling Fail: MkDocs-Material is a world-class tool for project documentation and such, but it lacks the three-pane interactivity as in OpenAPI Spec (aka OAS) required for modern APIs.
  • The Gold Standard: Developers need a layout that preserves context:
    • Left: Navigation (ToC)
    • Middle: Description and Schema
    • Right: Live Code Samples
Developer Experience (DX) is not a "nice-to-have" marketing fluff. It is an engineering discipline. When you provide a broken SDK or a non-existent sandbox, you aren't just frustrating a dev; you are telling the market that your infrastructure is an afterthought.
Don't jump into the rat race with FOMO. Don't live in your own delusional world either. Follow the market for trends, make bets doing your due diligence, and prepare right to showcase yourself bright.