Post

hard agree *(edited)*

someone finally said it

why is this buried? this is the real answer

THIS exactly

OP should pin this

underrated take

why is this buried? this is the real answer

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...

skill issue tbh

saving this comment *(edited)*

the way I nodded reading this

saving this comment

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

aPI clients who didnt DOCUMENT errors are worse.

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

this right here 👆

saving this comment

screenshotting this

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

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?

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

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

you're just now figuring that out lmfao

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.

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

that's crazy

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

ok boomer

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

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

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)*

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

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

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

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

What did ur friend do to escape

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

Written by engineers but for engineers lmfao

do they not think users read the code imo

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

ratio

so brave for sharing this completely obvious thing

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

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?

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

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

the way I nodded reading this

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

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

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

this right here 👆

Wiki's are soooo intuitive to navigate for docs fr

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)*

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

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

came here to say this

oof

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

so brave for sharing this completely obvious thing

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

Why’d you think it spirals so fast

nah this crazy

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

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

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 😂

L take

no way are you just casually dropping 'L take'? what happened

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

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..

Yeah but enapi endpoints can be soooo finicky and the doc dont even mention the query param thats required to get..

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

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...

spent months wrestling a 500 page api doc monstrosity

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

hard agree

this comment > the whole thread

underrated take

What do u mean by "API doc hell" r u talkin bout how theyre so basic but somehow still confusing lol u gotta explain

this comment > the whole thread

underrated take

saving this comment

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

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

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

this person gets it

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

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

this needs more upvotes

So data hell is just api hell with more commas

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)*

why tho

actually 💀

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)*