City of Broken APIs: A Noir Testing Thriller

OpenAPI

I have known Swagger for 5 years. I won’t say it was a close relationship, although we used his services for a previous case, which is even mentioned in my resume.

I used to brag about it because I know he has become a bigger name in the industry since then, but I had a close connection with him back then.

At that time, he had more competitors who were equally serious professionals. However, the situation has changed in the past few years, and he has become almost dominant. Those who had trouble with APIs turned to him.

Meanwhile, he has grown into a small family business. In the past, all he could do was describe an API nicely. He was a master at describing and sketching APIs, like a biologist organizing plants. He worked meticulously and precisely, and his work stood out from the rest.

You could recognize his work from a hundred others. I could say they were all the same in terms of quality. Then he involved his family members as well. One of his nephews worked on websites and showed how a well-designed API should look. His daughter tested it.

Others envied his success and started imitating him. A young guy who used to work for some famous and boring multinational company began copying what Swagger had accomplished. Even his name, OpenAPI, reveals a lot about his methods.

I’m not exactly sure about the difference between the two; both describe APIs and perform magic with them. OpenAPI has even more extensive knowledge; it’s no longer just a family business. They work with large companies, either as subcontractors or in some other way.

It’s a bit unclear because they don’t openly accept money, but you know, doing so much work for free is not possible.

So when there was a case that required API development, my first choice was OpenAPI. More precisely, Swagger at first, but after the first serious consultation, he mentioned his hourly rate and explained that he is busy lately, so he has to charge his previous clients as well.

Alright, I thought, and I rolled over to the office of OpenAPI, just a few blocks away from Swagger’s place.

It was a modern office building with a reception service and access control system; everything you need. The secretary offered me coffee to pass the time while I waited. The boss would see me soon. In the meantime, I looked at the posters on the wall.

I was amazed at all the things you can do with an API beyond just describing it. The company had become so international in such a short time since its establishment, offering tools in various languages, including TypeScript, Golang, and Python, not to mention those I had never heard of.

The secretary brought the coffee, and I asked for an espresso with two sugars and no milk. I find this new trend of diluting coffee with milk rather unmanly, like diluting wine with soda. She forgot to ask me which boss I was meeting with.

You see, the business is run by a pair of siblings, Vetwo and Vethree, or rather three because their youngest brother also joined. He’s a clever guy, resembles the middle brother; there are only a few years between them.

I voted for Vethree, who already has some experience but doesn’t hold too outdated views.

A few minutes passed, and a man in his thirties appeared, casually elegant in a sandy summer suit, with a hairstyle that suggested a recent visit to a hairdresser. We shook hands, and he gestured for me to follow him.

As we walked down the corridor, I could see into the other offices separated from us by glass walls. In most rooms, I saw the usual guys in t-shirts sitting behind huge monitors.

For a moment, nostalgia swept over me, a memory of when I used to be one of those guys, wearing a black t-shirt, stubborn and thinking I was worth more than an entire corporate IT department.

“Can I help you, or rather, can we help you?” Veethree from OpenAPI finally asked after we arrived in his office.

“I’m not even sure myself. I had a case with Swagger before. I found him talented and knowledgeable, but lately, he’s been acting strangely,” I replied.

“I completely understand. It’s not my intention to speak ill of him behind his back. That’s why my brothers and I decided to get into this business as well. Nowadays, there’s a saying that data is the new oil, and there’s some truth to it. But without APIs, everyone is just sitting on their own data.”

I sighed. Lately, several potential clients had asked me about my API expertise, and upon seeing my lack of enthusiasm, they ended up choosing someone else for the job.

OpenAPI may have misinterpreted my sigh. “Let’s clarify the basics first then. An API is the means through which we can communicate with a service. The API defines what questions we can ask it and what responses we can expect.”

“Thank you, I understand the basics, but…”

“Great. When I mention questions, I’m not referring to specific queries, but rather the ability to request customer data from the service by providing a customer ID. The response would include the customer’s name in text form and their address, which is a bit more intricate since it includes a zip code, as the name suggests, a number.”

If he continues explaining everything from scratch, we’ll be sitting here until evening. I nodded approvingly, wanting to get through it as quickly as possible.

“One of our innovations is precisely about this. Instead of just dryly describing a possible question as ‘/users/{userID}’, where ‘userID’ is a number, I also provide an example. I would say that if the customer ID is, let’s say, 111, then the response would be something like {”name”: “Winnie de Doe”, “address”: {“zipCode”: 55555, “street”: “Sunset Boulevard”, “houseNumber”: 1}}.

”And is there a way to verify, once an API is thoroughly described if a given backend meets its requirements?”

“Of course, we only release work that has been verified to be in good shape. We run several checks to ensure that everything is in order.”

Yes, that’s exactly what I need. “Then we can come to an agreement. My assistant will provide the necessary information to your secretary, and once they have it, they can start the work.”

We shook hands briefly but firmly. The elevator took us back to the ground floor. I bid farewell to the receptionist with a friendly nod and stepped out into the early afternoon sunshine.

Postman

The next day, I had to tie up the loose ends of a previous case, in which, incidentally, a cat turned into a zombie played the lead role. I’ll tell that story another time. The essential thing is that the next morning, as I entered my office, a fax was waiting for me.

It was sent by OpenAPI. It was a short text, fitting easily on one page, but it contained a rudimentary API description. The simplest question one can ask an API is this: How are you? Are you doing fine? In API language, it’s /health-check.

There’s no need to say anything more, no need to send any identifier. The response is also quite simple: {“status”: “OK”}. However, it could also happen that the service is not in good condition, something is wrong with it.

It can’t reach the database, it can’t find some configuration, oh my, there are so many ways a system can break. Sometimes, the trouble is so severe that it can only utter: “Internal server error.”

As Tolstoy wrote, the story of happy families is one, but the forms of unhappiness are countless, and the same goes for errors. A comprehensive API description includes what the response will be in problematic cases. For now, I only considered the optimistic scenario.

I easily determined that my client’s backend responds appropriately when queried with the health-check. I just glance at the source code and read the line where it returns the OK status. But I can’t sit there for every change.

What if someone changes the OK to UK or something else in the source code? It could happen accidentally or as an intentional sabotage. OpenAPI claimed they have people to verify the API description.

More precisely, the backend. Because the time will come when the API description becomes the truth, and everything must adhere to it.

I called OpenAPI to request a list containing the contact details of the inspectors. I didn’t find it there. The secretary connected me to one of the department heads, who listened to me and promptly promised to fax me the list.

While I waited for the fax machine’s clumsy, crackling sound, I started browsing the professional phone book. I didn’t find anything specifically about API inspectors, but on the first page under the API keyword, a framed advertisement caught my eye: Postman.

I had heard about it before; some of my colleagues had worked with it directly. In the industry, it could occupy a prestigious position, like Swagger did in its time. I knew it worked on the web, that’s all.

I had never really thought about how a web thing interacts with a backend, which is right here in my office. I had flirted with the idea of trying it out sometime.

Nowadays, if you don’t know Postman, you’re not considered a serious player in the API field.

It has a toll-free number. It’s worth a try. I dialed the number, it rang, and a pleasant female voice asked if I’m in their database. No, I replied.

Then she asked for my name and phone number to register me. I suppressed a curse and hung up the receiver. After all, I just wanted to ask a few questions, try out what this Postman can do since it advertises itself with a toll-free number. I brewed a sage tea to calm down.

Ten minutes later, I called again. This time, a woman answered, explaining that I must use the Postman services on the web; some people are hesitant about it. They have Postman Desktop in their office, and they can send it to me. It does almost the same as the boss.

I seized the opportunity. The woman promised that Postman Desktop would contact me soon.

As I hung up the phone, the fax machine began to crackle, and a page snaked out of it. It contained the names and contact information of the OpenAPI inspectors.

At the top of the list was a familiar name: Postman.

From experience, I know that the biggest name in town is not always the one that provides the best service. It’s worth exploring the others as well. Here we have Portman, a similar name, which could be a mere coincidence.

Although it’s such a niche profession that such a level of coincidence would be suspicious. I marked an X next to the name on the fax paper to look into it later.

I continued browsing the list. Most of the inspectors work with JavaScript, with a few using Golang and PHP, scattered with the occasional Python and others. It doesn’t matter much as I have some experience with each of them.

My client swears by PHP, but perhaps I can convince them to have a change of heart. It’s difficult to choose.

Over the next half hour, I marked a few more contacts. I stood up to stretch a bit, which naturally led to brewing a strong cup of coffee and lighting a cigarette. The smoke, as it obscured the air, cleared my thoughts. Then I realized I was just procrastinating.

I sat down and started calling all the marked inspectors on the list. That’s when there was a knock at the door.

My secretary poked her head in, apologizing for interrupting my morning, knowing it was my most productive time of the day. Someone is waiting for me outside. They’ve been sitting there for a while and are getting impatient. I told her to send them in calmly.

A short, middle-aged guy appeared, clutching a thin leather briefcase in his hand. “Mr. Postman sent me,” he said, patiently standing in the doorway.

“Ah, welcome. I’ve been expecting you. Please have a seat,” I quickly moved the accumulated papers from the armchair opposite my desk.

He sat down, placing the briefcase on his lap and smoothing his round, bald head. Clearly, he was waiting for me to present my needs.

“You see, there’s an API for which a description is being prepared. I know you also deal with this, but I entrusted it to OpenAPI,” I began. He elegantly spread his hands, which could mean that a dear client does as they please, even if it’s utter nonsense.

I continued, “The essential thing is that it needs to be verified. More precisely, whether my client’s backend complies with the specification written by OpenAPI.” I pretended as if that certain specification had already been completed. Let it be my problem that it’s not entirely true yet.

“No problem,” said Postman Desktop.

“Could you show me an example so that I can better understand how it works?”

“Of course,” he opened his briefcase and pulled out a thin notepad. “For this, I’ll only need a few details. Name, phone number, and such.”

I felt my face turn red. I took a few deep breaths, employing the good old 3-6-9 method. “You’re being petty,” I scolded myself, “just give your name, and that’s it.”

“I’m afraid it’s not possible,” I finally said, after calming down somewhat. “Perhaps later.”

Portman and Her Friend

My favorite café is located just around the corner from the office. There was a signboard advertising hamburgers for lunch in front of it. Although they were reasonably priced, I didn’t feel like having one. I decided to visit Portman instead.

I knew the address; it was close to the riverside. Just like another name on the list: Vacuum.

I had never heard of it before, but its motto sounded interesting, and judging by the address, it didn’t seem like a major detour.

I arrived at a single-story, modern building with large glass windows. A young woman opened the door in response to my ringing. I showed her my ID.

“Ms. Vacuum? I believe you specialize in API testing,” I began, intentionally cutting off the sentence. I expected her to invite me inside. It’s better not to linger in the doorway.

She didn’t seem bothered by it and nodded. “Exactly, and I work extremely quickly. What takes others a week to accomplish, I can do in a day.”

“We work with OpenAPI. We’ve also requested additional features, such as writing examples for the API requests.”

“Of course, I can also verify if the examples are valid.”

“I’m sorry, but that’s not the trick. The goal is to check if the backend behaves according to the examples. When I ask it how it’s doing, I expect to receive the pre-agreed {”status”: “OK”} response, not something else.”

“For this task, you’ll need to find someone else. Good luck!” the woman said, and she closed the door. There was no irony in her voice. It seems that nowadays, even someone who only does half the work is called a tester. I felt sorry because I found her perfume quite pleasant.

It wasn’t worth getting back in the car for such a short distance, so I decided to walk to the address two blocks away instead. I found an old-style office building there, with elegant doorbells mounted on a brass-framed signboard at the entrance. I ran my finger over the names.

Portman was nowhere to be found. At the doorbell on the second floor, a fancy sign proclaimed: APIDeck. I pressed the button twice quickly. The gate buzzed and clicked, allowing me to enter the cool staircase, and I took the elevator to the second floor.

As I stepped out, I found myself in a corridor with doors on both sides, each with a label. I couldn’t find anyone to ask for directions. Fortunately, at the bend of the corridor, I saw a black sign with golden letters: Portman. I knocked, silently counting to three, then opened the door.

I entered a tiny room with two filing cabinets and a desk near the window. A middle-aged woman in a discreet floral suit sat at the desk. Even while sitting, her posture indicated an athletic build.

She was deeply engrossed in studying the document in front of her, but she looked up and pushed her glasses up to her forehead.

I wanted to show her my ID, but she waved it off as if she didn’t care about such formalities. I briefly explained the purpose of my visit: OpenAPI, examples, and testing. I didn’t mention my visit to Ms. Vacuum.

“Yes, that fits my profile,” she said after listening to me. “Let me explain more precisely what I do.”

For the next ten minutes, I struggled intensely to concentrate and grasp the essence. With little success.

“Let’s clarify a few simple questions first,” I interjected. “So, are you web-based or console-based?”

“Strictly console-based.”

“That’s good news. So I’ll give you the OpenAPI specification and the backend, and you will test it.”

“Almost. I’ll write a bunch of test cases.”

Hmm, it seems everyone has a different concept of testing. “And who will perform the testing then?” I asked.

“I write completely standardized tests that can be given to Postman as well,” she replied.

The circle closed. “It’s not a coincidence that Portman and Postman rhyme,” I remarked.

“Why, what do you think?” she inquired.

“To be honest, I have certain reservations about Postman. For example, it being web-based. There’s a colleague of mine who works on the desktop version,” I explained.

The woman stood up. I was surprised by how tall she was; I didn’t notice while she was sitting. “I have a colleague who works on the console version, he might be interested,” she suggested.

“What can he do?” I asked.

“He can perform the testing,” she replied.

“Does he need anything else besides the standardized tests you write?” I questioned.

“Absolutely nothing. I’ll just send him the entire Postman collection through a courier, and he’ll be done by the next day,” she explained.

“Postman collection?” I asked suspiciously.

“The standardized test I was talking about,” she clarified.

Judging by the name, I could imagine how standardized it was. Anyway, if enough people know about it and accept it, why should I have any objections? “Alright. Please give me your friend’s contact information,” I requested.

The woman took a note from the shelf, scribbled something on it, and handed it to me. The address seemed familiar. Then I read the name. Newman. Well, another figure from the same gang. It reminded me of where I had seen this address before.

That’s where Postman Desktop came from.

“Where does your friend work?” I asked.

“At Postman,” she replied.

“So, Postman started the business as a web-based service, then realized it wouldn’t appeal to everyone. That’s when they approached Newman,” I deduced.

The woman shook her head. “It’s something like that. I would rather say Postman nurtured him.”

I knew the next step I had to take.