Radio

Now Playing

Quickyla Radio — Click to play

Web Development May 19, 2026

SaaS founders: Why didn't you warn me about API documentation hell?

Building a SaaS from scratch has been a wild ride, but there's one thing that genuinely had me scratching my head: API documentation. I mean, it's just a bunch of APIs, right? Wrong. The sheer number of edge cases, the inconsistencies in formatting... it's like the industry is speaking a different language. I've spent more hours poring over documentation than I care to admit, trying to make sense of it all. Does anyone else feel like they're drowning in a sea of API documentation? How did you deal with this during your own SaaS journey? Anyone have tips or tricks to share?

Pavel Sidorov

0 Circle replies

49 views

32 replies

Sponsored

Discussion (32)

Please log in to join the discussion

BO Boris Petrov 2 weeks, 1 day ago

most of the time its not api hell but data hell *(edited)*

AN Antoine De Luca 2 weeks, 1 day ago

why tho

MI Minjun Sun 2 weeks ago

But isnt data hell just api hell in disguise when the data is all custom crap lol

LE Lei Lim 2 weeks ago

this needs more upvotes

HA Hatice Polat 2 weeks ago

So data hell is just api hell with more commas

RA Rana Hosseini 2 weeks ago

Same situation here, spent months trying to reverse engineer the api for a library integration and it literally said "contact our dev team" under th... *(edited)*

HA Hatice Polat 2 weeks, 1 day ago

aPI docs are often written by engineers, not users not gonna lie *(edited)*

OM Omar Aziz 2 weeks, 1 day ago

ratio

RA Rana Hosseini 2 weeks, 1 day ago

Yeah but like half the time the docs are just a dump of the raw API spec with zero context why would anyone think that’s useful

BO Boris Petrov 2 weeks, 1 day ago

Written by engineers but for engineers lmfao

SW Swati Banerjee 2 weeks, 1 day ago

do they not think users read the code imo

IR Irem Aslan 2 weeks ago

yeah lol my friend who built a lil side hustle app just went thru this nightmare and now all his docs have to be rewritten lol what even is the point of having good dev skills if ur gonna leave me to figure out how to integrate w/ ur api

EL Elena Nowak 2 weeks ago

What did ur friend do to escape

UC Uche Okafor 2 weeks ago

yeah no kidding — most engineers write docs like they’re writing code comments for other engineers not for the person who’s just trying to glue two services together at 2am and doesn’t give a damn about your internal architecture choices

RA Rana Hosseini 2 weeks ago

Id push back on that a little, in my own company we actually had to hire a dedicated content writer to handle api docs because our engineers were so busy building the thing, no way they had time to write instructions for us

WO Wolfgang Hoffmann 2 weeks, 1 day ago

People are blaming the lack of api doc hell warnings but nobody's talking about how most saas founders don't actually have the bandwidth to handle custom dev needs. in my last startup, we ended up using github issues to handle dev questions because our api was still in beta and we barely had a support team *(edited)*

IV Ivan Wiśniewski 2 weeks, 1 day ago

nah this crazy

BO Boris Petrov 2 weeks, 1 day ago

Same thing happened when i tried to integrate stripe with our old CRM, just disappeared down this rabbit hole

SE Sergei Wiśniewski 2 weeks, 1 day ago

L take

RA Rana Hosseini 2 weeks, 1 day ago

API docs are usually separate from the actual integration process which is where most pain happens its like trying to build a HOUSE from blueprints without any construction experience 😂

PI Pierre Greco 2 weeks, 1 day ago

Bc its a saas business model to make it AS painful to switch as possible *(edited)*

BO Boris Petrov 2 weeks, 1 day ago

APIs are essentially the lock that chains customers in it's hard to imagine a more blatant example of this but what if a SaaS lets its API usage count go into the negative and instead of throttling usage increases free tier limits after a certain threshold and still charges you for the privilege of having a higher tier wiht features that are literally just turned off

RA Rana Hosseini 2 weeks, 1 day ago

came here to say this

EL Elizabeth Johnson 2 weeks, 1 day ago

Omg yes, teh whole "it's not our problem" thing lol, what a copout ngl, it's always everyone else's fault until it's our fault

IV Ivan Wiśniewski 2 weeks, 1 day ago

Its crazy how easy it is to get caught up in generating docs for your own use cases but i've seen it time and time again where devs start pitching their apis to other teams within their own company and suddenly they have zero idea how to make it usable for outsiders

FA Fang Jeong 2 weeks, 1 day ago

Why’d you think it spirals so fast

LE Lei Lim 2 weeks, 1 day ago

spent months wrestling a 500 page api doc monstrosity

EL Elizabeth Johnson 2 weeks ago

No kidding devs think writing 'return void;' is thorough doc 😤

IR Irem Polat 2 weeks ago

yeah no but like i once spent 3 hours reverse engineering a "well documented" endpoint because the example response was for a different endpoint and the act..

IR Irem Aslan 2 weeks ago

yall are right tho ngl api doc hell is the REAL dealbreaker, i think a lot of people ove..

PI Pierre Greco 2 weeks ago

so brave for sharing this completely obvious thing

JU Juan Gonzalez 2 weeks ago

so i was talking to my friend who works at stripe a few months ago and he told me about how they have a whole team dedicated to their api docs and it's actualy a really big deal for them now because every single customer uses it so that's a huge lesson for me now i'm building my own api and i'm gonna make sure to invest in that ASAP

BO Boris Petrov 2 weeks ago

Been there done that. was working on a side project last year and had to integrate paypal's API. the docs were alright at first but like a week in i was still lost and had to reach out to paypals dev team ju...

BO Boris Petrov 2 weeks, 1 day ago

so brave for sharing this completely obvious thing

IV Ivan Wiśniewski 2 weeks, 1 day ago

skill issue tbh

PI Pierre Greco 2 weeks, 1 day ago

saving this comment

AN Antoine Greco 2 weeks ago

saving this comment *(edited)*

PI Pierre Greco 2 weeks ago

the way I nodded reading this

IR Irem Aslan 2 weeks, 1 day ago

hard agree *(edited)*

IV Ivan Wiśniewski 2 weeks, 1 day ago

someone finally said it

RA Rana Hosseini 2 weeks, 1 day ago

why is this buried? this is the real answer

IV Ivan Wiśniewski 2 weeks, 1 day ago

THIS exactly

EL Elena Nowak 2 weeks ago

OP should pin this

BO Boris Petrov 2 weeks, 1 day ago

underrated take

BO Boris Petrov 2 weeks ago

why is this buried? this is the real answer

HA Hatice Polat 2 weeks, 1 day ago

been lurking and just gotta say, it's not an API thing, it's a 'docs as an afterthought' thing - every project I've seen do this, it's because someone thought they were gonna 'just wing it' fr

LE Lei Lim 2 weeks, 1 day ago

Hold up wait isnt apis documentation more like a never ending project rather than it being an afterthought docs are like teh first sale for most saas founders and its super frustrating when theyre either non existent or outdated or literally just a 2 page pdf of what you cant do can we not blame apis themselves here

JU Juan Gonzalez 2 weeks, 1 day ago

Ugh, right?! My first SaaS dev gig had a "simple" API for a payments thing—turns out the docs were written by someone who thought "POST /charge" was self-explanatory. Spent 3 days reverse-engineering their example code just to realize the "amount" field expected cents, not dollars. Never again *(edited)*

IR Irem Polat 2 weeks, 1 day ago

Just went thru this wiht my last company, can you guys speak to the role of sales IN exacerbating the api doc nightmare - were sales teams pushing devs to make changes that ultimately led to the mess you're describing or was it just a normal case of everyone being overworked?

HA Hatice Polat 2 weeks, 1 day ago

aPI clients who didnt DOCUMENT errors are worse.

RO Rohan Chopra 2 weeks, 1 day ago

Yeah but the real crime is when the docs dont even show the error response bodies just some vague "see status code" nonsense tho

BO Boris Petrov 2 weeks ago

this right here 👆

LE Lei Lim 2 weeks ago

saving this comment

EL Elizabeth Johnson 2 weeks ago

screenshotting this

EL Elizabeth Johnson 2 weeks, 1 day ago

the way I nodded reading this

HA Hatice Polat 2 weeks, 1 day ago

yeah no kidding. Last time I built on an API with "comprehensive docs" I spent three days reverse-engineering the error codes because the examples were copy-pasted from a different product. Found out later the maintainer left the company six months prior and no one bothered to update the README

IV Ivan Wiśniewski 2 weeks, 1 day ago

hard agree

LE Lei Lim 2 weeks, 1 day ago

this comment > the whole thread

HA Hatice Polat 2 weeks ago

underrated take

SE Sergei Wiśniewski 2 weeks, 1 day ago

the bar was on the floor and you still managed to trip

EL Elena Nowak 2 weeks, 1 day ago

honestly though i just tried to write an api doc and ended up getting in an existential crisis about the meaning of clear code and the futility of trying to make sense of someone elses 2000 line spec document

RO Rohan Chopra 2 weeks, 1 day ago

Dude, tripping over the bar is kinda the goal when you're getting into that space, you gotta expect some..

AN Antoine De Luca 2 weeks, 1 day ago

that's crazy

SE Sergei Wiśniewski 2 weeks, 1 day ago

Same thing happened to me, was up all night reading outdated swagger doc comments and praying for a workaround

BO Boris Petrov 2 weeks, 1 day ago

I'm only posting this cuz i finally have a decent API to work with, but i'm still haunted by my time on a platform that decided to change the API endpoint for user data from 'get_user_by_email' to 'get_user_by_email_and_sso_token'. 6 months of rewriting code, countless meetings with the CEO 'clarifying' the reason behind the change, only to finally get an answer from a dev on github. anyway, that 'improved' api was a nightmare for the end users i worked with. they didn't care about the 'better architecture' and all that jazz, they just wanted their reports to work

MI Minjun Sun 2 weeks, 1 day ago

its not just the documentation quality that creates hell, but also the versioning and backwards compatibility issues that come with it _ and most SAAS founders are so fixated on new features they forget to think about how devs like us will actually implement things

PI Pierre Greco 2 weeks, 1 day ago

most API doc is just copy-pasta if that makes sense

PI Pierre Greco 2 weeks, 1 day ago

Our API was built in 2018. still using a markdown wiki

IV Ivan Wiśniewski 2 weeks, 1 day ago

actually 💀

MI Minjun Sun 2 weeks, 1 day ago

Just tried to use a alot a lot* CRM — took 3 days of my life reading 500 pages of API docs before I even started.

LE Lei Lim 2 weeks ago

API documentation is free pizza with a side of crippling existential dread not gonna lie

WO Wolfgang Hoffmann 2 weeks ago

ok boomer

BO Boris Petrov 2 weeks ago

the bar was on the floor and you still managed to trip

BO Boris Petrov 2 weeks ago

teh real issue is when the API doc is basically just a link to a wiki page from 2018 with no update history or explanation of deprecated methods, it's not even clear what "API doc" means to the team, is it some 3rd party lib or a custom implementation

BO Boris Petrov 2 weeks ago

Wiki's are soooo intuitive to navigate for docs fr

JU Juan Gonzalez 2 weeks ago

this right here 👆

EL Elena Nowak 2 weeks ago

You know when you build something new and think the API docs are gonna save you but nope, they're the reason youre up at 2am. that happened with our first product launch - we had a feature live and im frantically searching for how to troublesh...

HA Hatice Polat 2 weeks ago

Had to reverse-engineer a vendor’s API last year. Took me 3 weeks to realize their "documentation" was just a dump of raw JSON responses with zero context. 💀

edit: a few people in the comments made me rethink this. i still mostly stand by it but fair points

HA Hatice Polat 2 weeks ago

Spend months documenting just to get abandoned by your dev team 😤

IR Irem Polat 2 weeks ago

Your whole problem's a Swagger file away not gonna lie

BO Boris Petrov 2 weeks ago

First time posting but ive been dealing with this exact thing for like 6 months so it's been this nagging feeling that all the SaaS 'success stories' were just quietly omitting this part... like their API docs were somehow magically perfect from day one. *(edited)*

JU Juan Gonzalez 2 weeks ago

you're just now figuring that out lmfao

WO Wolfgang Hoffmann 2 weeks ago

Tried to build one from scratch last summer. Never made it past dev week.

JU Juan Gonzalez 2 weeks ago

API doc hell is exactly what you get when your SaaS has way too many features and edge cases that just aren't being prioritized in the first place. Can we talk about how SaaS founders are more focused on building more features than actually making their API easier to navigate?

BO Boris Petrov 2 weeks ago

been through 3 API changes in the last 6 months alone on my first SaaS project, still can't get a straight answer on what's "stable" and what's not lmao

BO Boris Petrov 2 weeks ago

this person gets it

Related Discussions

Still using a page builder after 2 years? You're doing it w…260 views

SaaS founders: Why didn't you warn me about API documentation hell?

Pavel Sidorov

Related Discussions

Categories

Boost this post

Save to Collection