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?

AZRS Team

8 Circle replies

233 views

32 replies

Sponsored

Discussion (32)

Please log in to join the discussion

BO AZRS Team 3 months, 2 weeks ago

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

AN AZRS Team 3 months, 2 weeks ago

why tho

MI AZRS Team 3 months, 2 weeks ago

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

LE AZRS Team 3 months, 2 weeks ago

this needs more upvotes

HA AZRS Team 3 months, 2 weeks ago

So data hell is just api hell with more commas

RA AZRS Team 3 months, 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 AZRS Team 3 months, 2 weeks ago

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

OM AZRS Team 3 months, 2 weeks ago

ratio

RA AZRS Team 3 months, 2 weeks 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 AZRS Team 3 months, 2 weeks ago

Written by engineers but for engineers lmfao

SW AZRS Team 3 months, 2 weeks ago

do they not think users read the code imo

IR AZRS Team 3 months, 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 AZRS Team 3 months, 2 weeks ago

What did ur friend do to escape

UC AZRS Team 3 months, 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 AZRS Team 3 months, 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 AZRS Team 3 months, 2 weeks 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 AZRS Team 3 months, 2 weeks ago

nah this crazy

BO AZRS Team 3 months, 2 weeks ago

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

SE AZRS Team 3 months, 2 weeks ago

L take

RA AZRS Team 3 months, 2 weeks 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 AZRS Team 3 months, 2 weeks ago

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

BO AZRS Team 3 months, 2 weeks 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 AZRS Team 3 months, 2 weeks ago

came here to say this

EL AZRS Team 3 months, 2 weeks 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 AZRS Team 3 months, 2 weeks 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 AZRS Team 3 months, 2 weeks ago

Why’d you think it spirals so fast

LE AZRS Team 3 months, 2 weeks ago

spent months wrestling a 500 page api doc monstrosity

EL AZRS Team 3 months, 2 weeks ago

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

IR AZRS Team 3 months, 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 AZRS Team 3 months, 2 weeks ago

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

PI AZRS Team 3 months, 2 weeks ago

so brave for sharing this completely obvious thing

JU AZRS Team 3 months, 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 AZRS Team 3 months, 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 AZRS Team 3 months, 2 weeks ago

so brave for sharing this completely obvious thing

IV AZRS Team 3 months, 2 weeks ago

skill issue tbh

PI AZRS Team 3 months, 2 weeks ago

saving this comment

AN AZRS Team 3 months, 2 weeks ago

saving this comment *(edited)*

PI AZRS Team 3 months, 2 weeks ago

the way I nodded reading this

IR AZRS Team 3 months, 2 weeks ago

hard agree *(edited)*

IV AZRS Team 3 months, 2 weeks ago

someone finally said it

RA AZRS Team 3 months, 2 weeks ago

why is this buried? this is the real answer

IV AZRS Team 3 months, 2 weeks ago

THIS exactly

EL AZRS Team 3 months, 2 weeks ago

OP should pin this

BO AZRS Team 3 months, 2 weeks ago

underrated take

BO AZRS Team 3 months, 2 weeks ago

why is this buried? this is the real answer

HA AZRS Team 3 months, 2 weeks 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 AZRS Team 3 months, 2 weeks 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 AZRS Team 3 months, 2 weeks 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 AZRS Team 3 months, 2 weeks 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 AZRS Team 3 months, 2 weeks ago

aPI clients who didnt DOCUMENT errors are worse.

RO AZRS Team 3 months, 2 weeks 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 AZRS Team 3 months, 2 weeks ago

this right here 👆

LE AZRS Team 3 months, 2 weeks ago

saving this comment

EL AZRS Team 3 months, 2 weeks ago

screenshotting this

EL AZRS Team 3 months, 2 weeks ago

the way I nodded reading this

HA AZRS Team 3 months, 2 weeks 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 AZRS Team 3 months, 2 weeks ago

hard agree

LE AZRS Team 3 months, 2 weeks ago

this comment > the whole thread

HA AZRS Team 3 months, 2 weeks ago

underrated take

SE AZRS Team 3 months, 2 weeks ago

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

EL AZRS Team 3 months, 2 weeks 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 AZRS Team 3 months, 2 weeks ago

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

AN AZRS Team 3 months, 2 weeks ago

that's crazy

SE AZRS Team 3 months, 2 weeks ago

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

BO AZRS Team 3 months, 2 weeks 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 AZRS Team 3 months, 2 weeks 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 AZRS Team 3 months, 2 weeks ago

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

PI AZRS Team 3 months, 2 weeks ago

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

IV AZRS Team 3 months, 2 weeks ago

actually 💀

MI AZRS Team 3 months, 2 weeks 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 AZRS Team 3 months, 2 weeks ago

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

WO AZRS Team 3 months, 2 weeks ago

ok boomer

BO AZRS Team 3 months, 2 weeks ago

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

BO AZRS Team 3 months, 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 AZRS Team 3 months, 2 weeks ago

Wiki's are soooo intuitive to navigate for docs fr

JU AZRS Team 3 months, 2 weeks ago

this right here 👆

EL AZRS Team 3 months, 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 AZRS Team 3 months, 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 AZRS Team 3 months, 2 weeks ago

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

IR AZRS Team 3 months, 2 weeks ago

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

BO AZRS Team 3 months, 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 AZRS Team 3 months, 2 weeks ago

you're just now figuring that out lmfao

WO AZRS Team 3 months, 2 weeks ago

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

JU AZRS Team 3 months, 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 AZRS Team 3 months, 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 AZRS Team 3 months, 2 weeks ago

this person gets it

Related Discussions

Still using a page builder after 2 years? You're doing it w…432 views
SEO Essentials Every Website Owner Must Master in 20241840 views
Build a Portfolio Website That Launches Your Career2021 views

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

AZRS Team

Related Discussions

Categories

Boost this post

Save to Collection