Got my hands on an interesting API.
Look around on the site.
No documentation. Like, nothing. Not even examples.
Tried calling it.
Response code: 200 OK
Body: Unknown Error.

Well, fuck you too.

"there's a problem with your API"
Me: "why?"
"I get no data"
Me: "what response code are you getting?"
"405 - Method not allowed. But only on the /version endpoint"
Me: "Soo... What request are you sending?"
"POST"

WHY THE FUCK WOULD YOU SEND A POST REQUEST TO AN ENDPOINT THAT **GETS** THE VERSION OF MY API???!!!!

Me: "Read the documentation. It's there for a reason"

!rant

This was over a year ago now, but my first PR at my current job was +6,249/-1,545,334 loc. Here is how that happened... When I joined the company and saw the code I was supposed to work on I kind of freaked out. The project was set up in the most ass-backward way with some sort of bootstrap boilerplate sample app thing with its own build process inside a subfolder of the main angular project. The angular app used all the CSS, fonts, icons, etc. from the boilerplate app and referenced the assets directly. If you needed to make changes to the CSS, fonts, icons, etc you would need to cd into the boilerplate app directory, make the changes, run a Gulp build that compiled things there, then cd back to the main directory and run Grunt build (thats right, both grunt and gulp) that then built the angular app and referenced the compiled assets inside the boilerplate directory. One simple CSS change would take 2 minutes to test at minimum.

I told them I needed at least a week to overhaul the app before I felt like I could do any real work. Here were the horrors I found along the way.

- All compiled (unminified) assets (both CSS and JS) were committed to git, including vendor code such as jQuery and Bootstrap.
- All bower components were committed to git (ALL their source code, documentation, etc, not just the one dist/minified JS file we referenced).
- The Grunt build was set up by someone who had no idea what they were doing. Every SINGLE file or dependency that needed to be copied to the build folder was listed one by one in a HUGE config.json file instead of using pattern matching like `assets/images/*`.
- All the example code from the boilerplate and multiple jQuery spaghetti sample apps from the boilerplate were committed to git, as well as ALL the documentation too. There was literally a `git clone` of the boilerplate repo inside a folder in the app.
- There were two separate copies of Bootstrap 3 being compiled from source. One inside the boilerplate folder and one at the angular app level. They were both included on the page, so literally every single CSS rule was overridden by the second copy of bootstrap. Oh, and because bootstrap source was included and commited and built from source, the actual bootstrap source files had been edited by developers to change styles (instead of overriding them) so there was no replacing it with an OOTB minified version.
- It is an angular app but there were multiple jQuery libraries included and relied upon and used for actual in-app functionality behavior. And, beyond that, even though angular includes many native ways to do XHR requests (using $resource or $http), there were numerous places in the app where there were `XMLHttpRequest`s intermixed with angular code.
- There was no live reloading for local development, meaning if I wanted to make one CSS change I had to stop my server, run a build, start again (about 2 minutes total). They seemed to think this was fine.
- All this monstrosity was handled by a single massive Gruntfile that was over 2000loc. When all my hacking and slashing was done, I reduced this to ~140loc.
- There were developer's (I use that term loosely) *PERSONAL AWS ACCESS KEYS* hardcoded into the source code (remember, this is a web end app, so this was in every user's browser) in order to do file uploads. Of course when I checked in AWS, those keys had full admin access to absolutely everything in AWS.
- The entire unminified AWS Javascript SDK was included on the page and not used or referenced (~1.5mb)
- There was no error handling or reporting. An API error would just result in nothing happening on the front end, so the user would usually just click and click again, re-triggering the same error. There was also no error reporting software installed (NewRelic, Rollbar, etc) so we had no idea when our users encountered errors on the front end. The previous developers would literally guide users who were experiencing issues through opening their console in dev tools and have them screenshot the error and send it to them.
- I could go on and on...

This is why you hire a real front-end engineer to build your web app instead of the cheapest contractors you can find from Ukraine.

string excuses[]={
"it's not a bug it's a feature",
"it worked on my machine",
"i tested it and it worked",
"its production ready",
"your browser must be caching the old content",
"that error means it was successful",
"the client fucked it up",
"the systems crashed and the code got lost" ,
"this code wont go into the final version",
"It's a compiler issue",
"it's only a minor issue",
"this will take two weeks max",
"my code is flawless must be someone else's mistake",
"it worked a minute ago",
"that was not in the original specification",
"i will fix this",
"I was told to stop working on that when something important came up",
"You must have the wrong version",
"that's way beyond my pay grade",
"that's just an unlucky coincidence",
"i saw the new guy screw around with the systems",
"our servers must've been hacked",
"i wasn't given enough time",
"its the designers fault",
"it probably won't happen again",
"your expectations were unrealistic",
"everything's great on my end",
"that's not my code",
"it's a hardware problem",
"it's a firewall issue",
"it's a character encoding issue",
"a third party API isn't responding",
"that was only supposed to be a placeholder",
"The third party documentation is wrong",
"that was just a temporary fix.",
"We outsourced that months ago.","
"that value is only wrong half of the time.",
"the person responsible for that does not work here anymore",
"That was literally a one in a million error",
"our servers couldn't handle the traffic the app was receiving",
"your machines processors must be too slow",
"your pc is too outdated",
"that is a known issue with the programming language",
"it would take too much time and resources to rebuild from scratch",
"this is historically grown",
"users will hardly notice that",
"i will fix it" };

Things have been a little too quiet on my side here, so its time for an exciting new series:

practiseSafeHex's new life as a manager.

Episode 1: Dealing with the new backend team

It's great to be back folks. Since our last series where we delved into the mind numbing idiocy of former colleagues, a lot has changed. I've moved to a new company and taken a step up as a Dev manager / Tech lead. Now I know what you are all thinking, sounds more dull and boring right? Well it wouldn't be a practiseSafeHex series if we weren't ...

<audience-shouting>
DEALING! ... WITH! ... IDIOTS!
</audience-shouting>

Bingo! so lets jump right in and kick us off with a good one.

So for the past few months i've been on an on-boarding / fact finding / figuring out this shit-storm, mission to understand more about what it is i'm suppose to do and how to do it. Last week, as part of this, I had the esteemed pleasure of meeting face to face with the remote backend team i've been working with. Lets rattle off a few facts to catch us all up:

- 8 hour time difference to me
- No documentation other than a non-maintained swagger doc
- Swagger is reporting errors and several of the input models are just `Type: String`
- The one model that seems accurate, has every property listed as optional, including what must be the primary key
- Properties go missing and get removed at the drop of a hat and we are never told.
- First email I sent them took 27 days to reply, my response to that hasn't been answered so far 31 days later (new record! way to go team, I knew we could do it!!!)
- I deal directly with 2 of them, the manager and the tech lead. Based on how things have gone so far, i've nick named them:
1) Ass
2) Hole

So lets look at some example of their work:

- I was trying to test the new backend, I saw no data in QA. They said it wouldn't show up until mid day their time, which is middle of the night for us. I said we need data in our timezone and I was told: a) "You don't understand how big this system is" (which is their new catch phrase) b) "Your timezone is not my concern"

- The whole org started testing 2 days later. The next day a member from each team was on a call and I was asked to give an update of how the testing was going on the mobile side. I said I was completely blocked because I can't get test data. Backend were asked to respond. They acknowledged they were aware, but that mobile don't understand how big the system is, and that the mobile team need to come up with ideas for the backend team, as to how mobile can test it. I said we can't do anything without test data, they said ... can you guess what? ... correct "you don't understand how big the system is"

- We eventually got something going and I noticed that only 1 of the 5 API changes due on their side was done. Opened tickets. 2 days later asked them for progress and was told that "new findings" always go to the bottom of the backlog, and they are busy with other things. I said these were suppose to be done days ago. They said you can't give us 2 days notice and expect everything done. I said the original ticket was opened a month a go *sends link* ......... *long silence* ...... "ok, but you don't understand how big the system is, this is a lot of work"

- We were on a call. Product was asking the backend manager (aka "Ass") a question about a slight upgrade to the new feature. While trying to talk, the tech lead (aka "Hole") kept cutting everyone off by saying loudly "but thats not in scope". The question was "is this possible in the future" and "how long would it take", coming from management and product development. Hole just kept saying "its not in scope", until he was told to be quiet by several people.

- An API was sending down JSON with a string containing a message for the user with 2 bits of data inside it. We asked for one of those pieces to also come down as a property as the string can change and we needed it client side. We got that. A few days later we found an edge case and asked for the second piece of data to be a property too. Now keep in mind, they clearly already have access to them in order to make the string. We were told "If you keep requesting changes like this, you are going to delay the release of the backend by up to 2 weeks"

Yes folks, there you have it, the most minuscule JSON modifications, can delay your release by up to 2 weeks ........ maybe I should just tell product, that they don't understand how big the app is, and claim we can't build it on our side? Seems to work for them

Thats all the time we have for today,

Tune in for more, where we'll be looking into such topics as:

- If god himself was an iOS developer ... not
- Why automate when you can spend all day doing it by hand
- Its more time-efficient to just give everything a story point of 5
- Why waste time replying to emails ... when you can do nothing instead

See you all next week,
practiseSafeHex

Some of Google's API documentation..

Currently on an internship, PHP mostly, little bit of Python and the usual web stuff, and I just had the BEST FUCKING DAY EVER.

Wake up and find out I'm out of coffee, oh boy here we go.

Bus leaves 10 minutes late, great gonna miss my train.

Trains just don't wanna ride today, back in a bus I go, what's normally a 10 minute train travel is now a 90 minute bus ride.

Arrive at internship, coffee machine is broke, non problem, I'll just lose it slowly.

NOW HERE COMES THE FUCKING GOOD PART!!

Alright, so I'm working on a CMS that can be used just about on any device you want, mobile or desktop, it's huge, billion's of rows of scientific data. Very specific requirements and low error margins. Now, yesterday I was really enjoying myself here until today, Project manager walks in, comes to my desk and hands me a Samsung Gear S3, an Apple watch and some cheap knockoff. He tells me that before the Friday deploy, THE ENTIRE CMS SHOULD WORK ON THOSE WATCHES!

I mean, don't get me wrong, I like a challenge but it's just not right, I mean, I'm still not sure what the right way to handle tables on phones is, but smart watches, just no. Besides that, I've never worked with any Apple devices, let alone WatchOs, nor have I worked with Android Wear.

Also, Project Manager is a total dickhead, he's the kinda guy that prefers a light theme, doesn't clean up his code, writes 0 documentation for an API, 1 space = tab, pure horror.

So after almost flipping my desk, I just called my school coach to announce I'm leaving this internship. After a brief explanation he decides to come over, and guess what, according to the Project Manager I wasn't supposed to do that, I was supposed to test if it would be possible.

FUCKING ASSFUCKFACE

I've had my share of incompetent coworkers. In order of appearance:

1. A full stack dev. This one guy never, and I mean NEVER uses relationships in their tables. No indexing, no keys, nada. Couple of months later he was baffled why his page took ten seconds to load.

2. The same dev as (1). Requirement was to create some sort of "theme" feature for a web app. Hacked it by putting !important all over the place.

3. The same dev again. He creates several functions that if the data exists returns a view, and if it doesn't, "echo '0'". No, not return 0 or return false or anything, but fucking echo. This was PHP. If posted a rant about this a few months ago.

4. Same dev, has no idea what clean code is. No, not just reusable functions, he doesn't even get indenting right. Some functions have 4 spaces, some 2 tabs, some 6 tabs! And this is inside the same function. God wait until he tries Python...

5. Same dev now suggests that he become the PM. GM approves (very small company). Assigns me to travel to a client since they needed "technical assistance about the API". Was actually there to lead a UAT session.

Intermezzo, that guy went from fullstack dev to PM to sales (yes, one who calls clients to offer products) to business development, to product analyst in the span of two years.

After a year and a half there, I quit.

6. New company, a "QA engineer" who also assumes the role as the product owner. Does absolutely no tests other than "functional tests" in which he NEVER produces any form of documentation. Not even a set of test cases. He goes by "intuition".

7. Same guy as (6), hands me requirements for a feature. By "hands me" I mean he did that verbally. No spec documents, no slack chat, no Trello card. I ended up writing it as a card in Trello. Fast forward to the due date, he flips out because that wasn't what he wanted. Showed him the card. He walked away, without thinking of a solution how this mess should be handled.

Despite all this, I really don't want him (6&7) to leave the company. The devs get really stressed out at this job and he does make a really good person to laugh with/at.

You know side projects? Well I took on one. An old customer asked to come and take over his latest startups companys tech. Why not, I tought. Idea is sound. Customer base is ripe and ready to pay.

I start digging and the Hardware part is awesome. The guys doing the soldering and imbedded are geniuses. I was impressed AF.

I commit and meet up with CEO. A guy with a vision and sales orientation/contacts. Nice! This shit is gonna sell. Production lines are also set.

Website? WTF is this shit. Owner made it. Gotta give him the credit. Dude doesn't do computers and still managed to online something. He is still better at sales so we agree that he's gonna stick with those and I'll handle the tech.

I bootstrap a new one in my own simplistic style and online it. I like it. The owner likes it. He made me to stick to a tacky logo. I love CSS and bootstrap. You can make shit look good quick.

But I still don't have access to the soul of the product. DBs millions rows of data and source for the app I still behind the guy that has been doing this for over a year.

He has been working on a new version for quite some time. He granted access to the new versions source, but back end and DB is still out of reach. Now for over month has passed and it's still no new version or access to data.

Source has no documentation and made in a flavor of JS frame I'm not familiar with. Weekend later of crazy cramming I get up to speed and it's clear I can't get further without the friggin data.

The V2 is a scramble of bleeding edge of Alpha tech that isn't ready for production and is clearly just a paid training period for the dev. And clearly it isn't going so well because release is a month late. I try to contact, but no reaction. The owner is clueless.

Disheartening. A good idea is going to waste because of some "dev" dropping a ball and stonewalling the backup.

I fucking give him till the end of the next week until I make the hardware team a new api to push the data and refactor the whole thing in proper technologies and cut him off.

Please. If you are a dev and don't have the time to concentrate on the solution don't take it on and kill off the idea. You guys are the key to making things happening and working. Demand your cut but also deserve it by delivering or at least have the balls to tell you are not up for it.

First rant here. Long, but please bear with me:

So after slogging my ass off in various early stage startups for over 4 years and keeping up with the almost non-existent development process, I joined an organisation which has some of the brightest and smartest minds I have had the pleasure to work with.

Mind you, this company is the market leader in it's field and has a 50+ people in it's tech team and the quality of work is pretty impressive.

Now for this week's sprint, I was asked to develop a feature which already exists on the Android app and they want to introduce in the iOS app too. The backend APIs are all in place and all I need to do is build it with virtually no dependency. My PM asks me to start with the UI and ask the backend dev for the API list whenever I need them.This is where the story turns.

For my first API, I go to the backend dev and ask him to share the API documentation and he looks at me as if I have asked him to dance the fucking cha cha. With a straight face he tells me that, 'The organisation doesn't maintain any kind of documentation for it's APIs.' Now this really shocks me. Even in a 5 men tech teams I have worked on, we have always maintained a spec doc for the APIs and this is a company which is known for it's tech practices.

Being the new guy I compose myself and ask if they have anything for me here: Postman collection, a workflowy doc, a goddamn txt file; anything which might help me, and he laughs at my dilusion and says no.

Dejected, I ask for a way to get the APIs and I am told that there are only two ways: either I keep bothering the Android dev for the APIs(No, I don't have the access to the android repo and nor am I gonna get it) which he had worked on 4 months back or I install the prod app on my phone, and use Charles to get every fucking API which is really, really annoying.

I thought writing out this rant would make me feel better, turns out it just made me angrier. Why the fuck can't they document such an important thing!?

When your colleague, who wrote the API is on vacation, the documentation is non-existent and you are tired from reading all-day long his spaghetti code, so you are just waiting for him to show up.

API documentation in pdf seems like a sure way to spread out dated info about your API.

Every step of this project has added another six hurdles. I thought it would be easy, and estimated it at two days to give myself a day off. But instead it's ridiculous. I'm also feeling burned out, depressed (work stress, etc.), and exhausted since I'm taking care of a 3 week old. It has not been fun. :<

I've been trying to get the Google Sheets API working (in Ruby). It's for a shared sales/tracking spreadsheet between two companies.

The documentation for it is almost entirely for Python and Java. The Ruby "quickstart" sample code works, but it's only for 3-legged auth (meaning user auth), but I need it for 2-legged auth (server auth with non-expiring credentials). Took awhile to figure out that variant even existed.

After a bit of digging, I discovered I needed to create a service account. This isn't the most straightforward thing, and setting it up honestly reminds me of setting up AWS, just with less risk of suddenly and surprisingly becoming a broke hobo by selecting confusing option #27 instead of #88.

I set up a new google project, tied it to my company's account (I think?), and then set up a service account for it, with probably the right permissions.

After downloading its creds, figuring out how to actually use them took another few hours. Did I mention there's no Ruby documentation for this? There's plenty of Python and Java example code, but since they use very different implementations, it's almost pointless to read them. At best they give me a vague idea of what my next step might be.

I ended up reading through the code of google's auth gem instead because I couldn't find anything useful online. Maybe it's actually there and the past several days have been one of those weeks where nothing ever works? idk :/

But anyway. I read through their code, and while it's actually not awful, it has some odd organization and a few very peculiar param names. Figuring out what data to pass, and how said data gets used requires some file-hopping. e.g. `json_data_io` wants a file handle, not the data itself. This is going to cause me headaches later since the data will be in the database, not the filesystem. I guess I can write a monkeypatch? or fork their gem? :/

But I digress. I finally manged to set everything up, fix the bugs with my code, and I'm ready to see what `service.create_spreadsheet()` returns. (now that it has positively valid and correctly-implemented authentication! Finally! Woo!)

I open the console... set up the auth... and give it a try.

... six seconds pass ...

... another two seconds pass ...

... annnd I get a lovely "unauthorized" response.

asjdlkagjdsk.

> Pic related.

Sometime in mid 2013 or 2014 as a junior dev I woke up to a call from my company's CEO. He informed me that the legacy system they use for order processing is down nationwide that nobody can add new orders until it's fixed and that I needed to fix it. I had been working there 6 months and was hired along with a senior dev to begin developing a web app to replace this legacy system. The senior dev had left the company two weeks earlier for a better offer so it was put on me to figure it out. I was very frank with the CEO and told him I didn't know if I could fix it and suggested he try to call the company they hired to create it. I didn't even know where the source code was let alone what the design paradigm was or whether or not there was any documentation. He said he would try figuring out who created it and give them a call and asked "As a developer you shouldn't you be able to fix this?" I just told him it wasn't that simple and left it at that.

I get to work and the CEO has discovered that the company who created the software no longer exists and I tell him he may need to find a company to consult on this if I can find the source code and if I can't find the code he might be screwed.
I found the source code in a random IT shared folder there is no source control, no documentation, no unit tests, no test environment, and it looks like nobody had touched it since 2005 or about 8 years.

Despite being completely unfamiliar with the code and the design paradigm I was able to figure out that they were validating customer addresses against an old Google geocoding API that was shutdown the day before and the lack of response was killing the application. I fixed the issue and warned the CEO before deployment that I wasn't able to test but he said to go ahead and thankfully all went well.

"I want my API to return insults as error messages if they forget shit"

Uh no, I prefer helping them out by writing proper documentation than sending a giftbox with me flipping them off like Linus Fucking Torvalds for their spaghetti usage of your API

A programmer once explained Nietzsche like this:
A long time ago, god created the world, but forgot to leave a developer documentation, thus the whole world was like legacy code...
And humans are like the end user of this world, and some among them spent time studying it, using the Moral API, hoping to get a result of "http 200 ok" from our world for the peace of mind. But the true operation of this world is still yet unknown...
As time passes, humans begin to find that in Moral API, good and evil are two base classes, and all the other moral properties (like ethic, justice and stuff) are just other classes based on those two classes through multiple inheritance.
One day, when programmer Nietzsche was observing the world's runtime behavior, he came up with a question:
"Did god really use good and evil as base classes? Could it be that they are actually derived classes?"
Most of the world is currently in the favor of mankind, and god must've wrote individual user cases for it's end users, he thought.
This made Nietzsche thinking: if end users are considered into two cases: the strong and the weak, how would the world be designed base on its user story?
Let's think about the strong, they can bully the weak as they please, and there's nothing the weak can do to stop them. In this case whether the Moral API exists or not doesn't fulfill the need of the strong.
But when it comes to the weak, Nietzsche thinks that because the weak cannot fight the strong, they need to belittle bullying and praise the strong for being nice. When the weak does this, it covers their powerless state to some extent, making them look somehow equal to the strong by being capable of commenting.
God might have coded the Moral API to fit the weak's requirement, also adding some public methods for the weak to comment on the strong. If the strong takes care of the weak, they call him nice and good, if the strong bullies people, they call him bad and evil.
That's when Nietzsche realized, that good and evil are both derived classes from the weak, and the base class should be the strong and the weak.
Then he started a series of studies about the Moral API, and got some thesis that persuaded lots of other end users...

I had to open the desktop app to write this because I could never write a rant this long on the app.

This will be a well-informed rebuttal to the "arrays start at 1 in Lua" complaint. If you have ever said or thought that, I guarantee you will learn a lot from this rant and probably enjoy it quite a bit as well.

Just a tiny bit of background information on me: I have a very intimate understanding of Lua and its c API. I have used this language for years and love it dearly.

[START RANT]

"arrays start at 1 in Lua" is factually incorrect because Lua does not have arrays. From their documentation, section 11.1 ("Arrays"), "We implement arrays in Lua simply by indexing tables with integers."

From chapter 2 of the Lua docs, we know there are only 8 types of data in Lua: nil, boolean, number, string, userdata, function, thread, and table

The only unfamiliar thing here might be userdata. "A userdatum offers a raw memory area with no predefined operations in Lua" (section 26.1). Essentially, it's for the API to interact with Lua scripts. The point is, this isn't a fancy term for array.

The misinformation comes from the table type. Let's first explore, at a low level, what an array is. An array, in programming, is a collection of data items all in a line in memory (The OS may not actually put them in a line, but they act as if they are). In most syntaxes, you access an array element similar to:

array[index]

Let's look at c, so we have some solid reference. "array" would be the name of the array, but what it really does is keep track of the starting location in memory of the array. Memory in computers acts like a number. In a very basic sense, the first sector of your RAM is memory location (referred to as an address) 0. "array" would be, for example, address 543745. This is where your data starts. Arrays can only be made up of one type, this is so that each element in that array is EXACTLY the same size. So, this is how indexing an array works. If you know where your array starts, and you know how large each element is, you can find the 6th element by starting at the start of they array and adding 6 times the size of the data in that array.

Tables are incredibly different. The elements of a table are NOT in a line in memory; they're all over the place depending on when you created them (and a lot of other things). Therefore, an array-style index is useless, because you cannot apply the above formula. In the case of a table, you need to perform a lookup: search through all of the elements in the table to find the right one. In Lua, you can do:

a = {1, 5, 9};
a["hello_world"] = "whatever";

a is a table with the length of 4 (the 4th element is "hello_world" with value "whatever"), but a[4] is nil because even though there are 4 items in the table, it looks for something "named" 4, not the 4th element of the table.

This is the difference between indexing and lookups. But you may say,

"Algo! If I do this:

a = {"first", "second", "third"};
print(a[1]);

...then "first" appears in my console!"

Yes, that's correct, in terms of computer science. Lua, because it is a nice language, makes keys in tables optional by automatically giving them an integer value key. This starts at 1. Why? Lets look at that formula for arrays again:

Given array "arr", size of data type "sz", and index "i", find the desired element ("el"):

el = arr + (sz * i)

This NEEDS to start at 0 and not 1 because otherwise, "sz" would always be added to the start address of the array and the first element would ALWAYS be skipped. But in tables, this is not the case, because tables do not have a defined data type size, and this formula is never used. This is why actual arrays are incredibly performant no matter the size, and the larger a table gets, the slower it is.

That felt good to get off my chest. Yes, Lua could start the auto-key at 0, but that might confuse people into thinking tables are arrays... well, I guess there's no avoiding that either way.

And the award for the best API documentation goes to...

Microsoft!

“Our code is our documentation - it’s produced in such a way as to be explanatory, logical and clear, and annotated if/where needed”

Really?? That's the reply you give me when I asking API documentation for handover ?

it's funny, how doing something for ages but technically kinda the wrong way, makes you hate that thing with a fucking passion.

In my case I am talking about documentation.

At my study, it was required to write documentation for every project, which is actually quite logical. But, although I am find with some documentation/project and architecture design, they went to the fucking limit with this shit.

Just an example of what we had to write every time again (YES FOR EVERY MOTHERFUCKING PROJECT) and how many pages it would approximately cost (of custom content, yes we all had templates):

Phase 1 - Application design (before doing any programming at all):
- PvA (general plan for how to do the project, from who was participating to the way of reporting to your clients and so on - pages: 7-10.
- Functional design, well, the application design in an understandeable way. We were also required to design interfaces. (Yes, I am a backender, can only grasp the basics of GIMP and don't care about doing frontend) - pages: 20-30.
- Technical design (including DB scheme, class diagrams and so fucking on), it explains it mostly I think so - pages: 20-40.

Phase 2 - 'Writing' the application
- Well, writing the application of course.
- Test Plan (so yeah no actual fucking cases yet, just how you fucking plan to test it, what tools you need and so on. Needed? Yes. but not as redicilous as this) - pages: 7-10.

- Test cases: as many functions (read, every button click etc is a 'function') as you have - pages: one excel sheet, usually at least about 20 test cases.

Phase 3 - Application Implementation
- Implementation plan, describes what resources will be needed and so on (yes, I actually had to write down 'keyboard' a few times, like what the actual motherfucking fuck) - pages: 7-10.
- Acceptation test plan, (the plan and the actual tests so two files of which one is an excel/libreoffice calc file) - pages: 7-10.
- Implementation evalutation, well, an evaluation. Usually about 7-10 FUCKING pages long as well (!?!?!?!)

Phase 4 - Maintaining/managing of the application
- Management/maintainence document - well, every FUCKING rule. Usually 10-20 pages.
- SLA (Service Level Agreement) - 20-30 pages.
- Content Management Plan - explains itself, same as above so 20-30 pages (yes, what the fuck).
- Archiving Document, aka, how are you going to archive shit. - pages: 10-15.

I am still can't grasp why they were surprised that students lost all motivation after realizing they'd have to spend about 1-2 weeks BEFORE being allowed to write a single line of code!

Calculation (which takes the worst case scenario aka the most pages possible mostly) comes to about 230 pages. Keep in mind that some pages will be screenshots etc as well but a lot are full-text.

Yes, I understand that documentation is needed but in the way we had to do it, sorry but that's just not how you motivate students to work for their study!

Hell, students who wrote the entire project in one night which worked perfectly with even easter eggs and so on sometimes even got bad grades BECAUSE THEIR DOCUMENTATION WASN'T GOOD ENOUGH.

For comparison, at my last internship I had to write documentation for the REST API I was writing. Three pages, providing enough for the person who had to, to work with it! YES THREE PAGES FOR THE WHOLE MOTHERFUCKING PROJECT.

This is why I FUCKING HATE the word 'documentation'.

A colleague and I spent a month building a Shopify app that allows merchants to give customers store credit.

Since Shopify's API is so limited, we were forced to augment it's functionality with a Chrome extension.

Now before you go throwing full wine bottles at your screen because of how wrong and disgusting that is, note that Shopify's official documentation recommends 5 different extensions to augment functionality in their admin panel, so as gross as it is, it seems to be the Shopify way...

Today we got a reply from their review team. They won't accept the app because it requires a Chrome extension to work properly and that is a security risk.

Are you fucking kidding me? So I guess Shopify is exempt from their own security standards. Good to know.

Not to mention the plethora of published apps that require a staff account's username and password to be provided in plain text upon setup so it can spoof a login and subsequent requests to undocumented endpoints.

Fuck you and your "security standard" Shopify!

I wrote a database migration to add a column to a table and populated that column upon record creation.
But the code is so freaking convoluted that it took me four days of clawing my eyes out to manage this.
BUT IT'S FINALLY DONE.
FREAKING YAY.

Why so long, you ask? Just how convoluted could this possibly be? Follow my lead ~

There's an API to create a gift. (Possibly more; I have no bloody clue.)
I needed the mobile dev contractor to tell me which APIs he uses because there are lots of unused ones, and no reasoning to their naming, nor comments telling me what they do.

This API takes the supplied gift params, cherry-picks a few bits of useful data out (by passing both hashes by reference to several methods), replaces a couple of them with lookups / class instances (more pass-by-reference nonsense). After all of this, it logs the resulting (and very different) mess, and happily declares it the original supplied params. Utterly useless for basically everything, and so very wrong.

It then uses this data to call GiftSale#create, which returns an instance of GiftSale (that's actually a Gift; more on that soon).

GiftSale inherits from Gift, and redefines three of its methods.

GiftSale#create performs a lot of validations / data massaging, some by reference, some not. It uses `super` to call Gift#create which actually maps to the constructor Gift#initialize.

Gift#initialize calls Gift#pre_init (passing the data by reference again), which does nothing and returns null. But remember: GiftSale inherits from Gift, meaning GiftSale#pre_init supersedes Gift#pre_init, so that one is called instead. GiftSale#pre_init returns a Stripe charge object upon success, or a Gift (and a log entry containing '500 Internal') upon failure. But this is irrelevant because the return value is never actually used. Pass by reference, remember? I didn't.

We're now back at Gift#initialize, Rails finally creates a Gift object using the args modified [mostly] in-place by all of the above.

Another step back and we're at GiftSale#create again. This method returns either the shiny new Gift object or an error string (???), and the API logic branches on its type. For further confusion: not all of the method's returns are explicit, and those implicit return values are nested three levels deep. (In Ruby, a method will return the last executed line's return value automatically, allowing e.g. `def add(a,b); a+b; end`)

So, to summarize: GiftSale#create jumps back and forth between Gift five times before finally creating a Gift instance, and each jump further modifies the supplied params in-place.

Also. There are no rescue/catch blocks, meaning any issue with any of the above results in a 500. (A real 500, not a fake 500 like last time. A real 500, with tragic consequences.)

If you're having trouble following the above... yep! That's why it took FOUR FREAKING DAYS! I had no tests, no documentation, no already-built way of testing the API, and no idea what data to send it. especially considering it requires data from Stripe. It also requires an active session token + user data, and I likewise had no login API tests, documentation, logging, no idea how to create a user ... fucking hell, it's a mess.)

Also, and quite confusingly:
There's a class for GiftSale, but there's no table for it.
Gift and GiftSale are completely interchangeable except for their #create methods.

So, why does GiftSale exist?
I have no bloody idea.
All it seems to do is make everything far more complicated than it needs to be.

Anyway. My total commit?
Six lines.
IN FOUR FUCKING DAYS!

AHSKJGHALSKHGLKAHDSGJKASGH.

Writing more infrastructure than product.

Look, my application requests and transforms data from a single external API endpoint, it's just one GET request...

But I made an intelligent response caching middleware to prevent downtime when the parent API goes down, I made mocks and tests for everything, the documentation is directly generated from the code and automatically hosted for every git branch using hooks, responses are translated into JSONschema notation which automatically generate integration tests on commit, and the transformations are set up as a modular collection of composable higher order lenses!

Boss: Please use less amphetamine.

Worked 8 hours on a feature to send attachments from our system (A) to another (B) via B's API. Perfect code, yet I couldn't make it work. B's API has full and extensive documentation for said feature. Contacted B to ask about it, got reply: "Oh yeah - we havent enabled that yet but thought it was handy to have it ready in the docs"

FML

2 years into polytechnic I got my 1st big project as a subcontractor doing Symbian. No need to tell the company I presume.

Anyways, I was brought into the project just couple weeks before holiday season started. My Symbian programming experience was just the basics from school. 1st day I was crapping my pants out of anxiety. I pretty much didn't understand anything what my project manager or teammates were telling, so I just wrote EVERYTHING down on paper and recorded all the meetings to my laptop.

My job was to implement a very big end to end SDK feature. Basically from API through Symbian OS through HAL to other OS and into its subsystem. Nice job for a beginner :/

As the holidays were starting we had just drafted out the specification (I don't know how, because I didn't understand much of what was going on) and I got a clear mission from team lead. Make a working prototype of the feature during the time everybody else was on vacation.

"No problemos, I can do it" I BS'd myself and the team lead.

First 2 weeks I just read documentation, my notes and internal coding tutorials over and over again. I produced maybe couple of lines of usable code. I stayed at the office as late as I dared without seeming to obvious that I had no clue what I was doing. After the two weeks of staying late and seeing nightmares every night I had a sudden heureka moment. Code that I was reading started to make sense. Okay, still 2 weeks more until my teammates come back.

Next 2 weeks were furious coding and I got better every day. I even had time to refactor some of my earlier code so that quality was consistent.

Soooo, holidays are over and my team leader and collagues are very interested with my progress. "You did very well. Much better than expected. Prototype is working with main use case implemeted. You must have quite high competence to do this so well..."

"Well...I did have to refactor some stuff, so not 10/10"

I didn't say a word of my super late nights, anxiety and total n00biness.

Pretty much finished "like a boss". After that I was on the managers wanted list and they called me to ask if I had the time work on their projects.

Fake it, crap your pants, eat your crap and turn into diamonds and then you make it.

PS. After Symbian normal C++ and almost any other language has been a breeze to learn.

FUCKING TELEGRAM FUCK YOU STAY IN YOUR FUCKING API DOCUMENTATION AND STOP FUCKING TESTING YOUR SHIT ON A PRODUCTION SYSTEM WHY WOULD YOU DO THAT FUCK OFF WHY AM I EVEN DEVELOPING SHIT FOR YOUR PLATFORM ANYMORE WHEN FOLLOWING YOUR DOCUMENTATION LEADS TO FUCKING ERRORS AND WE HAVE TO DECOMPILE AND REVERSE ENGINEER YOUR FUCKING "OPEN SOURCE" APPS BECAUSE YOU DONT EVEN BOTHER TO FUCKING UPDATE THE SOURCE CODE ONCE A YEAR WHAT THE FUCK

Thank you for your attention

I'll point names today

Boss: Quick! The Xero integration is not working anymore!
Xero Documentation: place your client secret in the HEADERS
Me: * places client secret in headers *
Xero API: Bad Request!
Me:
*re-reads documentation*
*creates new client secret*
*1 hour of trying*
Hmmmm
* places client secret in request body, not in headers *
Xero API: Ok!

UPDATE YOUR DOCUMENTATION
TELL US ABOUT IT IN THE CHANGELOGS

!drunk (yet)

It's whiskey and code tonight!
(Whiskey because I couldn't get to my rum. annoyed face.)

Why? Because rum is so much better. duh.

More seriously: My boss has thrown me every single one his current tasks and is refusing to answer simple questions about them, such as "oh, so you already know about this bug; what's the cause?" or "how do i test this once i've fixed it?" or "where the fuck are you?"

and I'm also getting lots of bugs from other people. They're all basically categorized "urgent, please fix immediately" but should instead be categorized "super-boring and not-at-all-important, and should get fixed on the off chance you happen to remember it next year". That's the best category of bug.

I just gave up on fixing a Rails pluralize bug which fits into the aforementioned category quite nicely. It's returning "2x round of golves" -- which is hilarious and I might leave it in just for the amusement. But now it's back to fighting with ActionCable! Everything has been getting in the way of me finishing that. I'm about to start biting.

Speaking of ActionCable, it turns out my code wasn't wrong after all (have I said that yet?). Since the official documentation and examples suck, I've been digging through the (generated) javascript source and working my way backwards to learn how to use it. I cleaned up my code a little, but it was still correct. The reason nothing is working correctly is that API Guy gave me broken code. ...Again! Go figure. So I'll be rewriting that today. or tomorrow. (Whiskey, remember?)

I also have some lovely netcode to debug and fix. So totally not looking forward to that. The responses are less bloody reliable than my boss's code ffs. *grumble grumble*

Wondering why there isn’t API documentation.

Yesterday I received the API documentation from an external company. Over half of the endpoints are either wrong or send invalid data and even the given test requests are fucking failing.
It's a nightmare. We have to finish a website until friday and that company did nothing for 2 months and now we have 2 days left.
The sheer incompetence is too damn high.
My boss said it would have been much better if we had implemented the API on our own. Damn right.

Real friends write API documentation

Published a well documented and tested API with project examples for basic use cases

- "Yeah we didn't use yours because we didn't know how to use it"
- "Did you look at the documentation or code examples?"
- "What where?"
- "In the repo you just cloned"
- "Yeah no <random guy> found a hacky way of doing what we want, his thing just works"
- "I..."

Task:
- Replace a 4 year old PHP API.
Old API:
- PHP script writing PHP scripts to /var/www/ for every endpoint needed
- Answers everthing with 200 (not even 404)
DB:
- MySQL 5.6
- ~ 1000 Tables, NO FUCKING FK's
Documentation:
- "Wasn't worth the effort"
New API:
- Not allowed to behave any different
.
.
.
😭

After returning back from the company we were purchasing a new phone system (hardware+software, $100K+, kind of a big deal)
VP: “I need the new phone system software integration for our CRM by next week. I need to demo the system for the other VPs”
Me: “No problem. Were you able to get their API like I asked?”
VP: “Salesman didn’t know for sure what that was, but he said all the developer software documentation is on their site.”
Me: “Did he give you a URL? Their main site is all marketing mumbo-jumbo. I assume there is another one specific for developers.”
VP: “Yea, he might have said something, but I don’t understand why you need it. The salesman said the integration would be seamless. He showed me several demos.”
Me: “No, I mean I need to know, is the API a full client install? a simple dll? is this going to be a web service integration? How will I know what to program against?”
VP: “I think I heard him say something about COM? Does that sound like an API?”
Me: “It’s a start. Did he provide you anything, a disk, a flash drive, anything with the software?”
VP: “No, only thing he told me was our CRM integration would be seamless and our development team would have no problems.”
Me: “OK..OK…I get it…he’s a salesman. Is there an 1-800 number I can call? A technical support email address? Anyone technical I can reach out to?”
VP: “Probably, but I don’t understand what the problem is. I need the CRM integrated by next week. I gave the other VPs a promise we would get it done. I do not break promises.”
Me: “Wait…when are we installing the new system?”
VP: “Well, the purchase order will be cut at the end of the month’s billing cycle, the company has about a two month turnaround time to deliver and install the hardware, so maybe 3 months from now? Are you going to be able to have the integration ready for next week?”
Me: “If we won’t see any of the hardware for 3 months, what exactly am I integrating with?”
VP: “That API you wanted or whatever it is. COM…yea, it’s COM. I was told the integration would be seamless and our developers would have no problem. I don’t understand why you can’t simply write the code to make it work. Getting the hardware installed is going to be the hardest part.”
Me: “OK, so I have no documentation, we have no hardware, no software, and no idea what this ‘seamless integration’ means. I’m afraid there isn’t anything I can do right now. ”
VP: “Fine!...I’ll just have to tell the other VPs you were not able to execute the seamless integration with the CRM.”
Which he did. When the hardware+software was finally installed, they hired consultants (because I “failed”). I think the bill was in the $50K range to perform the ‘integration’ which consisted of Excel spreadsheets (no kidding). When approached with the primary CRM integration, the team needed our API documentation, a year’s development time and $300K. I was pissed off enough, and I had the API documentation, I was able to get the basic CRM integration within 3 days. When an agent receives a call, I look up the # in our database, auto-fill the form with the customer info, etc. Easy stuff when you have the documentation.
The basics worked and the VP was congratulated by ‘saving’ the company $300K. May or may not have been bonuses involved, rumors still out on that one, but I didn't see em'. Later my manager told me the VP was really ticked that I performed the integration ‘behind his back’, but because it was a success, he couldn’t fire me.

Client: So we want you to redesign the frontend for this app

Me: Ok, sounds easy enough, send me the source code and API documentation

Client: yeaaaaaah, here's the thing, we don't have the frontend source code anymore, we originally wrote it in React and then we lost the source code, we only have the bundles now

Me: ok fine, I can handle it, can I have the API doc?

Client: yeaaaaaah, here's the thing, we didn't write API docs, but we have the source code if you want

Me: fml

Hi,
I'm not a ranty person so I never actually thought I'd post anything here but here it goes.

From the beginning.
We use ancient technologies. PHP 5.2, Symfony 1.2 and a non RFC complient SOAP with NO documentation.
A year ago We've been thrown a new temporary project. An VOIP app for every OS.
That being iOS, Android, MAC, PC, Linux, Windows mobile. With a 3 month deadline. All that thrown at 4 PHP developers. The idea being that They'll take it, sign the delivery protocol, everyone happy. No more updates for the app needed. They get their funds they needed the app for and we get paid.

Fast forward to today...

Our dev team started the year with great news that We'll most likely have to create a new project. Since the amount of new features would be far greater than current feature set, we managed to finally force our boss to use newer technologies (ie. seperate backend symfony4 PHP7+/frontend react, rest api and so on). So we were ecstatic to say the least. With preestimates aimed at a minimum 3 month development period. Since we're comfortable with everything that needs to be done.
Two days later our boss came to me that one of our most annoying clients needs a new feature. Said client uses ancient version written on a napkin because They changed half of the specification 2 weaks before deadline in a software made not by a developer but some sysadmin who didn't know anything. His MVC model was practically VVV model since he even had sql queries in some views. Feature will take 3 days - fixing everything that will break in the meantime - 1-2 months.
F*** it, fine. A little overtime won't kill me.
Yesterday boss comes again... Apparently someone lost a delivery protocol for a project we ended that half a year ago. Whats even better at the time when we asked for hardware to test we never got any. When we asked about any testing enviornment - nothing. The app being SEMI-stable on everything is an overstatement but it was working on the os'es available at the time. Since the client started testing now again, it turns out that both Android app does not work on 8.1/9 and the iOS app does not work on ios12. The client obviously does not want to pay and we can do little with it without the protocol, other than rewriting the apps.
It will take months at least since all of those apps were written by people that didn't know neither the OS'es nor the languages. For example I started writing the iOS one in swift. Only to learn after half of the development time, that swift doesn't like working by C Library rules and I had to use ObjC also. With some C thrown in due to the library. 3 unknown languages, on an unknown platform in 3 months. I never had any apple device in my hand at that time nor do I intend to now. I'm astonished it worked out then. It was a clusterf**k of bad design and sticking everything together with deprecated apis and a gum. So I'll have to basically fully rewrite it.

If boss decides we'll take all those at the same time I'll f***ing jump of a bridge.

writing library code is hard.

there are sooo many details that go into writing good libraries:

designing intuitive and powerful apis
deciding good api option defaults, disallowing or warning for illegal operations

knowing when to throw, knowing when to warn/log
handling edge cases
having good code coverage with tests that doesn't suck shit, while ensuring thry don't take a hundred years to run

making the code easy to read, to maintain, robust
and also not vulnerable, which is probably the most overlooked quality.

"too many classes, too little classes"

the functions do too much it's hard to follow them
or the functions are so well abstracted, that every function has 1 line of code, resulting in code that is even harder to understand or debug (have fun drowning in those immense stack traces)

don't forget to be disciplined about the documentation.

most of these things are
deeply affected by the ecosystem, the tools of the language you're writing this in:

like 5 years ago I hated coding in nodejs, because I didn't know about linters, and now we have tools like eslint or babel, so it's more passable now

but now dealing with webpack/babel configs and plugins can literally obliterate your asshole.

some languages don't even have a stable line by line debugger (hard pass for me)

then there's also the several phases of the project:

you first conceive the idea, the api, and try to implement it, write some md's of usage examples.

as you do that, you iterate on the api, you notice that it could better, so you redesign it. once, twice, thrice.

so at that point you're spending days, weeks on this side project, and your boss is like "what the fuck are you doing right now?"

then, you reach fuckinnnnng 0.1.0, with a "frozen" api, put it on github with a shitton of badges like the badge whore you are.

then you drop it on forums, and slack communities and irc, and what do you get?

half of the community wants to ban you for doing self promotion

the other half thinks either
a) your library api is shitty
b) has no real need for it
c) "why reinvent the wheel bruh"

that's one scenario,

the other scenario is the project starts to get traction.

people start to star it and shit.
but now you have one peoblem you didn't have before: humans.

all sorts of shit:

people treating you like shit as if they were premium users.

people posting majestically written issues with titles like "people help, me no work, here" with bodies like "HAAAAAAAAAALP".

and if you have the blessing to work in the current js ecosystem, issues like "this doesn't work with esm, unpkg, cdnjs, babel, webpack, parcel, buble, A BROWSER".
with some occasional lunatic complaining about IE 4 having a very weird, obscure bug.

not the best prospect either.

It's my first week working at shithole.co (can i say that?). My boss is a micromanaging asshole who knows the bare minimum re: programming. He thinks css is hard (no offense). I'm fresh outta college. He expects me to be able to do a very complicated api development through an equally complicated authorization process. Every fucking day "Is it working yet?" [This is my first week on the job]. I don't think he's read the documentation and I don't think he understands how to. As I am typing this out I realize I'm more educated than this dumb ass. Oh, some more context. Our senior dev is working on a more important project So we don't have time to bother him? So I am doing his job for 1/10 the cost. Oh, and i'm not allowed to contact him because he is too important. When the app inevitably crashes and no one knows how to fix it. I will give them my nutsack to swallow (can i say that?).

software engineers be like “i don’t read books” then proceed to read api documentation for 4 hours straight

Using 10% React with the rest in Jquery. Importing a giant legacy CSS blob in a newly made SCSS file. Two thirds of the API documentation in docblocks, the rest in Markdown files. Half of the repositories in Github, the other half in Bitbucket. The root of every project littered with ymls and jsons and readmes of stupidly named tools no one has ever heard of.

Fuck your partial refactoring, fuck your little experiments, fuck all this half work. I'm so done with this shit. 😡

The worst that can happen to a developer is good API with bad documentation

Pro Tip: if you're building a developer REST API, don't forget to add a sample response to each endpoint. I don't want to have to test each one when I'm building my integration, I'd rather build my model in one go with the documentation displayed on a second monitor.

So a company I'm working at has this internal product. I just got employed and was put into that team.

"First task: refactor some of the code"

Alright, I start refactoring. Oh I may need to write a small class for this one. And then rewrite this a bit. And then rewrite that a bit. And then rewrite everything.

"Why are you rewriting most of my code?"

oh i would not have needed to do so if your code was not COMING OUT OF YOUR ASS and if all the teams had FREAKING PROPER API DOCUMENTATION

New project at work involving Google Nest Hubs, supervisor asks me to do the initial setup of one of them to start developing with it using its API.

I start looking throughout the documentation and realise that we need to setup a work google account in order to register the devices, pay a fee and only THEN be able to use Google's API for Smart Devices (damn, you, Google!). Supervisor is somewhat baffled by this, and in my head I'm also surprised by his reaction. I'd assume you'd research your devices before you buy them, right?

Later, he comes into the room I'm in (I'm still allowed to work on location), looks at the freshly setup Nest Hub, saying "wow, this sure is a much smaller screen than I was expecting". I mean, you did research these devices before you bought TWENTY of them. RIGHT?!

On my way to fight with this Google device-registration-API-thing now.

To be continued...

Poorly written docs.

I've been fighting with the Epson T88VI printer webconfig api for five hours now.

The official TM-T88VI WebConfig API User's Manual tells me how to configure their printer via the API... but it does so without complete examples. Most of it is there, but the actual format of the API call is missing.

It's basically: call `API_URL` with GET to get the printer's config data (works). Call it with PUT to set the data! ... except no matter what I try, I get either a 401:Unauthorized (despite correct credentials), 403:Forbidden (again...), or an "Invalid Parameter" response.

I have no idea how to do this.

I've tried literally every combination of params, nesting, json formatting, etc. I can think of. Nothing bloody works!

All it would have taken to save me so many hours of trouble is a single complete example. Ten minutes' effort on their part. tops.

asjdf;ahgwjklfjasdg;kh.

You have to integrate company A system with company B.
You look up B`s api documentation, write the necessary code, test it thoroughly. Done
__________________________________
A wild dev from B has appeared!!!
------------------------------------------------------

him > you cannot use this SDK to implement this solution. You must use a different one...

You > (coming back to him after scouring through the docs) . Ok which sdk is it then? I can't find it anywhere. Could you send it to me pls?
him > I don't kbow, my knowledge doesn't go that far. Send an email to the dev department.

After sending the email, and spending a couple of days trying to figure out which sdk was he referring to. His department answers that the sdk you should use, is the one you already used. The only one they have.

A couple of days lost, because certain smart-ass could not refrain himself from meddling in the project.

What would you do?

Note: Killing him is out of the question :)

This might actually be my first real rant.

Whatever fucking cockgoblin decided that making dynamics GP so fucking confusing needs to suck a big bag of dicks. I'm so fucking tired of having to google every damned table name and column name because nothing makes any motherfucking sense.

Am I supposed to instinctively know what PM20201 does? What data it holds? I don't mind reading documentation. But it's hard to even know where to start when the shitbird API and database are more complicated than calculating orbital fucking decay.

I am done. Fuck you gp. Fuck you and your nonsense. I guess our sales people don't get to know when an invoice was paid.

Long time ago, back in a day of Microsoft Office 95 and 97, I was contracted to integrate a simple API for a payment service provider.

They've sent me the spec, I read it, it was simple enough: 1. payment OK, 2. payment FAILED. Few hours later the test environment was up and happy crediting and debiting fake accounts. Then came the push to prod.

I worked with two other guys, we shut down the servers, made a backup, connected new provider. All looked perfectly fine. First customers were paying, first shops were sending their products... Until two days later it turned out the money isn't coming through even though all we are getting from the API is "1" after "1"! I shut it off. We had 7 conference calls, 2 meetings, 3 days of trying and failing. Finally, by a mere luck, I found out what's what.

You see, Microsoft, when you invent your own file format, it's really nice to make it consistent between versions... So that the punctuation made in Microsoft Word 97 that was supposed to start from "0" didn't start from "1" when you open the file in Microsoft Word 95.

Also, if you're a moron who edits documentation in Microsoft Word, at least export it to a fucking PDF before sending out. Please.

Thanks for not having proper api documentation, moron! 😒

We are a small size product based company. There was a change in management a year back and the new management decided to fire the entire engineering team one by one. I was hired as full time back-end developer (C++). Just after I joined they removed the last 2 engineers from the previous regime and handed over devops and Python API development to me as well.
There was no documentation for the main product which was a sophisticated piece of software. There were no comments in the code as well. I had to go through line by line (roughly 100,000 lines of code).
Then they decide to hire more devs.Turned out to be false hope. They hired interns who had no programming knowledge.
Now they got two clients who are interested in using the service. They lured them using empty promises. The product is not stable. The cloud infrastructure is not at all ready. The APIs are a mess. I don't know which one to work on.
Worst part is that there is no other technical person in the office.

I'm thinking about quitting now. I don't know why I haven't already.😖😖

I created a REST API for a customer that one of their customers should use. I sent some documentation and code samples to the "developer". He didn't understand why he should send css to the API. He obviously couldn't tell json from css...

My current project is a fucking nightmare.

It started in 2007, using a solution developed by an Indian company due to outsourcing (aka low-quality code).

It's running on Java 7 on the back-end and its front-end side is pure Javascript files. There are thousands of little .js files everywhere, no documentation, no comments, differents coding styles, outdated API that were already outdated at the time, mixed oop and procedural.
Not even when I started coding, I wrote something so horrible.

Yo, it's a clusterfuck and I just wanna get drunk.

Update log: performance improve, API rewritten, fixed all bugs reported, new features implemented, general cleanup of code, documentation and comments update
Feedback: love the new background colour!
😞

Got pretty peeved with EU and my own bank today.

My bank was loudly advertising how "progressive" they were by having an Open API!

Well, it just so happened I got an inkling to write me a small app that would make statistics of the payments going in and out of my account, without relying on anything third-party. It should be possible, right? Right?

Wrong...

The bank's "Open API" can be used to fetch the locations of all the physical locations of the bank branches and ATMs, so, completely useless for me.

The API I was after was one apparently made obligatory (don't quote me on that) by EU called the PSD2 - Payment Services Directive 2.

It defines three independent APIs - AISP, CISP and PISP, each for a different set of actions one could perform.

I was only after AISP, or the Account Information Service Provider. It provides all the account and transactions information.

There was only one issue. I needed a client SSL certificate signed by a specific local CA to prove my identity to the API.

Okay, I could get that, it would cost like.. $15 - $50, but whatever. Cheap.

First issue - These certificates for the PSD2 are only issued to legal entities.

That was my first source of hate for politicians.

Then... As a cherry on top, I found out I'd also need a certification from the local capital bank which, you guessed it, is also only given to legal entities, while also being incredibly hard to get in and of itself, and so far, only one company in my country got it.

So here I am, reading through the documentation of something, that would completely satisfy all my needs, yet that is locked behind a stupid legal wall because politicians and laws gotta keep the technology back. And I can't help but seethe in anger towards both, the EU that made this regulation, and the fact that the bank even mentions this API anywhere.

Seriously, if 99.9% of programmers would never ever get access to that API, why bother mentioning it on your public main API page?!

It... It made me sad more than anything...

Arghhhh!

The screen I'm looking at that is supposed to be the documentation portal for an API I need to consume :(

My FAVORITE bugs are those in someone ELSE's code that MY code depends on. Like an API that won't respond correctly when I FOLLOW THE DOCUMENTATION EXACTLY. 😐

I give MS a lot of cr@p for terrible API documentation, but even Google's API docs are pretty terrible to read through.

Seriously, guys... Your docs shouldn't read like an endless page of search results.

Ok so I've been working on this bug for the past four days, fucking non-stop. I wanted to fucking die, was wishing I could just "pkill -f mylife". I tried fucking everything, did what the documentation told me to, stack overflow, tried different versions of the API, read through more lines of documentation than lines in the bible, to no avail. Start comparing screenshots of error logs from the past four days, notice that I started getting a line saying that it's connecting to the config file in a different location from default. I realize that the config file does not match the config file provided by the package installed, so I switch it to the default location. IT FUCKING WORKED, I've tested it nearly 10 times now and I am still in disbelief. It was a rollercoaster of emotions fixing the bug but now I'm just smiling like a fool in my chair at work now.

Becoming a High Reputation Stackoverflow Master

Can work like this:
1. Look for questions like "How do I add a value to a list"
2. Post "Use list.Add(x)" faster than any of the 20 expected answers that will be written for this question
3. Become accepted solution
4. Get 100 up votes as more people unaware of API documentation come across your answer

Sometimes answers and questions are so trivial you wonder how this would be upvoted by anyone ever.

sooooooooo for my current graduate class we were to use the MVC pattern to build an IOS application(they preferred it if we did an IOS application) or if you didn't have an Apple computer: an Android application.

The thing is, they specified to use Java, while in their lectures and demos they made a lot of points for other technologies, hybrid technologies, such as React Cordova, all that shit, they even mentioned React Native and more. But not one single mention of Kotlin. Last time I tried my hand at Android development was way before Kotlin, it was actually my first major development job: Mobile development, for which we used Obj C on the IOS part and well, Java on the Android part.

As some of you might now, I rarely have something bad to say about a tech stack(except for VBA which I despise, but I digress) and I love and use Java at work. But the Android API has always seem unnecessarily complex for my taste, because of that, when I was working as a mobile development I dreaded every single minute in which I had to code for Android, Google had a great way to make people despise Java through their Android API. I am not saying it is shit, I am not saying it is bad, I just-dont-like-it.

Kotlin, proves a superior choice in my humble opinion for Android development, and because the language is for retards, it was fairly easy for me to pick it up in about 2 hours. I was already redesigning some of my largest Spring applications using half the code and implemented about 80% of the application's functionality in less than 3 hours(login, fragment manipulation, permissions, bla bla) and by that time I started to wonder if the app built on Kotlin would be ok. And why not? If they specifically mentioned and demonstrated examples using Swift, then surely Kotlin would be fine no? Between Kotlin and Java it is easy to see that kotlin is more similar to Swift than Java. So I sent an email. Their response: "I am sorry, but we would much rather you stick with the official implementations for Android, which in this case is Java for the development of the application"

I was like 0.o wat? So I replied back sending links and documentation where Google touted Kotlin as the new and preferred way to develop Android applications, not as a second class citizen of the platform, but as THE preferred stack. Same response.

Eventually one of the instructors reflected long enough on it to say that it was fine if I developed the application in Kotlin, but they advised me that since they already had grading criteria for the Java program I had to redo it in Java. It did not took me long really, once I was finished with the Kotlin application I basically rewrote only a couple of things into Java.

The end result? I think that for Android I still greatly prefer Kotlin. Even though I am not the biggest fan of Kotlin for anything else, or as my preferred language in the JVM.

I just.......wish....they would have said something along the lines of: "Nah fam please rewrite that shit for Java since we don't have grading criterias in place for Kotlin, sorry bruh, 10/10 gg tho" instead of them getting into an email battle with me concerning Kotlin being or not being the language to use in Android. It made me feel that they effectively had no clue what they were talking about and as such not really capable of taking care of students on a graduate level program.

Made me feel dirty.

Looks like a start of a great day !!

The company I am currently working for is partnering with another startup. Nothing special about that. We should integrate their API into our system. I wasn't involved in the process when it came to checking there API and if it would work with our Systems. The Person who did that already left the company so I was left behind with some internal documentation. In that Documentation is already written that API is basically trash....

After I started integrating the API I found more and more flaws in the design. They are not sending any responses that would help, when a param is missing or the authentication isn't correct, only 500's . I got some documentation from the partner company so i thought it will be fine as long as the Documentation would be accurate. Turns out the documentation isn't even close to be up to date. Wrong content types wrong endpoints, wrong naming. Basically we could not work with that. We shortly contacted the partner Company. After a few WEEKS we got a response that they updated the Documentation what was right but still not everything was correct. At this point I lost my mind. I researched a little bit about them, the company is founded from 2 young people who basically came strait out of the University and doest have any experience or idea how to build an API. I investigated a little bit there websites.

They have an Admin panel on the base domain from their API but it is only accessible via HTTP. Like WTF , They use HTTP for an Admin Panel this must be a joke right?

They use Cloudflare without a HTTP to HTTPS redirection ???

I really had not that much time to research in there website but if I find these things in 5 minutes I don't want to know what I can find in like an hour.

At the end we will still use them as partners because surprise surprise our company already sold the product that uses their API.

I know that I will be the person who has to help fixing this shit when it breaks and it will break 1000% JUST FUCK THIS SHIT. FUCK THE PARTNER COMPANY. FUCK THERE API.

Just released version 1 of my first API! For this project I did everything the way I wanted to, no shortcuts! I documented the shit out of every endpoint and parameter. Everything is throughly tested and it’s dockerized. I also have metrics for each endpoint (with Grafana in the frontend, which I love) as well as alerts in case it would go down for some reason.

I prepared all of this before deploying it out into the wild and damn, it feels so good. Probably no one will use it but I don’t care. It’s one of those projects where you have to force yourself to go to bed at 2 AM.

Just some thoughts. Don’t really have any techie friends so figured maybe someone here recognizes that feeling. Also I wrote it in Python, such a pleasant language.

This company wanted a "sample of your feed output in CSV format". So I threw together some documentation for our REST API. My project manager forwarded a link to their project manager who forwarded it to their backend team who forwarded it to their contactor who is doing the front end. I've half a mind to just put an extra field in the API responses: {
"comment": "If you're reading this, you're the person I've been trying to through to. Email me "
}

Hard at work moving the unofficial devRant api documentation to GitBook.

Note: The previous link provided will stop working in due course.

met a client yesterday to discuss about the coming task. After discussion, we agreed that I will develop the API for the system in one month. I did the planning and posted the upcoming tasks in Trello. Today, he told me some of the tasks have been done by his staff and asked me if I can continue the remaining tasks and get it done in one week. Hey, bro, what you want!? it is not what we agreed! do you think i can understand the code that your staff wrote, with poor documentation and structure, in few hours and immediately start working on it, yet deliver everything with high quality? come on...

Spent the last days trying to reach paypal tech support, hung on the phone across the globe, with people at paypal CS, who weren't even familiar with their own terminology, read tons of VERY 'straightforward' documentation and it kept me up two nights straight.

ALL because I REFUSED to believe that it is like I understood it between the lines that I read.

Today I got my answer. You can create Billing Plans (rules on which you'll base your subscriptions, i.e. amount, intervals, duration..) ONLY over the rest api, and only when a customer purchases a first subscription, you're able to EDIT the plan on Paypal dashboard!

What fuckery is that!? You have a edit form, but you can not provide a create form?! TY paypal for making me build a whole billing plan manager for usually a one time transaction per website.

I AM SENDING YOU MY PHONE BILL.

Amazing API's and SEX!

Alright people, now that I've got your attention, I'm getting to the point where I need to plan and roll out a solid API for a project. So after reading a lot of the horror stories written here, What are the finer points of what makes an amazing API experience to use and integrate with over a poor one?
And don't say documentation (If you do explain why) 😁

Android development:
- read the official documentation
- implement the logic in your app using what you learned
- find out that at least one method is always deprecated
- read the updated API and, as always, check out your loyal friend Stack Overflow.

School gave me 3 DigitalOcean droplets to try out Kubernetes in the cloud, awesome!

Wrote an Ansible script to not only simply install docker and add users but also add kubernetes, nice!

Oh wait, error?! Well I should've known this wasn't going to be easy... ah well no problem. Let's see... Ansible is cryptic as always, it can't connect to the API server? Is it even running?

Let's ssh to the master, ah nothing is running, great. Let's try out kubeadm init and see what happens, oh gosh, my Docker version has not been validated! No problem, let's just downgrade!

How do I do that? Oh I know, change the version in the role! Wait that version doesn't exit? Let's travel to Docker's website and see what versions exist of docker-ce, oh I see, it needs a subversion, no problem.

Oh that errors too? Wait then what... Oh I need a ~ and a ubuntu and a 0 somewhere, my mistake!

Let's run it again! Fails!

Same ssh process, oh wait...

Oh god no...

Kubernetes requires 2 cores and these things only have 1...

Welp, time to ask the teachers to resize my droplet by a small amount tomorrow, hopefully I'll get a new error!

----------------------------------------------

My adventure so far with Kubernetes. I'm not installing it for any serious/prod reason, just for educational purposes. K8s seems like 'endgame' to me, like one of the 'big guys' that big enterprises use so I'm eager to throw stuff at a droplet and see what happens.

Going further down the rabbit hole tomorrow!

Wish me luck :3

(And yes, I could've figured this all out beforehand with documentation, but this is more fun in my opinion)

I wrote a random string/int/other stuff API somewhere this year which I still regularly use because I'm a lazy fuck.

Never posted anything about it on here and the documentation isn't entirely complete (and not all the endpoints are extensively bug-tested yet) but if someone is interested I'll see if I can patch some stuff and put it on here as I find it useful!

I don't know if I'm being pranked or not, but I work with my boss and he has the strangest way of doing things.
- Only use PHP
- Keep error_reporting off (for development), Site cannot function if they are on.
- 20,000 lines of functions in a single file, 50% of which was unused, mostly repeated code that could have been reduced massively.
- Zero Code Comments
- Inconsistent variable names, function names, file names -- I was literally project searching for months to find things.
- There is nothing close to a normalized SQL Database, column ID names can't even stay consistent.
- Every query is done with a mysqli wrapper to use legacy mysql functions.
- Most used function is to escape stirngs
- Type-hinting is too strict for the code.
- Most files packed with Inline CSS, JavaScript and PHP - we don't want to use an external file otherwise we'd have to open two of them.
- Do not use a package manger composer because he doesn't have it installed.. Though I told him it's easy on any platform and I'll explain it.
- He downloads a few composer packages he likes and drag/drop them into random folder.
- Uses $_GET to set values and pass them around like a message contianer.
- One file is 6000 lines which is a giant if statement with somewhere close to 7 levels deep of recursion.
- Never removes his old code that bloats things.
- Has functions from a decade ago he would like to save to use some day. Just regular, plain old, PHP functions.
- Always wants to build things from scratch, and re-using a lot of his code that is honestly a weird way of doing almost everything.
- Using CodeIntel, Mess Detectors, Error Detectors is not good or useful.
- Would not deploy to production through any tool I setup, though I was told to. Instead he wrote bash scripts that still make me nervous.
- Often tells me to make something modern/great (reinventing a wheel) and then ends up saying, "I think I'd do it this way... Referes to his code 5 years ago".
- Using isset() breaks things.
- Tens of thousands of undefined variables exist because arrays are creates like $this[][][] = 5;
- Understanding the naming of functions required me to write several documents.
- I had to use #region tags to find places in the code quicker since a router was about 2000 lines of if else statements.
- I used Todo Bookmark extensions in VSCode to mark and flag everything that's a bug.
- Gets upset if I add anything to .gitignore; I tried to tell him it ignores files we don't want, he is though it deleted them for a while.
- He would rather explain every line of code in a mammoth project that follows no human known patterns, includes files that overwrite global scope variables and wants has me do the documentation.
- Open to ideas but when I bring them up such as - This is what most standards suggest, here's a literal example of exactly what you want but easier - He will passively decide against it and end up working on tedious things not very necessary for project release dates.
- On another project I try to write code but he wants to go over every single nook and cranny and stay on the phone the entire day as I watch his screen and Im trying to code.

I would like us all to do well but I do not consider him a programmer but a script-whippersnapper. I find myself trying to to debate the most basic of things (you shouldnt 777 every file), and I need all kinds of evidence before he will do something about it. We need "security" and all kinds of buzz words but I'm scared to death of this code. After several months its a nice place to work but I am convinced I'm being pranked or my boss has very little idea what he's doing. I've worked in a lot of disasters but nothing like this.

We are building an API, I could use something open source to help with anything from validations, routing, ACL but he ends up reinventing the wheel. I have never worked so slow, hindered and baffled at how I am supposed to build anything - nothing is stable, tested, and rarely logical. I suggested many things but he would rather have small talk and reason his way into using things he made.

I could fhave this project 50% done i a Node API i two weeks, pretty fast in a PHP or Python one, but we for reasons I have no idea would rather go slow and literally "build a framework". Two knuckleheads are going to build a PHP REST framework and compete with tested, tried and true open source tools by tens of millions?

I just wanted to rant because this drives me crazy. I have so much stress my neck and shoulder seems like a nerve is pinched. I don't understand what any of this means. I've never met someone who was wrong about so many things but believed they were right. I just don't know what to say so often on call I just say, 'uhh..'. It's like nothing anyone or any authority says matters, I don't know why he asks anything he's going to do things one way, a hard way, only that he can decipher. He's an owner, he's not worried about job security.

Facebook API...

Facebooks "graph" or API's in general fucking stink donkey dick.

Their implementation of oAuth is horrible.. 3 different tokens, which can be either short or long lived, for fetching a facebook page feed (the clients own facebook page)
To that you add a clientID and a ClientSecret.

Great... after painstakingly reading confusing documentation and itching your head... You get it to work.

Then they, without notice, makes a breaking change of deprecate an endpoint you were using.. Jesus..

And all the support you can get comes from a "community group" which may or may not reply with a generic link to their documentation...

Unofficial devRant API Documentation
(Remake of the old devRant-Docs site)

I assigned a new task to an intern who has been with us for a month. He was supposed to prepare the testing environment and test the Geolocation API. When it works, then he can start integrating it with our platform and everything.

After a week, he emails me to say that he thinks the Geolocation API doesn't work. I was weirded out by that because a lot of people use it. We scheduled a meeting and asked him for a demo of his code to see what the error message is.

Him: *no Visual Studio, no code, nothing at all* So here it goes.

Me: ????

Him: *Goes to the API documentation, copies the base URL, pastes it to the browser and hits Enter* See? It says 404 not found.

Me: *literally facepalmed*

Now, he is working on sales management. We totally took him off every software developing projects.

This is a short tale that can be summed up as "oh fuck meee".

After finishing an API the night before I settled in for a day of bug fixes and tidy ups. Until slack went off.

The front end dev was getting an error, a code breaking error. After doing the standard process of request checking i went okay must be me. I find the script that is has the error and the line that it is failing at.

Que 2 hours of the full cycle of anger, sadness, pleading, and finally acepting that it had finally happened I had gone insane. The code was to documentation best practise correct and it still had the same error.

I the cheaked the DB on a whim and I found that my code was not wrong and it was doing exactly what I wanted the data however had a single record that was old and the schema had change juuussstt enoigh to break everything at that record. One 3 secound deletion later code ran perfectly.

So, 9months ago my scrum master came to me and asked me to spearhead a "little" API... 2months work, no worries... I started the analysis and quickly discovered that that estimation was grossly understimated...

I convinced them that it was not 3 months but 4. I alerted to the design mistakes that were made, I pushed changes and made sure the entire project worked, was stable and the best it could be... 4 months passed, target proposition donne... Several change requests since then and we have been implementing braindead CR after CR for 5 months... Most CRs came from design issued I raised but we're ignored at the time just to come back and bite them on the ass...

Horrible design, bad documentation, amateur requirements analysis... However, delivered successfully with great acceptance...

What was my reward? They rearranged my team, removing virtually every good performer.

Never did I receive a "good work" or a "thank you"... I don't want one, I am just doing my job... However can you please not fuck me in the ass!? I now have 2 projects to spearhead at the same time and virtually no team... I can only handle so much!!!

Some good news? Ok, just announced I'm the project owner of a new project, that we will take advantage and make a 2 in one.... Great! Some more work for my lap! Thank you for the workload raise!... Ok, timewise? One month! And I still don't if that includes implementation....

TL DR; did my job, got fucked with more work...

Sorry for the vent, just wandering if I should try and not do my job...

These are the things that finally finally helped me stick to learning programming.

Hello world! This is my first story on devrant and I would like to share how I finally overcame the barriers that had always prevent me from learning programming in a more serious and structured way.

I know my way around linux, had some experience with BASIC many years ago and have more than basic notions of cryptography... however I never got myself to learn programming in such a way that I could write an app or interact with an API. Until now.

I have advanced more than ever before and I believe it might be thanks to these aspects:

1. C#
I have always had struggles with languages that were too compact or used many exotic or cryptic expressions. However I have found C# to be much more readable and easier to understand.

2. Visual Studio
My previous attempts at learning programming were without an IDE. Little did I know what I was missing!

For example when I tried learning python on Debian, I almost went crazy executing programs and trying to find the compile errors in a standard text editor.

Intellisense has been live changing as it allows me to detect errors almost immediately and also to experiment. I'm not afraid to try things out as I know the IDE will point out any errors.

3. .NET library and huge amounts of documentation
It was really really nice to find out how many well documented classes I had available to make my learning process much easier, not having to worry about the little details and instead being able to focus on my program's logic.

4. Strong typing
Call me weird, but I believe that restricting implicit conversions has helped learn more about objects, their types and how they relate to each other.

I guess I should be called a C# fanboy at this point, but I owe it to that language to be where I'm now, writing my first apps.

I also know very very little about other languages and would love to hear if you know about languages that provide a similar experience.

Also, what has helped you when you first started out?

Thanks!!

I've just seen the documentation of an api I have to communicate with, and facepalmed when I have seen that some actions return 404 on success. And more bizarre things... Just wanted to make it worse for me, didn't you?
Once at it. Why don't you glue spikes onto my keys?
Ffs

I fucking hate being a Dev sometimes.

G i v e m e f u l f i l l i n g t a s k s p l e a s e

Not these shitty ones with API documentation riddled with holes 🫠😥

!devButAlsoKindaIsDev

Alright, time to do some explanation.

TL;DR: JavaScript is a fucking nightmare. May god help every web developer out there. Essentially, I was gone because of JavaScript.

Q: where tf are you bruh
A: in your mo-uhhhhh alright, so I was chosen to be the main developer for an interactive promotional video for my school (every year the school holds something called an open day, where kids from 8th grade can come to the school and have a tour in the school first hand. Because of the coronavirus (just gonna call it “the rona” from here) this is now impossible so we are losing the interest and the first impressions so the school decided to make an interactive virtual one). They asked me if I want to do it and I said yes.

Boy, was that ever a mistake... (hint: it was a huge mistake)

So the guy who talked to me and asked if I wanted to do this was my grade’s manager, and he gave me the phone number of my PM. So we talked and stuff, and then this happened: (bruh = PM)

bruh: I’ll send you the API and documentation for the thing that we are working with! They have lots of examples and stuff and they’re Israeli too!

Me: Okay! What language are we talking about here?

bruh: JavaScript.

Me: (questioning life choices) Okay!

I didn’t write any JavaScript for the last 3 years or so. It had to be done because I promised and I can’t let down people who count at me and ask me to show where I shine.

So, what was the objective for me? Build a Firebase client that sends the user’s score and choices to Firestore after he chooses something in the interactive video (for example, go to chemistry or go to physics) while learning JavaScmeme (ECMEMEScript) as I go.

Deadline? A week and a half.

After working almost 12 hours a fucking day, I made it work. Sorta. In order to reconcile with small exceptions and edge cases in the interactive video, I had to hard-code some IDs in the code. I had no choice, since I couldn’t allow myself to spend more and more time to make my code more dynamic than it was because I simply didn’t have time. The code absolutely STINKS but it works.

Today is the day where we (aim) to finish all of the cosmetic things that we need to fix. All of them are non-essential for everything to work, but we want to make this thing presentable because we want to put this on the school’s website.

CONCLUSION:

JavaScript is literal shit. Dynamic weakly-typed languages are cursed AF and need to die in a fire.

Finding the right balance between well written, need-one-week, maintainable software, and fast-written, ready-in-2-hours-and-never-look-at-it-again software.

Last time it took me 20 minutes to integrate with a new API. I had a script that did everything you needed. I then spent 2 weeks on handling error responses, unexpected responses, exceptions, intelligent retries, logging, unit tests, integration tests, caching, documentation, etc.

When the only "api" documentation you have is a wsdl file...

18 commits later, the unofficial documentation has been ported over to GitBook.

The documentation now lives in a private repo on GitHub which is hooked up to a CI tool to build the book when a commit is pushed.

This will make maintaining the documentation much easier and also allow for collaboration which was previously not possible.

Because this documentation contains some endpoints some of you might not even know about, access is provided on a invite-only basis which is controlled by @dfox.

For new requests, contact @dfox with your name and what you are planning to build.

If you have already created something with the API email me at support@nblackburn.uk with your name and a link and I will send you a invite.

Rant

I'm tired of this shit!!!

First I receive a task to create a new functionality for the app that I'm working on and some documentation (this is the only good part of all the rant) but no design.

It's been 2 weeks since I got assigned to this and still no design, no assets, no API calls that ACTUALLY WORK.

Today was testing a plist to get a banner link, and for 1 hour that little fucker didn't returned the image I was asking.

Better, I wasn't getting ANY IMAGE. Turns out that the link sends me to a HTML URL that doesn't have any image... go figure!

So I've been working on this from some images inside the PDF with the documentation given.

Oh! Wait! There's more!

The cherry on top is that I'm implementing a chat/voice call/video call into the app and the framework that I will be using is being created now, and it's not even finished!!!!!!

!Rant

TLDR: What's your favorite REST API Documentation tool?

I'm about to start developing a really large REST API. I have never really had need to document my previous API's since they were small, self explanatory and had only me using them. Aside from this one being too large for me to keep track of there is also a remote team that will need to integrate with it.

Basically I need write exceptional documentation while using as little time as possible. I love postman and am planning to use it for documentation since I currently use it to test during development anyway but I have seen some really neat looking tools like swagger and apiary so I figured I would check for some other suggestions.

What is your current / preferred REST API documentation method?

Ah, developers, the unsung heroes of caffeine-fueled coding marathons and keyboard clacking symphonies! These mystical beings have a way of turning coffee and pizza into lines of code that somehow make the world go 'round.

Have you ever seen a developer in their natural habitat? They huddle in dimly lit rooms, surrounded by monitors glowing like magic crystals. Their battle cries of "It works on my machine!" echo through the corridors, as they summon the mighty powers of Stack Overflow and Google to conquer bugs and errors.

And let's talk about the coffee addiction – it's like they believe caffeine is the elixir of code immortality. The way they guard their mugs, you'd think it's the Holy Grail. In fact, a developer without coffee is like a computer without RAM – it just doesn't function properly.

But don't let their nerdy exteriors fool you. Deep down, they're dreamers. They dream of a world where every line of code is bug-free and every user is happy. A world where the boss understands what "just one more line of code" really means.

Speaking of bosses, developers have a unique ability to turn simple requests into complex projects. "Can you make a small tweak?" the boss asks innocently. And the developer replies, "Sure, it's just a minor change," while mentally calculating the time it'll take and the potential for scope creep.

Let's not forget their passion for acronyms. TLA (Three-Letter Acronym) is their second language. API, CSS, HTML, PHP, SQL... it's like they're playing a never-ending game of Scrabble with abbreviations.

And documentation? Well, that's their arch-nemesis. It's as if writing clear instructions is harder than debugging quantum mechanics. "The code is self-explanatory," they claim, leaving everyone else scratching their heads.

In the end, developers are a quirky bunch, but we love them for it. Their quirks and peculiarities are what make them the creative, brilliant minds that power our digital world. So here's to developers, the masters of logic and the wizards of the virtual realm!

Is it wrong to expect some widespread documentation from a $350 billion company to properly document a key part of their upgrade path for a new SDK version? beware any Android devs upgrading from API 3.X to 4.X on the Facebook SDK.......you'll want FacebookSdk.setLegacyTokenUpgradeSupported(true); before your call to initialize.....

step 1) open and browse producthunt for new dev tools to use and try out
.
step 2) opens dev tool/app's website *ooh nice landing page*
.
step 3) tries to find api and documentation, scrolls to bottom of the webpage
.
step 4) "we are still in private beta, sign up to be notified about the final release!"
.
step 5) lol *sighs* bookmarks tab before closing it
.
step 6) repeat step 1
.
.

React router is shit
I have never seen more retarded library.

Not only those suckers change the 100% of the API every fucking update for no reason, also they have the most fucked up documentation ever.

No search in the docs!!! Fucking bullshit examples with no such easy things like how to create nested routes.

Please, stop using this piece of shit, I'm tired of working with this fucking abomination. Hope they will delete their shit repo one day.

We have a new hire, and he doesn't know much so he is receptive when given feedback on better ways to handle a situation...Or at least, he appears that way. Until the next time and he didn't listen at all.

Today I'm working on the front end to match his API calls. I ask him about a list of options for one of the fields, as he didn't provide that info initially. No worries, there was a lot, easy to miss. He responds with a list of ~100 options, which he copied and pasted from, I'm assuming, their documentation. I tell him that's too many options to hard code, as there is an easy chance to have an error or for there to be one added or deleted, and ask if there is an API endpoint to get the list.

He then asks if I need the key and value, or just key. I tell him if he needs the value(human readable) then he can send me just the value, otherwise both. He says he just needs the key, so I let him know that I need both then, as the value is human readable. He says okay.

He proceeds to make the endpoint, I test it. Then I look at the code he wrote. Not only did he not send me both, he just sent the keys, but he hard coded all 100 keys as opposed to making the call to the external API.

“The documentation of this API is left as an exercise to the reader.”

Wow, very technical and clear documentation:

"While we do not publish the symbol limits for the streaming API, we do monitor for abuse to make sure people aren’t doing anything egregious. Essentially, ask for what you need. Don’t abuse the APIs and you should be fine."

...and, we all know what 'fine' stands for, right?

🤡

Api with no documentation and obscure endpoints

Dear API vendor,

Please get off your arse and learn about REST, OpenAPI, JSON Schema, XSD and basic documentation so that I don't have to guess how to use your shitty, inconsistent, RPC over HTTP service.

With Love,

Platypus

Not only Synology's REST API documentation is outdated, but I have to deal with this.

Let alone the fact that login in a GET request where username and password are passed as query string in URL.

Aren't you, software engineer, ashamed of being employed by Apple? How can you work for a company that lives and shit on the heads of millions of fellow developers like a giant tech leech?
Assuming you can find a sounding excuse for yourself, pretending its market's fault and not your shitty greed that lets you work for a company with incredibly malicious product, sales, marketing and support policies, how can you not feel your coders-pride being melted under BILLIONS of complains for whatever shitty product you have delivered for them?
Be it a web service that runs on 1980 servers with still the same stack (cough cough itunesconnect, membercenter, bug tracker, etc etc etc etc) incompatible with vast majority of modern browsers around (google at least sticks a "beta" close to it for a few years, it could work for a few decades for you);
be it your historical incapacity to build web UI;
be it the complete lack of any resemblance of valid documentation and lets not even mention manuals (oh you say that the "status" variable is "the status of the object"? no shit sherlock, thank you and no, a wwdc video is not a manual, i don't wanna hear 3 hours of bullshit to know that stupid workaround to a stupid uikit api you designed) for any API you have developed;
be it the predatory tactics on smaller companies (yeah its capitalism baby, whatever) and bending 90 degrees with giants like Amazon;
be it the closeness (christ, even your bugtracker is closed and we had to come up with openradar to share problems that you would anyway ignore for decades);
be it a desktop ui api that is so old and unmaintained and so shitty, but so shitty, that you made that cancer of electron a de facto standard for mainstream software on macos;
be it a IDE that i am disgusted to even name, xcrap, that has literally millions of complains for the same millions of issues you dont even care to answer to or even less try to justify;
be it that you dont disclose your long term plans and then pretend us to production-test and workaround-fix your shitty non-production ready useless new OS features;
be it that a nervous breakdown on a stupid little guy on the other side of the planet that happens to have paid to you dozens of thousands of euros (in mandatory licences and hardware) to actually let you take an indecent cut out of his revenues cos there is no other choice in a monopoly regime, matter zero to you;
Assuming all of these and much more:
How can you sleep at night with all the screams of the devs you are exploiting whispering in you mind? Are all the money your earn worth?

** As someone already told you elsewhere, HAVE SOME FUCKING PRIDE, shitty people AND WRITE THE FUCKING DOCS AND FIX THE FUCKING BUGS you lazy motherfuckers, your are paid more than 99.99% of people on earth, move your fucking greasy little fingers on that fucking keyboard. **

PT2: why the fuck did you remove the ESC key from your shitty keyboards you fuckshits? is it cos autocomplete is slower than me searching the correct name of a function on stackoverflow and hence ESC key is useless? at least your hardware colleagues had the decency of admitting their error and rolling back some of the uncountable "questionable "hardware design choices (cough cough ...magic mouse... cough golden charging cables not compatible with your own devices.. cough )?

Me: Could you please provide us with api key so we can add this feature?
Client's IT person: You don't need the api key to develop, their site has documentation so it's not a blocker. I will get you the api key when we are ready to go live.
Me: ...

Microsoft APIs documentation, best API documentation ever!

So how do people figure out API endpoints without documentation?

When you click on the github wiki of the API you wanted to use and it shows you the "Create the first page" banner....

Guess I'll have to find another API with proper fucking documentation.

I really hate sales people. My stakeholder wants to buy an address verification service but is hesitant to purchase now because the dev time needed would be substantial. Now the sales rep has planted seeds of doubt in my SH and SH thinks I grossly overestimated the labor I quoted.

Sales rep is all “major corporations have installed this in a weekend.” 🤬🤬🤬 Major corporations also have more than one developer and probably aren’t dealing with a website that has a dozen address forms that all work differently. Oh, and I DON’T WORK WEEKENDS MOFO.

My SH originally requested a labor estimate for installing the AVS on all address forms and that’s what I delivered. My audit revealed a dozen different forms. I’m working with a legacy code base that’s been bandaged together and maintained by an outside dev agency. The only thing the forms have in common is reusable address fields. They all work differently when it comes to validating and submitting data to the server and they all submit to different api endpoints. At least a quarter of those forms are broken and would need to be fixed (these are mostly admin-facing). I also had to provide an estimate on frontend implementation when I have no idea what they want the FE to look like.

My estimate was 5-8 weeks for implementation AND testing. I wrote up my findings and clearly explained the labor required, why it was needed, and the time needed. All was fine until the sales rep tried to get into SH’s head.

My SH is now asking for a new estimate and hoping for 1-2 weeks of labor, which is what will SH to buy the AVS. Then go to the outside dev agency you used to work with and ask for a second opinion. I’m sure they’d also tell you at least month if not more for testing, implementation, and deployment because you have a DOZEN FORMS you want to add this to. 1-2 weeks is only possible for a single form.

My manager doesn’t work in the same coding language I do, but he read my documentation and supports my original estimate.

I honestly want to ask my SH if this sales rep is giving a very good price for the AVS. If not, are there other companies in the mix? Because right now you have a sales rep that’s taking you for a ride and trying to pressure you all so he can get another notch in his belt for getting another “major corporation” as his account. I don’t think it’s a good idea to be locked in with a grimy sales rep.

Take the laziest person in the world and ask him/her to write an API documentation. He/she would do a better job than Apple

This is the story of the API documentation.
Which btw I couldn't find on the producent's website anywhere. I had the pdf shared with me by a coworker.

I knew the api was fucked up the moment I looked at endpoint documentation.

GET params? WHERE, ORDERBY etc. Literally make a SQL select in a GET request.

Returned stuff? The whole thing. Not some DTO, you literally get everything you can get.
Eg if you get IP in your response, you get it in several formats: dotted form, as hex, and as int. In 3 different json fields.

Oh, and regarding IP - one would imagine you can use masks or prefixes for subnets, right? Nope. The only param you can use there is the subnet size. So you have to calculate the power of 2 every time you want to make a request.

That's from the endpoint documentation. But what about some general info on the API, before all that?

As I was looking for something, I decided to read that intro and general info about the API.

Okay, so there was a change log between API versions. "removed [endpoint which sounds like correct REST design], please use [this generic thing with SQL-like GETs]"... Several of them.

And there was also this sentence which said that the API is not restful, "it's REST-like". <facepalm>

If it was a bad attempt at REST API, I would let it go. But this sentence clearly showed they knew they did everything wrong. And the changelog showed they didn't stop there, they were actively making it worse.

So I spent the last 2 hours trying to figure out why my co-workers source when hitting the API I built was not working. They kept saying that the problem was the API and I kept saying that it's their implementation.

Turns out it was their implementation and as well as the API. Their implementation problem was not setting the "Accept" in the header. The API problem is how Laravel will return a JSON error response ONLY IF the "Accept" is set in the header.

I actually documented this into the API documentation but it's obvious that none of my co-workers read that you need to set the headers correctly. I think the more scary thing is that they didn't know the difference between Accept and Content-Type!!

Best: actually started to work on side projects, they are not just discarded ideas on the paper anymore, so excited about this one

Worst: legacy bolognese app nobody understands and doesn't have documentation coupled with weird API also without any documentation

Not exactly the worst but Ingenico's API documentation is destroying my life right now.

In This Rant: A mildly satisfying piece of mind story.

Using code to prove yourself right is a hell of a drug.

A few weeks ago I whipped up a tiny program that downloads configs from hardware we manage. Since the vendor's API documentation is hidden behind a pay wall, my method of extraction is different. It results in bigger files, but testing showed it to still be valid.

Enter today. Interns at work downloaded a config to load onto a spare machine and it won't work.

"TheCapeGreek, your configs don't work"

I was confused since I tested the files when I built it and it worked. I am also currently fleshing out that download utility's features so the fear that I've been wasting the past 2 weeks on improvements is looming.

Last 15 minutes of the day and nothing else to do so I figured I might as well whip up a string comparer. The smaller file's content is scattered in the big file so a direct diff won't work.

Code it all, quick hardcoded proof of concept code, bit it got the job done. I was right, my bigger file is still correct!

Turns out the issue was with the machine they were configuring. They found this out before I finished my test code, so I'm off the hook already, but it was good to have piece of mind haha!

SO MAD. Hands are shaking after dealing with this awful API for too long. I just sent this to a contact at JP Morgan Chase.

-------------------
Hello [X],
1. I'm having absolutely no luck logging in to this account to check the Order Abstraction service settings. I was able to log in once earlier this morning, but ever since I've received this frustratingly vague "We are currently unable to complete your request" error message (attached). I even switched IP's via a VPN, and was able to get as far as entering the below Identification Code until I got the same message. Has this account been blocked? Password incorrect? What's the issue?

2. I've been researching the Order Abstraction API for hours as well, attempting to defuddle this gem of an API call response:

error=1&message=Authentication+failure....processing+stopped

NOWHERE in the documentation (last updated 14 months ago) is there any reference to this^^ error or any sort of standardized error-handling description whatsoever - unless you count the detailed error codes outlined for the Hosted Payment responses, which this Order Abstraction service completely ignores. Finally, the HTTP response status code from the Abstraction API is "200 OK", signaling that everything is fine and dandy, which is incorrect. The error message indicates there should be a 400-level status code response, such as 401 Unauthorized, 403 Forbidden or at least 400 Bad Request.

Frankly, I am extremely frustrated and tired of working with poorly documented, poorly designed and poorly maintained developer services which fail to follow basic methodology standardized decades ago. Error messages should be clear and descriptive, including HTTP status codes and a parseable response - preferably JSON or XML.
-----

This whole piece of garbage is junk. If you're big enough to own a bank, you're big enough to provide useful error messages to the developers kind enough to attempt to work with you.

all documentation points to an Invalid auth token being code 400 (ignore the fact that this is a code in the JSON response and not HTTP)

Me: here iz credential. Plz send datas
API: haha fock off and die mate, then credentials you got there aren’t workin’
API: code 998 invalid auth token
Me: *speechless* so that’s why it took me longer than it did to find that error, because YOUR CODE WAS MISSING ALL MY CHECKS FOR CODE 400.

Why can’t people design apis properly.

Ok so I have done some work with crypto currency mining pools and recently a client requested for me to make a splash page that showed data from multiple instances of these pools APIs. I went to find some documentation for this open source api and to my surprise there is none. I thought of querying the public API from the clients side and it worked, however it's so slow that the data shows up roughly 20 seconds after the page loads.

Easy fix right? Make a PHP server get the data every 5 seconds, cache it and serve the data with the page and use a websocket for live updates! Until I found out that there is no practical way in this garbage framework to get the damn API data without making an HTTP request or mutilating the original source code. I'm so done with this garbage framework. It literally loads pages based on a page and action parameter on the index.php. I quit.

If you're not going to update your API documentation please just delete it. I spent two hours trying to use the example only to discover SECRET REST PARAMETERS that solved my problem.

If it weren't for the hero bitching in the comments about the missing documentation I would never have gotten this to work.

Working on an Android app for a client who has a dev team that is developing a web app in with ember js / rails. These folks are "in charge" of the endpoints our app needs to function. Now as a native developer, I'm not a hater of a web apps way of doing things but with this particular app their dev teams seems to think that all programming languages can parse json as dynamically as javascript...

Exhibit A:

- Sample Endpoint Documentation
* GetImportantInfo
* Params: $id // id of info to get details of
* Endpoint: get-info/$id
* Method: GET
* Entity Return {SampleInfoModel}

- Example API calls in desktop REST client
* get-info/1
- response
{
"a" : 0,
"b" : false,
"c" : null
}
* get-info/2
- response
{
"a" : [null, "random date stamp"],
"b" : 3.14,
"c" : {
"z" : false,
"y" : 0.5
}
}
* get-info/3
- response
{
"a" : "false" // yes as a string
"b" : "yellow"
"c" : 1.75
}

Look, I get that js and ruby have dynamic types and a string can become a float can become a Boolean can become a cat can become an anvil. But that mess is very difficult to parse and make sense of in a stack that relies on static types.

After writing a million switch statements with cases like "is Float" or "is String" from kotlin's Any type // alias for java.Object, I throw my hands in the air and tell my boss we need to get on the phone with these folks. He agrees and we schedules a day that their main developer can come to our shop to "show us the ropes".

So the day comes and this guy shows up with his mac book pro and skinny jeans. We begin showing him the different data types coming back and explain how its bad for performance and can lead to bugs in the future if the model structure changes between different call params. He matter of factually has an epiphany and exclaims "OHHHHHH! I got you covered dawg!" and begins click clacking on his laptop to make sense of it all. We decide not to disturb him any more so he can keep working.

3 hours goes by...

He burst out of our conference room shouting "I am the greatest coder in the world! There's no problem I can't solve! Test it now!"

Weary, we begin testing the endpoints in our REST clients....

His magic fix, every single response is a quoted string of json:

example:
- old response
{
"foo" : "bar"
}
- new "improved" response
"{ \"foo\" : \"bar\" }"

smh....

For all the hate that Java gets, this *not rant* is to appreciate the Spring Boot/Cloud & Netty for without them I would not be half as productive as I am at my job.

Just to highlight a few of these life savers:
- Spring security: many features but I will just mention robust authorization out of the box
- Netflix Feign & Hystrix: easy circuit breaking & fallback pattern.
- Spring Data: consistent data access patterns & out of the box functionality regardless of the data source: eg relational & document dbs, redis etc with managed offerings integrations as well. The abstraction here is something to marvel at.
- Spring Boot Actuator: Out of the box health checks that check all integrations: Db, Redis, Mail,Disk, RabbitMQ etc which are crucial for Kubernetes readiness/liveness health checks.
- Spring Cloud Stream: Another abstraction for the messaging layer that decouples application logic from the binder ie could be kafka, rabbitmq etc
- SpringFox Swagger - Fantastic swagger documentation integration that allows always up to date API docs via annotations that can be converted to a swagger.yml if need be.
- Last but not least - Netty: Implementing secure non-blocking network applications is not trivial. This framework has made it easier for us to implement a protocol server on top of UDP using Java & all the support that comes with Spring.

For these & many more am grateful for Java & the big big community of devs that love & support it.

I hate React. I keep reading that people have problem of grasping it, but that's not the case for me. I get it, I understand it, but I hate with passion HOW it's done knowing how nice it's done elsewhere. What really triggers me is how ugly it looks, both from architecture and code level. To me it really say a lot when even code shown in documentation looks ugly, and while reading it you ask ourself constantly "why it's done this way?". When I read React being called an "elegant" solution something explodes in me. Did you saw Svelte? Vue? Damn, even Alpine.js?
I just cannot how overengineered this API is. Even doing simplest things there produces so much junk code written only because this is what library requires. Why? I feel like working with it is a punishment.
And scalability and maintainability? I've never seen large-scale projects more messed up than those wrote with React. And yes, you can blame teams working on them for lack of skills, but it is the library which encourages or not good practices also, and I've never seen such bad situation with other libraries/frameworks.

When do you know something is being overdesigned or overengineered?

The applications that the other programmer started building are killing me. He's using Clean Architecture and it has like a million different classes and shit. It's not messy or anything, but fuck it's overwhelming.

Just to figure out wtf was happening when getting the currently signed in user's email, I had to go through like 30 folder and files. Maybe more. All files were fairly simple on their own, but the entire flow was mindfucking me. Use cases, schemas, gateways, repositories, entities, models, etc etc

And that's the client facing application, I haven't checked the API yet, though it seems like that one is simpler.

The worrying aspect here is, any time anyone else has to mess with this, they'll also have to deal with this shit. This needs some really good documentation.

Just wanted to code some better public transportation route calculator (better ux) and found out that the pt company offers an API.

EVERY FUCKING REQUEST HAS TO BE SENT AGAINST THE SAME FUCKING ENDPOINT IN A POST REQUEST WITH THE ORIGINAL REQUEST AS FUCKING XML IN THE FUCKING BODY. At least they offer xsd files... BUT THATS NO FUCKING HELP. At least not that much of a help. AND THE DOCUMENTATION DOES NOT STATE A SINGLE FUCKING EXAMPLE OF HOW TO USE THAT FUCKING ENDPOINT. I FOUND THIS OUT BY SENDING RANDOM REQUESTS TO THE ENDPOINT TRYING TO REVERSE ENGINEER THE EXISTING FUCKING FRONTEND AND NOW I NOTICED THAT 80% OF THE FUCKING DOCUMENTED FEATURES ARE DISABLED BECAUSE: NOT FUCKING SUPPORTED!!!

MAAAN WHY DO YOU DO THIS.

Alternatively I'd use the GTFS files they provide but THEY ARE FUCKING INCOMPLETE AND DONT STICK TO THE EXISTING STANDARD GOOGLE DEFINED... They also offer a different propietary format... BUT THATS FUCKING UNDOCUMENTED AND FUCKING INCOMPLETE...

I would like to present new super API which I have "pleasure" to work with. Documentation (very poor written in *.docx without list of contents) says that communication is json <-> json which is not entirely true. I have to post request as x-www-form with one field which contains data encoded as json.

Response is json but they set Content-Type header as text/html and Postman didn't prettify body by default...

I'm attaching screenshot as a evidence.

I can't understand why people don't use frameworks and making other lives harder :-/

¡rant|rant

Nice to do some refactoring of the whole data access layer of our core logistics software, let me tell an story.

The project is around 80k lines of code, with a lot of integrations with an ERP system and an sql database.

The ERP system is old, shitty api for it also, only static methods through an wrapper to an c++ library

imagine an order table.

To access an order, you would first need to open the database by calling Api.Open(...file paths) (yes, it's an fucking flat file type database)

Now the database is open, now you would open the orders table with method Api.Table(int tableId) and in return you would get an integer value, the pointer.

Now for the actual order. first you need to search for it by setting the search parameter to the column ID of the order number while checking all calls for some BS error code

Api.SetInt(int pointer, int column, int query Value)
Then call the find method.

Api.Find(int pointer)

Then to top this shitcake of an api of: if it doesn't find your shit it will use the "close enough" method of search.

And now to read a singe string 😑

First you will look in the outdated and incorrect documentation given to you from the devil himself and look for the column ID to find the length of the column.

Then you create a string variable with ALL FUCKING SPACES.

Now you call the Api.GetStr(int pointer, int column, ref string emptyString, int length)

Now you have passed your poor string to the api's demon orgy by reference.

Then some more BS error code checking.

Now you have read an string value 😀

Now keep in mind to repeat these steps for all 300+ columns in the order table.

News from the creators: SQL server? yes, sql is good so everything will be better?

Now imagine the poor developers that got tasked to convert this shitcake to use a MS SQL server, that they did.

Now I can honestly say that I found the best SQL server benchmark tool. This sucker creams out just above ~105K sql statements per second on peak and ~15K per second for 1.5 second to read an order. 1.5 second to read less than 4 fucking kilobytes!

Right at that moment I released that our software would grind to an fucking halt before even thinking about starting it. And that me & myself and I would be tasked to fix it.

4 months later and two weeks until functional beta, here I am. We created our own api with the SQL server 😀

And the outcome of all this...

Fixes bugs older than a year, Forces rewriting part of code base. Forces removal of dirty fixes. allows proper unit and integration testing and even database testing with snapshot feature.

The whole ERP system could be replaced with ~10 lines of code (provided same relational structure) on the application while adding it to our own API library.

Best part is probably the performance improvements 😀. Up to 4500 times faster and 60 times less memory usage also with only managed memory.

What if I told you that algebra, geometry, precalculus's (ect) laws are the equivalent of api/documentation. we learn them and use them when necessary to solve problems. I will use the quadratic formula in math to solve a problem just like I would use a particular function in programming.

I love to develop for the web, i find JavaScript a nice language and I love the unmatched flexibility of the web platform but i hate when I have to work with the unstable or badly documented APIs which seems to be the norm in the enterprise world: wasting hours in forced breaks because suddenly the API returns nothing but 503 or the VPN suddenly dies, wasting lot of time to find the documentation you need in the slow and cumbersome enterprise API manager, making lots of tests with cURL/Paw/Postman/wethever trying to find out why a request which should work just doesn't... in these moments I envy desktop and mobile devs. The worst part of it is which microservices made everything worse since nowadays there are way more "moving parts" which can break making the API you need unavailable and unlike with monoliths often it's hard to just clone a back-end, populate a database and then work fully locals since now everything depends on a lots of things which are hard/almost impossible to replicate on your laptop.

Companies writing a documentation for their cloud api is similar to the 4 year old kid who draws up something and brings it to us... Either ways all we can understand from it is... Nothing.

// Stupid JSON
// Tale of back-end ember api from hell
// Background: I'm an android dev attempting to integrate // with an emberjs / rails back-end

slack conversation:
me 3:51pm: @backend-dev: Is there something of in the documentation for the update call on model x? I formed the payload per the docs like so
{
"valueA": true,
"valueB": false
}
and the call returns success 200 but the data isn't being updated when fetching again.
----------------------------------------------------------------------------------------
backend-dev 4:00pm: the model doesn't look updated for the user are you sure you made the call?
----------------------------------------------------------------------------------------
me 4:01pm: Pretty sure here's my payload and a screen grab of the successful request in postman <screenshot attached>
----------------------------------------------------------------------------------------
backend-dev 4:05pm: well i just created a new user on the website and it worked perfectly your code must be wrong
----------------------------------------------------------------------------------------
me 4:07pm: i can test some more to see if i get any different responses
----------------------------------------------------------------------------------------
backend-dev 4:15pm: ahhhhhh... I think it's expecting the string "true", not true
----------------------------------------------------------------------------------------
me 4:16: but the fetch call returns the json value as a boolean true/false
----------------------------------------------------------------------------------------
backend-dev 4:18pm: thats a feature, the flexible type system allows us to handle all sorts of data transformations. android must be limited and wonky.
----------------------------------------------------------------------------------------
me 4:19pm: java is a statically typed language....
// crickets for ten minutes
me 4:30pm: i'll just write a transform on the model when i send an update call to perform toString() on the boolean values
----------------------------------------------------------------------------------------
backend-dev 4:35: great! told you it wasn't my documentation!

// face palm forever

anyone else, when reading documentation to some API, and you come across section titled "doing [whateveritis] via SOAP", you just laugh "hahaha, no way, sweety", and scroll past that section as fast as possible? =D

Fuck api docs which are blatantly wrong. Wasted several hours on building an API client with pagination according to the api docs.

Turns out the actual implementation did not follow its own spec / api doc and returns values without pagination. And some objects are not objects but arrays.

I mean, next time I build an API client, I'll just fire a dozen requests on the endpoint, see what it wants and see what I get and maybe guess right what it actually does.

Today after longer vacation I came back to work.

Edit: wrote this rant long time ago, but never finished. Was too pissed.

Some easy meetings, then wanted to start on an easy job.

Just migrating some things from bash regex voodoo to proper tools like JQ.

Finished in roughly 1 h. Lovely.
Made some tea, ate some cookies.

Set up dev environment, found no documentation what so ever, got it running after half an hour.

Annoying, but ok.

Then I tried my scripts...

They worked... Except they didn't.
Console log empty, response code 200 with state: GENERATE_NO_FILES.

Eh. Fuck you. Just fuck you.

Fixed the logging configuration, which was broken since uhm... 2 years plus?

Well... Another half another hour gone...
Kinda pissed now.

Still script return failed...
Poking and trying to sprinkle debug all over that shit cause everything seems ... An incohesive, inconsistent diarrhea.

3 hours later...

Made the ticket to rewrite it.

I did nothing wrong at all.

The API just has no workflow at all. The
*seperate* API calls have to be in an **specific** order - as otherwise the generation will fail, as the prerequisites for the generation are not fulfilled.

Yeah. Completely logical. Especially not to give out any kind of warning or an error message like requirements not met, blablabla.

I drank that evening 2 six packs of beer. I was raging mad....

Then gave that shit to another manager, as I never want to touch that nuclear waste again....

How can someone be so brain damaged -.-

- Implemented oauth1 - no body hashing
- URL contains credentials in plain text
- Used Azure API management feature as a proxy of the our API, however the documentation was on the our API, thus exposing the API URL with no management to developers.
- easy resource DDoSing because each trial user got a DB, the registration process did not have bot checks. You could literally freeze the db instance by spamming registration requests.

"XYZ is an API that allows you to throw a bunch of stuff at it, and it will generally do the right thing" - best documentation ever!

If you have an hard-to-use API, you need a fucking strong documentation. Otherwise, a fucking developer like me will get lost and will spend days and days trying to make it work. Man up that documentation, for God's sake.

I'm faszinated by some dev's ability to write legacy code.
Not maintaining but plainly creating code so horrible, that it can be considered legacy.

I wrote a new API for a silly Application because the old one had hardly anything to do with rest. At all. And despite the code being only 2 years old, it was still unmaintainable.

Now that I'm finish with this task, i got the next generation of the angular Frontend.
A guy wrote a completely new version of the frontend in angular5.
Only untyped variables, no documentation, no tests at all, no idea whats going on where,....

I thought my job was to adjust a few URL's and change some DTO's, but now i have to refactor everything again...
And the pain continues.....

We use at our company one of the largest Python ORM and dont code ourselfs on it, event tough I can code. Its some special contract which our General Manager made, before we as Devs where in the Project and everything is provided from the external Company as Service. The Servers are in our own Datacenter, but we dont have access.

We have our Consultants (Project Manager) as payd hires and they got their own Devs.

Im in lead of Code Reviews and Interfaces. Also Im in the "Run" Team, which observes, debuggs and keeps the System alive as 3rd-Level (Application Managers).

What Im trying to achieve is going away from legacy .csv/sftp connections to RestAPI and on large Datasets GraphQL. Before I was on the Project, they build really crappy Interfaces.

Before I joined the Project in my Company, I was a Dev for a couple of Finance Applications and Webservices, where I also did coding on Business critical Applications with high demand Scaling.

So forth, I was moved by my Boss over to the Project because it wasn't doing so well and they needed our own Devs on it.

Alot of Issues/Mistakes I identified in the Software:
- Lots of Code Bugs
- Missing Process Logic
- No Lifecycle
- Very fast growing Database
- A lot of Bad Practices

Since my switch I fixed alot of bugs, was the man of the hour for fixing major Incidents and so on so forth. A lot of improvements have been made. Also the Team Spirit of 15+ People inside the Project became better, because they could consult me for solutions/problems.

But damn I hate our Consultants. We pay them and I need to sketch the concepts, they are to dumb for it. They dont understand Rest or APIs in general, I need to teach them alot about Best Practices and how to Code an API. Then they question everything and bring out a crooked flawed prototype back to me.

WE F* PAY THEM FOR BULLCRAP! THEY DONT EVEN WRITE DOCUMENTATION, THEY ARE SO LAZY!

I even had a Meeting with the main Consultant about Performance Problems and how we should approach it from a technical side and Process side. The Software is Core Business relevant and its running over 3 Years. He just argumented around the Problem and didnt provide solutions.

I confronted our General Manager a couple of times with this, but since 3 Years its going on and on.

Im happy with my Team and Boss, they have my back and I love my Job, but dealing with these Nutjobs of Consultants is draining my nerves/energy.

Im really am at my wits end how to deal with this anymore? Been pulling trough since 1 year. I wanna stay at my company because everything else besides the Nutjob Consultants is great.

I told my Boss about it a couple of times and she agrees with me, but the General Manager doesnt let go of these Consultants.

Even when they fuck up hard and crash production, they fucking Bill us... It's their fault :(

> wanting to add an embed google maps to a website I'm working on for fun, with React
> Check the API documentation, excepted their iframe they create from your needs, not much info about how to set in a a js framework
> decide to check if anyone has already created something with React
> They did! 1 american dude, one polish, one last from idk where
> The rest is basic doc so let's try each of them
> Errors, errors everywhere
> Screens stays awefully white
> Spend 2 hours checking, checking and checking again each library
> Each of them have a different problem
> Fuck this, let's copy the iframe thingy from Google's doc, adapt 1 or 2 things because of React and run npm
> Google maps works on first try

I'm developing a web app, which is purely based on some commercial .NET driven API. The documentation is a 12 page MS Word file with incorrect parameters and non-existing endpoints. I think there's also a cronjob which purposely crashes their server every 15minutes. I just love getting client emails saying I need to fix my app and get my shit together.

When I started this job 4 months ago, I was given a grace period of a week to "get into the groove of the code". I asked the lead dev where on pulse (intranet) the documentation was, he laughed and then resumed what he was doing. I shrugged it off and continued scrolling through the code.
A week later, working on a story, I'm stuck at why a particular function exists. I say "it would be nice if there was documentation, where is that anyway?". Lead dev replies, "one thing you should know about this company, there is no documentation unless it's API related".
Last month's retro, 80% of our (mine and lead dev) problems were related to a lack of kt, I laughed.

Whoever created the google adsense/admob report api and its documentation : choke on my dick and die you fucking asshole.

API provider: include a signature based on these fields in this order. DO NOT ENCODE IT!

Implementation works a while, then..

*a wild apostrophe appears*

Signature no longer works.

API Provider: "oh, yeah we escape those."

Arrghhghghghhhghvhxmchsoxnsoxnwl

Not only is it a poor design for signing payloads, the documentation is shockingly poor in it.
Even the implementation example (which is supposedly from their code) doesn't account for any type of escaping or encoding.

Before anyone asks, I can't into details about the implementation.

Custom php api for huge known national software. No frameworks. Not following mvc structure. No decent documentation. Im the new dev and like how the fuck should i catch up before they think im not productive

Let's see what's on the menu today:

* Web Application Catastrophe Special *

Includes, but not limited to:
- Orphaned server processes in the configuration management cluster
- Microservice back-end architecture with no API documentation
- Poorly implemented cache microservice with no documentation
- Stale data causing everything to be shown as down in production, despite everything running fine

Cost: 1 developer's sanity

Google documentation sucks!

Lack of practical examples. They show us very simple example like clicking on button and then straight away redirect to API docs.
Wait, let me at least understand how things fit in together.

Me: Hey google where is step by step guide, at least for setup?
Google: We don't do that here!

rant && !rant
Our timetable for lectures are online as "rapla" eventsystem. I want to write a small app including a timetable. As I didn't found any way to get the lectures as JSON (Bad documentation of API) but only as formated (and ugly) HTML View, I just wrote a small node module that parses the html body with cheerio and fetches all needed data of each entry in a week. Worked out pretty well, will add more functionality.
Never felt so independent 🙌🏻

Things that piss me the fuck off about user programs(in this case text editors):

No fucking documentation or signs of it available, a promise from like 3 years ago to post: tutorials/actual docs and yet unfulfilled shit. Yet the author sells the editor, you can get a free version of it, but the extension api is only given in the paid version. It's like $12 bucks, which depending on where you are from is really the cost of a meal.

The editor in question is 4coder, seems like a good stack for building C/C++ based applications with a lot of cool utilities underneath, I see dudes using it to create a lot of cool shit online, but things like moving input, stopping the thing from formatting pasted code etc etc. Shit, even reaching the documentation is fucky, you get the names of the commands......ok...awesome...wtf do I do with these? Why do i need to watch a 20+ minute tutorial from the developer instead of being able to read a retarded ass tutorial regarding how to do the most basic shit? For an editor that is set to replace Emacs and Vim for developers inside of a windows platform....it sure is lacking AF in that regards.

I really want to work with this thing because it seems to be made with a lot of heart, just can't stand the fact that the documentation is lacking like a motherfucker

The dangers of PHP eval()

Yup. "Scary, you better make use of include instead" — I read all the time everywhere. I want to hear good case scenarios and feel safe with it.

I use the eval() method as a good resource to build custom website modules written in PHP which are stored and retrieved back from a database. I ENSURED IS SAFE AND CAN ONLY BE ALTERED THROUGH PRIVILEGED USERS. THERE. I SAID IT. You could as well develop a malicious module and share it to be used on the same application, but this application is just for my use at the moment so I don't wanna worry more or I'll become bald.

I had to take out my fear and confront it in front of you guys. If i had to count every single time somebody mentions on Stack Overflow or the comments over PHP documentation about the dangers of using eval I'd quit already.

Tell me if I'm wrong: in a safe environment and trustworthy piece of code is it OK to execute eval('?>'.$pieceOfCode); ... Right?

The reason I store code on the database is because I create/edit modules on the web editor itself.

I use my own coded layers to authenticate a privileged user: A single way to grant access to admin functions through a unique authentication tunnel granting so privileged user to access the editor or send API requests, custom htaccess rules to protect all filesystem behind the domain root path, a custom URI controller + SSL. All this should do the trick to safely use the damn eval(), is that right?!

Unless malicious code is found on the code stored prior to its evaluation.

But FFS, in such scenario, why not better fuck up the framework filesystem instead? Is one password closer than the database.

I will need therapy after this. I swear.

If 'eval is evil' (as it appears in the suggested tags for this post) how can we ensure that third party code is ever trustworthy without even looking at it? This happens already with chrome extensions, or even phone apps a long time after reaching to millions of devices.

Started porting one application written in php to:
Golang(and some libraries to make certain sht simpler like GORM and Gorilla amongst a couple of others, most shit is STD shit already built in)

Java Spring(I know it well, but wanted to try this particular app in it, lots of boilerplate although the coded is solid AF)

.NET Core API, which I separated in a series of modules for the domain interface, the persistence logic, the actual api etc, I really dig it. It has a basic React frontend in Typescript whereas the other 2 versions are using the standard Go html/template package and the Twig interface for Spring.

My favorite thus far is Golang. I find it extremely easy to extend, the language reads good enough for a retard like myself to make sense of it fairly easy, really easy to test and experiment with it, any idea I get for something to add(say users and stuff) took me less than 30 mins to figure out while reading the actual documentation, as in the base documentation or just the source code.

I know the language is retard proof, and I am highly enjoying this. Not to say that the other two are bad, not at all, been using C# and Java for years now, but I highly appreciate being able to concentrate on functionality rather than all the fucking architectural boilerplate needed to run basic shit in the other two frameworks. Thus far Golang has been a breath of fresh air the likes Clojure gives me, while not even being a profound or mind blowing language in terms of features(since other than the interface{} and goroutines i can't think of shit) and have not reached a scenario in which I am stuck or dying to have generics one bit for the overall business logic.

The app is growing like crazy in terms of code since the original php application was huge to begin with, but dear me this shit is as simple as it can get without being too technical. Might move it to production once all usability tests pass and force the rest of the staff to learn it. I have one lead dev that damn near refuses to touch anything other than php, and a very eager to try shit out content administrator that comes from a Java and C# background.

all I want to say is how much I love go haha

APIs, APIs, APIs... I feel like building an API for everything which goes over the wire is a must-have today! Yes it makes sense for decoupling purpose, access control etc (all the things we learned from OOP design principle books when we were in school) but come on, REST API for internal database access when there is something like SQL over JDBC/ODBC/WhateverBC ?? So I have to study the REST API documentation for applying simple where-statements but in API manner...

I talked to the client how functionality should look like on UI, draw a mockup, designed and made changes to db schema, created REST api, made documentation how to use it, told frontend developer to make changes on frontend application according to the documentation and mockups. Still no one have fucking clue how to do it. Fucking testers can’t write anything, only clicking.
So I sent curl code how the fucking request should look like exactly then resolved bugs they reported as won’t fucking fix because I will not be also making fucking frontend. Probably they even don’t know what curl is. What a fucking fuck.
And that’s what I am mostly doing from Monday till Friday to keep this project going.
It’s cause client are nice guys and we are doing something good, not some fucking ai, blockchain, big data, financial scam everyone is wanking around.
And friends are asking, why I drink.

So I made an inquerery for some API documentation..

They escalated the ticket to 2nd level support from what they already called tech support.. why have API integration as a feature then??