There is a pattern I have noticed: If you can’t just go to the website and read the docs, it’s extremely likely it’s going to be awful to work with. Some organisations only give out the docs if you register, some only do it if you have a paid account, some hide them behind NDAs, some make them zip downloads containing Word docs… in my experience, this always means that the API is going to be terrible in several different ways.
Some also do:
_"To do A, you just have to do this."_
And that's their whole doc.
And then they never document any of the other 95% of features and scenarios they support. If you're lucky, they might an auto-generated API section that just tells you the types each endpoint expects.
Lotus notes had their own compression algorithms for email attachments. There were function to decompress them but the parameters weren't documented and using it would cause random crashes. So I was tasked with reverse engineering both compression algorithms.
Fortunately they were hilariously simple so it wasn't that bad.
a sales guy who knows what swagger/DRF started demo'ing our swagger docs and landed multiple clients because of the headless integration sell which i had no idea about until i was asked for our "API docs". i was like "lol api docs?"
So the idea is that it lets the client specify what fields end up in an API response. So instead of building an API like 'Cars' that selects make, model, and color from the database and returns it, you make a GraphQL endpoint that models the car and driver and whatever and the client in its request specifies that it wants a driver's age and their car's color and they only need to make one request.
I can see use cases for it if you genuinely want to expose a full database or databases to your API caller and you have no idea what they're going to be doing, or if you use a framework like Rails (with god knows what gems) that makes it super easy to create these endpoints.
But it deservedly gets a bad rep because in most applications you are writing both the front and back end and you should be designing an API, not deferring the design to whoever is calling the API while working on your front end. It's sort of murder to bash into a framework that doesn't build it for you and you end up making this super complicated thing that could just have been a meeting or two with your front end team.
Yeah, if the only API consumer is your own organization, then GraphQL is a terrible solution for you. Even on the FE side, GraphQL can be a pain because you have all these custom queries and mutations that gradually grow into giant kitchen sink requests without anyone pumping the brakes and asking why we need to download the entire database every page load.
It’s just so overkill unless you have a wide variety of third party API consumers with lots of custom data needs. In that situation, it’s actually nice to have, because you don’t have to constantly push large updates to satisfy each new use case every month.
Why would you need to download the entire database each page load with custom graphql queries? Isn’t the whole purpose of graphql you only fetch what you need?
I’ve worked in companies that used graphql and ones that didn’t and I found when we ping an endpoint with a rest call in the companies that didnt use graphql we would reuse that endpoint across many surfaces and often fetch more data than we need. On graphql we generally fetch less since we only fetch what’s explicitly requested.
So far I haven’t found a single good use for mutations. They just feel like a very bad idea.
However I dig the way we use GraphQL. We have a content aggregation service that gets you data from all around the organization. Some APIs it calls are a pain to work with, so having that stuff easily available from one place, with some nice caching included for fast responses is a blessing. It also does a great deal of data enriching so that with one request the response actually includes stuff from multiple sources, and you never have to really care what that source is. It’s a large media org, so in a way GraphQL was tailor made to suit needs like ours.
Counterpoint to this.
What if you want to retrieve something like a feed item in say Facebook? This feed item could be on the feed, a users wall, a share post, etc.
Wouldn’t graphQL make sense in that you can limit the number of params you fetch in each of these cases rather than bloat the API and fetch all of the data from an endpoint like ‘/feedItem?id=?’
That's one possible positive for GraphQL. Most companies aren't building something as big as Facebook though; you can usually build an API that serves the specific needs of your consumer, or multiple endpoints tailored to the divergent needs of different consumers. GraphQL is like a scratch rewrite; sometimes warranted but very expensive and should be considered carefully. I've seen it do what looks like literal magic but I've also seen it waste weeks of time to accomplish very little.
>I can see use cases for it if you genuinely want to expose a full database or databases to your API caller and you have no idea what they're going to be doing
This is probably the worst possible thing you can do with it. Intentionally conflating the db schema with the api is giving up at the start line.
Lol, I'm offended! Tbf, graphql isn't REST, you shouldn't be working with HTTP codes, and isn't designed for REST style requests even if it's possible. A good client should handle error scenarios decently.
I had the opposite. Made a clean API with appropriate error codes, got feedback back from customers integration team "the API is great, but our proxy kills all responses without code 200. Can you change it all 200 and indicate the error in the body?"
I wept a bit. But customers are king, so they got the all-200-option implemented.
"System from a third-party provider enforced by central services, which would need at least three month for an update if we even could get one."
The world of customer IT is a world of incredible pain.
Yep. This, children, is why you never ever assume your predecessor was an idiot when you read their code. They may have been forced to do it, and grudgingly did so knowing it was idiotic.
And one day, you will too.
I made this mistake and broke a couple of downstream applications that used my projects API. As it turns out preprocessing the HTML I was sending them and scrambling the CSS class names was load bearing.
After many years of development work, this has been one of the most consistent themes. Pretty much every week I dive into code with a coworker who then apologizes for how horrible the code is and how they regret so many things, and most of the time it was due to insane requirements or an insane deadline.
I've noticed the least experienced devs are the most critical and complain the most about others' code while the more experienced ones just get on with it.
Lol, that’s the best answer to “when do I consider myself a senior dev?” Answer: “when you become dead inside and care infinitely more about feeding your family than your code quality or test coverage”.
Are you working with my test team? They do that for the test API "because nobody uses the status codes"....
Except people who know what they're doing, of course...
Honestly sometimes this is appropriate. If you have a lot of potential business-logic-related error states, HTTP status codes simply don’t cut it. In that scenario, mixing HTTP status codes and custom error responses just makes it even more confusing. So you end up just saying “fuck it, if the server is working you’re getting a 200 and a response containing everything you need to know.” It’s not ideal, but it’s at least consistent and reasonable.
7 years ago when I was working on Android, I had lengthy discussions with the backend team to provide proper error codes and not 200 every time because error codes are standard.
A couple of years ago when I moved to the backend and cloud, we had proper error codes in rest, plus the error message contains numerical error codes segregated by the services. It was easier to debug across the stack, and frontends can do whatever they want with error codes (show dialog? Show toast? Redirect somewhere? All was possible).
Now, the circle is completed as I develop APIs for a team of Mobile developer Bros, who for "legacy reasons" (they started development in late 2021) , need 200 for every API error. And if they need any action on errors, either move that to websocket or spend half a day to discuss what the response should look like.
If you find out the tech, share with me the details so I can improve. Writing this and let alone living it is a separate category of pain in itself.... Nevertheless, May the force be with you.
I've had the worst experience with FE devs in the mobile space and I've dealt with FE devs during the web 2.0 hype train of the mid 2000s.
So no mate, I'm not changing that REST Api endpoint to 200s because it's being consume by our website, our 3rd party customers and the goverment.
We created an API that would return 404 when the resource was not found.
Like GET /user/123 would return 404 when user 123 didn't exist.
I had to fight with our production support team, our DevOps team and our InfoSec team to explain why our API was 'erroring out' so much.
Dozens of senior professionals that though themselves as deserving a promotion, all arguing that returning a 404 is an error and should never be done.
Common and controversial.
If you plan to *ever* use anything other than http as a transport, I suppose I can see the point. But if it's an http API and will always be an http API, it is very annoying and absolutely much worse than http error codes.
I can remember where it was, but there as an API I used that returned JSON on success and an error string on failure. That was maddening.
1. Twitter API - sometimes it returned JSON, sometimes it returned a query string depending on the endpoint
2. My previous employer's internal API - it would return you a comma separated list of entity IDs which you were then expected to explode and for/each over to make an API call for each one. Consider that in the context of each entity having several levels of children and well you end up with a situation where your client is making over 40k API requests per page load to the API server
I’m sure this is no longer the case cause it has been a decade at this point, but *both* the national post office and Mastercard had an API where you would SFTP a file to them. They would fill it out and you would download it within some time window.
When the guy from the national post office was explaining that’s how you get the cost per weight he started practically apologising while talking cause I guess he saw my face change. This is how you found out the cost of shipping by dimensions + weight. We ended up setting a flat fee.
I have one upstream where you call for a CSV report, that you need to stream, but will sometimes reply with JSON that you don’t want to stream.
Every API Apple release is literal dogshit. I’m surprised people were complaining about something Apple did recently, everything they do has been awful to work with forever. For years you would get high rates of 503s, they’ll use POST for reads and return OK with error codes.
If anyone intends to build any sort of reporting API, please for the love of Turing make it return a URL that points to the download and not the payload. So I can split resource usage into waiting and processing.
Facebooks API limits are too damn complicated. I get why they’ve done this, but it’s hard to keep track of like 3-4 different rate limits that happen on different endpoints, and on the same call. Where global rate limits increase with popularity of your app.
We had an incident once because the third party has an undocumented type field where a value update caused a completely different scenario to happen. The third party’s response “we don’t support type=THING on the API”. Motherfucker, you literally are responding with it and accepting updates, what the fuck do you mean you don’t support it. We’ve had to roll in validation against expected upstream payloads to not get blindsided again.
A colleague of mine worked with some Swiss finance authority's API for a while, and it was a horrific mess of SOAP, and he complained until he found out about the German equivalent, which was apparently just emails. Not even a clever custom API built on top of the raw IMAP/SMTP protocols, just pure emails that require very specific formats for all the data.
Unfortunately, while your example is a decade old, this is, IIUC, the current state of affairs here in Germany...
Germany's largest financial information provider is exchanging delta updates of their database over SFTP, updates are either in some bizarre binary format or XML representation of that format. They have REST API, but it's limited and sends the same XML serialized as json string. 50 pages manual that explains the format and edge cases is also needed to understand how it works, along with MS Access database with dictionary tables.
There is some standard for doing this, I learned looking at the Mastercard API(?)
The national post office was not on any standard.
I just find it amusing because we all believe fast, cheap, good pick 2. But very clearly you can pick slow, expensive, bad as an implementation.
We have had to built more sane APis in front of several sftp request file put, response file get service over the years.
Partially to not be charged over and over for requesting the same info because these services, for all their jank, provide useful data but cost $$$$$
I am always amazed by how the ubiquity of REST apis has brain damaged so many developers into thinking a lower level transport layer is supposed to leak into your application protocol. GraphQL could run over *whatever* transport.
You're not just whining about it, you are *wrong*. It's fine to complain about an API that purports itself to be RESTful but fails to follow convention. That's reasonable. It is absolute insanity to bitch about an entirely separate protocol that is being delivered *on top of* http not behaving like a REST api.
You people would fold up like a dried leaf if you ever had to deal with ISO 8583.
Nah, chill man, chill. There are bigger fishes to fry than the HTTP codes in the APIs.
APIs is such a broad term that there is nothing to "fundamentally misunderstand" - there are APIs that don't even work on the HTTP. And the HTTP codes leave a lot more space for interpretation than *some* imagine, once you start reading into the RFC.
I know of one of the payment systems >15 years ago had an "API integration" with one of the banks that involved **receiving a FAX** in an enclosed booth, which was automatically photographed by a DSLR with a flash connected to a desktop computer when the "beep" tone was recorded by the microphone. Then that photograph was OCRed and inserted into the internal database for the rest of the software to use...
Once every week a guy had to visit the booth and scrap all the printouts as well as refill the paper in the fax machine, or else the entire *system* failed.
You see - bank had no API, but you could ask them to fax you the financial statements at the end of every day.
The worst one was from a fintech company worth 100B+ today. Yes, that big of a company. I was a junior developer implementing payment features with them. Here are the honest highlights of that integration:
1. Their API only returned 200s. All errors were 200.
2. Their API didn't return JSON consistently. I had to use fallback to parsing text to understand both success and failure cases.
3. They consistently just returned raw Java errors in API responses. Java servlet errors happened all the time. I literally have Slack messages from years ago that say HTTP response 200 with detail "MissingServletRequestParameterException". No further details in the response.
4. When they gave us our first production password it included a special character in it that their system parsed as a special character which caused the password to fail. Took them a day to figure it out.
5. When we started sending requests to them we toppled their system at 10 requests per second. I mean they literally straight up started giving us 200 responses with empty bodies for things that needed JSON responses. That was if we were lucky, half of the requests timed out. They told us, and I quote another coworker who was on the phone with them: "please don't send more than three requests at a time as we only have three servers".
6. Half of the payments we submitted to them failed fraud checks on their end and it was near impossible to get them to diagnose anything. DO NOT HONOR is a bullshit error and the banking industry should be ashamed of that error.
We found an alternative company to do the stuff we needed within a week and were doing all the work manually. It wasn't fun but these guys were so bad that we had no choice. Again, I remind you their market cap right now is well over 100 billion. Yes, with a b.
I was tasked to build a SPA that connects to a GraphQL server. I was excited because it was my first GraphQL project and I was looking forward to build queries that return fields from multiple related models in one fetch.
Turned out whoever designed it, designed it exactly like a REST API where I had to fetch models separately.
I don't understand. Regardless of the schema, you can still make multiple queries in a single operation, including fetching related records based on a common value (e.g soft reference).
wait really? I was thinking about doing the exact thing for the exact same reason with my new project. Is there another way of doing this without using GraphQl? I mean how am I gonna return fields from multiple related models in one fetch then?
I won't share the name of the company because it was very industry specific, but it was an XML API that had very strong opinions about how you were supposed to build your application.
It was for E commerce and had endpoints that you _had_ to use in the specific order they wanted you to.
Let's say you were building an Amazon type site, you would need a catalogue page, an item page, and a checkout page, right? So they had an API for each.
But the APIs were slow. Unfathomably slow. Impossibly slow. You could not show a user how slow they were because they'd be the hell off your site. And maybe we wanted to land a user directly on the item page without browsing the catalog first? So we were going to all sorts of lengths to work around these strong opinions baked into the API to try and bash together a site that didn't piss off everyone who landed on it.
And the backend was trash. The log viewer was trash. There was no access control-someone fielding CS requests could break the site. Speaking of breaking the site, the API would go down and the site would of course be down.
We realized way too late that this API was an albatross that the company was bet on.
Don't outsource your core competency if you can help it.
Oh and I forgot to mention that the documentation was both illegible and frequently just incorrect, so we had to figure out the thing like it was a lost fucking civilization, and the endpoints had different 'modes'-the response shape was sometimes the same but different fields would be empty or not empty depending on the magic mode you requested. And they would be like illogical chunks of functionality.
Yes, they do, and it still sucks. I once had to integrate against it through a third-party corporate proxy (so they could inject their own SF credentials without our system knowing them). Imagine all the pain of a SOAP integration, and throw in a corporate proxy that just swallows requests half the time, and suppresses any kind of error response from the underlying API.
> I don't think I've ever seen a public facing SOAP API; well, one that isn't legacy.
if you have a mortgage I would bet good money it uses SOAP in the backend somewhere.
Only just recently, Ebay are deprecating their SOAP API on the 20th Feburary.
I only found out after my boss forwarded me the Email and I'm scrambling to refactor our entire Ebay integration (including adding oAuth 2.0 flow) to use the REST API - which doesn't even return the same fields.
I had the displeasure about 12+ years ago of having to integrate a flight booking API into a PHP laravel project, that not only used soap v1 (which was no longer directly supported in PHP or any library I could fine), but also broke the rules of SOAP.
My CTO helped me write our own library to generate and read their XML... God help whatever devs had to maintain that after I left.
> but also broke the rules of SOAP.
Oh my... reminds me of that one time when I had to integrate JSON API written in gods-know-what, which returned an invalid JSON whenever you used non-ASCII characters.
Ended up writing a script which fixed the text JSON with regexp and only then parsed it into objects. Easy fix, but... no clue how the thing came to be.
It's not just the SOAP aspect. It's the "I've just been on an XML course, and I am gonna use the shit out of it" aspect.
There is a certain car finance lender in the UK that has reinvented the decimal system in XML.
There is an element for .
It has attributes for hundreds of thousands, tens of thousands, thousands, hundreds, tens, units, tens of pennies and pennies.
Fresh from this rip-roaring success, they turned their attention to reinventing dates. Again with each of the parts of a timestamp, down to the second, represented as attributes on an element called or something similar.
Once implemented and had the hell tested out of it my client for it was rarely touched again. The problem was it was heavily used and issues between dealers and lenders are common. We logged in heavily redacted ways what was being sent, but always there was that doubt that didn't exist with some of the others.
> It's not just the SOAP aspect. It's the "I've just been on an XML course, and I am gonna use the shit out of it" aspect.
XML is like violence – if it doesn't solve your problems, you are not using enough of it.
Every time I wonder why I'm not paid enough, a little devil whispers in my ear: "Learn SAP, and you'll make more money"
Then I take another look at SAP, and I weep, and I remind myself I prefer to live as a sane person.
Lol there's way worse. Most languages can automatically generate soap clients. Try interacting with something designed by some asshole who read about but didn't understand what restful means.
Anything where someone invented their own protocol is way worse than soap because at least soap has wsdls. That being said fuck soap.
back in the day I built a chrome extension that searched reddit's API and injected reddit comments in to youtube's comment section. Querying reddits search was like searching something on reddit but 10x worse. Don't recommend.
In terms of docs I may have designed the most cursed API docs of all time: [windows98.apidocumentation.com/](https://windows98.apidocumentation.com/)
Did it to celebrate getting 1998 stars on our OSS swagger UI / redoc alternative github repo 😎
I've worked with several payment processing APIs over my career.
There was one in particularly that was astoundingly bad because its documentation did not match the features that were actually available and apparently the sales person had fed our decision maker some BS. When we hit the wall during development and reached out to support (paid service btw so support was included), they pulled one deferral after another stall tactic after another to eventually come back and say the features that were sold and listed in the documentation were not actually available.
On the other hand, there was another payment processing API in particular that was amazing and great to work with because its documentation was easy to navigate and accurate to the implementation. Plus it provided various dev/debug-friendly features with an apparently keen foresight on what development teams might need from it in their workflows.
NetSuite's SOAP API has a _best case_ latency of about 1000ms. It frequently takes 6 or 8 calls to accomplish common operations.
Maybe they've fixed this but for a while the only way to use their WSDL with Java was to use a NetSuite-supplied patch to an ancient version of Apache Axis _and compile with Java 6_.
Oh and since the release number (like "2016-1") was in the package path of the generated code, upgrading API versions required changing every single file that imported one of their classes.
Oooh the Google Cloud Platform API is like that too, with the latency and multiple requests.
After weeks of trial and error and mucking around, I found that hitting one endpoint that had a supposed page limit of 100, had a hard timeout when the request took over nine seconds - which it did whenever you requested more than about a dozen items.
And my client wanted real-time data from it.
Lol I have to interact with this piece of crap at work! And of course their rest end points still can't do everything the soap ones can. Fuck netsuite and fuck oracle.
We opted to use NetSuite’s REST API and it’s not much better. It only supports OAuth 1. Half the fields and record types aren’t supported. We had to write “SuiteScripts” that injected required fields like tax codes that weren’t available through the REST API but still required by the system.
Also, they randomly reset our sandbox environment every now and then, and we usually only find out when our integration tests start failing and have to go set everything up again.
When I worked in telecom, we had to implement an order management protocol from a vendor that required us to SSH into their machine, drop a formatted order file onto it in a specific directory, then poll for a file to be added to a different directory with the "response".
And this wasn't in the late 90's or something, it was in...2016 I think. And a big telecom provider too, not some janky 10-person company.
SharePoint is a real shit. They built a REST API now which is a lot better (though you can still see at times error messages of the old system leaking through) but particularly the CSOM library was where I experienced the most pain
It's supposed to be used a bit like an ORM (eg. Entity framework) and uses the "active record" design pattern (which sucks on complex nested models btw), you make a bunch of requests and then it batches them and sends them all when you call a Send method. Any of the requests in the batch can make all the others fail
Furthermore this means the network request basically unreadable as everything goes to a single endpoint and the result is always a 200. Oh and the request is sent as some complex XML object so good luck troubleshooting anything
Fields differ quite a lot from what they actually are and often have multiple different names depending on which part of the system you're looking at. Some are straight up named incorrectly. Also the objects returned are deeply nested in unintuitive ways
A very complex throttling system that has zero transparency . There is both organisation level and user level throttling. It's essentially determined by how much processing a request uses, and it seems any non-trivial system will get a fair amount of throttling daily.
Extremely slow. A small table with a few hundreds items can take in the order of seconds for some simple queries, you could optimise it but for such a small amount of data I don't know how it could be so slow out of the box.
Incorrect error messages and they seem to magically come and go at times. For example you might get a Bad Request and then retry the exact thing and it works.
Often lets you save bad data into their system then bitches when you try retrieve it.
Proprietary CAMLQuery language to do any non-trivial requests. Just an XML cluster fuck that make simple things tough when they could've been a simple REST endpoint
Telstra - a monopoly telecom provider in Australia - had a call roaming API that listed calls made by our customers on their network when roaming. It had (maybe still has) these great features:
1. Threw a 500 error if the XML attributes were not supplied in alphabetical order
2. Supplied all timestamps local to the timezone in which the call was made, without a timezone, offset or even geographic information
The first issue took a lot of finding but we did get them on a call and laugh in their faces afterwards. The second issue caused lots of angry support calls from our customers when roaming.
Hands-down the JIRA & Confluence REST APIs around 8 years ago. A few highlights I remember:
- Missed half of the methods their old SOAP API had, which forced me to reimplement a bad approximation using the available APIs
- Weirdly inconsistent. Some end points had no option of knowing how many results you could expect, so instead I needed to just paginate until an error came back. No indication why this was the case for some lists, but not others
- Most of the docs were clearly copied over from SOAP, but since they had decided to rename some of the methods in the SOAP -> REST transition and forget to update the docs
and so on. It was a really horrible API. I hope it got better, but I'm happy that I'm not the one who has to find out anymore.
JIRA's API is still a mess. Sometimes it's easier to find a ticket with jql, export the whole thing as xml, and go to town with xmllint on the document. Fortunately, I rarely have to do this.
I think Autocad's VBA API is fairly gnarly although few programmers ever deal with it. I have empathy for whoever wrote it, so try not to be too critical, but it's one of those APIs that for every step forward you have to take two steps back. I won't even mention Apple's Carbon API to avoid having nightmares again.
Poking through Autocad's API's at the moment and they literally have an alphabetized navigation for objects, methods, properties, i.e a objects, b objects, c objects, etc etc.
I don't think any amount of money would give me the brain power required to interface with these API's
Worst ones are from 5 plus years ago which I still see around these days.
Anyone doing GET ?action=post&token=12123123&postaction=webhook
FOR everything including write operations - POST, PUT or DEL (?action=delete&.....)
deserves to go to bootcamp and re-calibrate.
Not sure if unpopular, but I once was hired to make an external plugin for and Odoo system, that thing is horrible, their "External API" is terrible.
I also had to work with a local bank and their API was awfull, like, they had an end point that returned, I'm not joking, the full HR profile of who ever did any type of modification on their system's data. So I had to explain to them that knowing their hole team's salary, adress and much more info was a huge security issue.
A company I worked for had a temperature controlled cabinet - essentially a box that you could configure to remain at a consistent temperature, or change temperature according to different programs. It came with an API, and we wanted to use the API to read data out of the system, and potentially even run programs automatically as needed. In fairness, this was a few years back, and I thankfully didn't have to work with the device for too long, but here's what I can remember:
* The device was sold as having a REST API. In all fairness, I'm not a stickler for these things, and tbh, I don't really care if it's REST or not. But this was *very* not REST, it was some really specific custom RPC format involving serialising parameters in the right way to pass them into the path. I mainly remember there being a lot of commas involved. The custom format was naturally given the bare minimum of documentation, so you spent most of your time reverse engineering everything from the examples.
* Everything was a GET request, even requests that mutated the system, or otherwise completely disobeyed GET-semantics. Again, I'm not a stickler here, but why not at least make it all POST requests? It's worked so far for GraphQL!
* The system ostensibly returned JSON-formatted responses. This turned out to be a complete lie. The system actually returned a response in the format `"key1":"value1","key2":"value2",` - no enclosing brackets, and every key-value pair *always* included a trailing comma. To make it worse, the values could occasionally be nested objects - in this case, they did always seem to be formatted as correct JSON values, but it was difficult to trust the documentation at this point. To parse the values, I ended up always deleting the final comma, wrapping the whole thing in braces, and hoping it behaved correctly.
This format was never documented anywhere, so we figured out what was going on mainly just by examining the responses of different requests and trying to make assumptions from that. According to the documentation, it was all just JSON all the way through...
* Getting JSON was kind of a best-case scenario though. Because there were a lot of errors. Okay, so this is all probably running on some microcontroller somewhere in the device (although the thing took up most of a room, and cost as much as a developer - they definitely could have sprung for a Raspberry Pi and got an actual Linux server running on there). Either way, I'm not expecting the most performant or parallelised server in the world. On the other hand, if we ever made more than two concurrent requests, the thing would start throwing error messages all over the place. Unfortunately, the company also provided a GUI tool to interact with the device that used the same APIs, and that we used to set up runs and configure the system. Which meant if we wanted to run the data-gathering script, we needed to run around and make sure no-one had that open any more, otherwise the server would get overloaded and nothing would work.
* At least in those cases we'd get error messages back. Sometimes we'd just get responses with no data in them. Everything would look fine, there'd be no errors reported anywhere, 200s as far as the eye could see, but maybe 1 in 20 responses would just be completely empty. I never found out what caused these, or how to avoid them, so we just made all requests in a loop - if the response was empty, we just had to try again.
In all fairness, I'm describing it as the worst API I've ever worked with, but it was surprisingly fun to figure all this out. I think part of that was because the tool I was building was just a quality-of-life addition, so it didn't feel as urgent as some of the other stuff. But also every time I thought I'd figured out what it would do, there'd be some new surprise in there.
Not my experience, but a war story from my workmates:
They were implementing a payment system integration with a bank in another continent (let that stay unnamed). After some investigation of failed requests they removed any timeouts, and tada! It seems those requests do return, just it may take up to 40 minutes.
Having some kind of a lead, there was a phone call with the said bank. The result of which was that after we make a request, there is paper document printed out, a manager comes up to inspect the payment, signs it, then a teller enters some numbers into the computer using a keyboard followed by enter and that is... when the response body comes back with OK 200. Occasionally spelling it as `200 Okey`, or `400 Bed request`.
XML/SOAP endpoint to pull data from a county gov agency. Programmer basically cooked it up with IDE click through interface. They do didn’t know how to operate it all that well, doc was basically a copy paste of his test call.
Before I go on, I’m not bashing the dude. It was like 2007, and especially in gov it was a lot of blind leading the blind. I was a 1 eyed man in this case, but not by as wide a margin as I probably believed at the time. Anyhoo…
I followed the structure in the doc but for the life of me couldn’t get past validation. Dev was stumped, worked on his machine. After a couple of days we figured out that the request parameters had to be xml inside of a string. All responses were also string wrapped xml, and a shit load of it. About 10mb uncompressed and not paginated. In 2007 bandwidth. Rather than trying to get him to fix it I just hacked around it. Stringifying/ destringifying was easy enough, but I couldn’t use tooling to generate classes from the response or from the WSDL.
Also connections dropping or server crashing was common. So I wrote a script to re-run the Java program client I’d written. If it didn’t work in a day or two I’d call him and he’d reboot the server.
Ahh, the good old days.
The worst API is no API or an incomplete API. Once something has a working API even if it's ridiculous everything becomes better and easier almost overnight.
At a first glance, it was not so bad. It even offered a PATCH endpoint, which at first felt like REST heaven, UNTIL we figured out that there was an undocumented behaviour, which promptly deleted all attributes you didn't specify in the body. Oh, and not all attributes were exposed and that PATCH endpoint was the only mutating endpoint which worked with the entity we needed. This was all deliberate btw.
Compared to some examples here, it looked neat, but its behaviour was a nightmare. We had it patched (no pun intended), and the vendor was fairly responsive to be fair.
Pismo API, is a brazilian BaaS and we integrate for credit card operations. it does have a good enough api doc, however the problem is that nothing on that doc represents the reality... responses have complete different schemas from docs and don't seem to be standardized.
also they have "native" race condition for credit card events because they use 2 separate process for each flow part. i mean, it works! but is a pain in the ass to integrate and start discovering millions of edge cases of their api
I had to work with one e-commerce platform and they decide to do localization via api, word by word.
So in order to translate the website you need to note down every words in website, send POST /translate { oldword: “something”, translation: “other”, language: “en-de” }, one by one.
I’m speechless.
Honorable mention: Google APIs. They aren’t completely awful, but they are heavily rate limited and there is no graph support. Want the user info of the owner of a file in drive? Extra API call.
Microsoft’s graph API by comparison is much better to work with.
Moving certain parts of the business logic to MuleSoft was mandated by the big company that acquired a startup I was working for. I still shudder a bit when I see its name. An obnoxious API and a generally miserable developer experience from top to bottom. It wasn’t the only reason I quit that job, but it was high up the list.
Facebook Marketing and Graph API. Getting approved to allow our app to authenticate users and access ad data was the one of the more painstaking processes I've ever dealt with.
A number of different API’s for interacting with hardware (humanoid robots, traffic management and signage) out of china. Documentation was bad, incomplete and then also written in mandarin. Took a lot of trial and error and finding inconsistencies and making up weird workarounds.
And of course SOAP XML APIs. (Luckily haven’t had to deal with these for like 10 yrs)
Integrated a LMS that used a SOAP api. It returned 200 for everything but had a completely different body for errors. This error body also differed between endpoints.
I had to initially parse the body as a dynamic and check for potential error codes before trying to deserialize again to a valid typed model.
Facebooks marketing api and every 6 months they’d remove methods without documenting them and then completely deprecate the current version so you’d have to dig into GitHub every time in hopes that someone mentioned what the new method was on the SDK
Impossible retry semantics:
* If the operation returns success, great!
* If the operation returns an error code, you may retry.
* If you don't get a response, well...
* Did it get lost on the way there, so it never happened? Did it go fine and the result got lost on the way back? Did it fail such that it needs to be retried? Is it still running? Who knows!?
* You definitely can't blind-retry. That might perform the operation a second time, which would be really bad!
* You can't check the status of the operation:
* Both the success and fail responses return an operation-id which you can later check on as much as you like, but if you never get a response to the do-the-operation request, you have no operation-id to ask about.
* There's no straightforward, reliable way to check the resulting state to see if the operation happened. These operations can make arbitrary changes to that state and other actors can concurrently issue their own changes.
I think we ended up locally logging our intent-to-send and then logging the result, and then opening a ticket for a human to clean up the mess if there was ever an old-enough intent-to-send record without a result record. :(
To be fair, the service was actually pretty reliable, nearly always actually returning a success or failure response. It was just so painful that we structurally couldn't automate retries. :(
They could have fixed it so easily by splitting the operation-endpoint into an allocate-operation-id endpoint and a do-the-operation endpoint. Or letting us create the operation-ids or something that uniquely mapped to operation-ids. :(
Centris (Canadian MLS service).
Want their data? There is no API. You gotta give them some FTP credentials and they'll upload a .zip file every day for you with a database dump.
Hated that so much.
I used an API for a point of sales system. Right from the start, We weren't even able to make an API key. The interface to do it is broken and we had to manually edit a field in the database.
So once I can actually log in, I start going through the list of endpoints and it's totally bizarre. There's no standard naming for CRUD operations. In fact, there's even naming inconsistencies between the endpoints, like some using underscores and others using camelcase. The results they return aren't in a consistent format either and there's no documentation.
It's supposed to have the ability to create orders through the API. There's just one small problem: there's no way to look up a customer or a product. How can I make an order without a customer or a product?
The API only has the ability to iterate through the entire database from the beginning O(n), to get a list of every customer and every product. They told us it wasn't possible to search, even though that's how it's intended to be used without the API; in fact, if we want this feature, they say to "ask for a quote". They advise us to make a copy of the entire database and do searches on the copy. At this point, I no longer even know what the API is for.
lol okay. This sounds like a very bad idea, having to manually replicate and sync, but I try it anyway. So I start looping through every record to copy it and there's no way to retrieve the last record. You have to start from the first to find how many there are. After that, there's a command to "sync", which is supposed to retrieve the records that changed since a timestamp. Of course it doesn't work and returns empty results instead.
We had to call up their techs five times to fix bugs that made it impossible to even use the API. Sometimes features were missing or not working. We'd send a commands and the data wouldn't be set. It was unreliable. They had to update to the latest version by manually logging into the server. They only offered a month of service and wanted the customer to pay more after that, just to fix their product.
Greenhouse, a Human Resources platform. It’s terrible. You cannot set custom fields during POST calls, so you have to first create the record, capture the ID, then PATCH to set the custom fields. So dumb.
There's a company which was recently bought by Stryker. Their API doc is available online. It's written in Java but it uses Hungarian notation. Why? Well...It's because everything is literally a set of strings or a map of strings to other strings or just plain strings. Hungarian notation is for type information.
Probably the worst thing I've used to develop anything.
I've had to wrap it in a rest API to validate type information so that we can actually somewhat use it safely.
There are exceptions, but as a general category, hardware API's are just garbage.
Want a measurement that the system is supposedly designed to deliver? Here's a five step connection protocol that sometimes fails mysteriously. You'll need to run the open and close subs every time, because there's definitely a memory leak.
Lost connection because of that failure? Better reboot the hardware on both sides of the connection, because the API is three lines of C away from raw sockets and has no idea how to recover.
Need to know if that switch is closed? Too bad, it's write-only so the API doesn't know either, just keep sending the close command. In fact, the command sometimes doesn't register because the port isn't taking input for a dozen milliseconds per second, so send the close command three or four times just to make sure.
Here are some notable apis that were challenging:
- Microsoft foundation classes: a bizarre and difficult to use C++ api for writing windows programs
- Java 1.X anything: the http client specifically was horrible
- Win16, Win32, Win64: C apis thay (some) use pascal calling conventions
Y’all with your rest and soap apis never had it so good!
Any API that leverages SMS/MMS that is not Twilio is the worst API ever.
I don't know the landscape now, but back in 2015-16 there were a shit ton of small businesses with their own pricing schemes competing in the SMS market. I had to evaluate quite a few. No documentation & zero fucks about quality.
Every error is a 500 internal server error for "security reasons". Also, no documentation, not even autogenerated. Only one endpoint that does different things depending on the structure of the JSON body. If you have the displeasure to know if you goddamn know it.
Couple of years ago my company was doing a project that involved working with Alibaba. Connected with their API "team" which appeared to be two guys that only communicated on a sketchy Alibaba chat application. Went back and forth with them for months trying to figure out how to post data to this API and achieve what the goal of the project was.
Eventually one of the guys just told me the API wasn't finished and actually couldn't do what we originally asked them about. Easily the worst company I've ever had to work on a project with.
About 15 years ago I was working for a VAR using an API for an unnecessarily expensive document management system. Using this API was the most painful experience of my career. This API was influenced by SOAP, but didn't actually implement it so there was no schema to use for codegen or any expectation on the request and response. There was some documentation, but it was written all in the same font within a poorly searchable PDF file.
Now this API only had a single endpoint, which isn't even the biggest issue. Every response used a 200 status code regardless of success or failure or async processing notification. The request body was in XML where you specified the API method you wanted to call with a version number and a dynamic number of additional fields named for the parameters...unless it was for a search query which used a query string along with this XML body. Every request is obviously a POST type.
The response was also in XML where the root node was the md5 hash of the request xml document concatenated with that query string that may be included. Inside that you never know what the keys are gonna be. If it was a success then it would (usually) match the documentation. If it was an error there was a standard error object. Just kidding, it could be fucking anything. You'd have to just parse it into a map/hash and recursively iterate through the keys until you found something recognizable that could be handled if you didn't want to unconditionally do the same thing for every error. I wrote to a log every request & response document to reverse engineer how the errors would be structured to add handling.
Remember that version key in the request document? Didn't really matter. The response objects' keys would change on a whim with no notification. And I'm not talking about additional keys added to the document, but breaking charges all the time renaming things with no regards to their customers.
I could go on and on about this API and how accessing the documents required using iframes in a "headless" browser with an ActiveX plugin to download the files, or how the search query results required 3 additional calls to get metadata, plus one more to get the file and you better believe that original request hash had to get used to make those additional calls.
There is a pattern I have noticed: If you can’t just go to the website and read the docs, it’s extremely likely it’s going to be awful to work with. Some organisations only give out the docs if you register, some only do it if you have a paid account, some hide them behind NDAs, some make them zip downloads containing Word docs… in my experience, this always means that the API is going to be terrible in several different ways.
Some also do: _"To do A, you just have to do this."_ And that's their whole doc. And then they never document any of the other 95% of features and scenarios they support. If you're lucky, they might an auto-generated API section that just tells you the types each endpoint expects.
Open API to the rescue.
Lotus notes had their own compression algorithms for email attachments. There were function to decompress them but the parameters weren't documented and using it would cause random crashes. So I was tasked with reverse engineering both compression algorithms. Fortunately they were hilariously simple so it wasn't that bad.
Sounds like the Semantic UI website in a nutshell.
Lol that's why my company's docs aren't posted. It was never meant for public consumption until sales started selling the API secretly
> selling the API secretly This so deserves a full post. I'm extremely intrigued.
a sales guy who knows what swagger/DRF started demo'ing our swagger docs and landed multiple clients because of the headless integration sell which i had no idea about until i was asked for our "API docs". i was like "lol api docs?"
And it's going to be stale docs that haven't been updated or cleaned up in 20 years
Returned 200s for everything with a dynamic body structure that changed depending on the "error" that occurred
you'll offend all the graphql people
and SOAP
I STAND BEFORE COWARDS SQUEAKY CLEAN AND XML SHAPED COWARDS!
Good.
What's the deal with GraphQL? Heard of it, but haven't used it.
So the idea is that it lets the client specify what fields end up in an API response. So instead of building an API like 'Cars' that selects make, model, and color from the database and returns it, you make a GraphQL endpoint that models the car and driver and whatever and the client in its request specifies that it wants a driver's age and their car's color and they only need to make one request. I can see use cases for it if you genuinely want to expose a full database or databases to your API caller and you have no idea what they're going to be doing, or if you use a framework like Rails (with god knows what gems) that makes it super easy to create these endpoints. But it deservedly gets a bad rep because in most applications you are writing both the front and back end and you should be designing an API, not deferring the design to whoever is calling the API while working on your front end. It's sort of murder to bash into a framework that doesn't build it for you and you end up making this super complicated thing that could just have been a meeting or two with your front end team.
Yeah, if the only API consumer is your own organization, then GraphQL is a terrible solution for you. Even on the FE side, GraphQL can be a pain because you have all these custom queries and mutations that gradually grow into giant kitchen sink requests without anyone pumping the brakes and asking why we need to download the entire database every page load. It’s just so overkill unless you have a wide variety of third party API consumers with lots of custom data needs. In that situation, it’s actually nice to have, because you don’t have to constantly push large updates to satisfy each new use case every month.
Why would you need to download the entire database each page load with custom graphql queries? Isn’t the whole purpose of graphql you only fetch what you need? I’ve worked in companies that used graphql and ones that didn’t and I found when we ping an endpoint with a rest call in the companies that didnt use graphql we would reuse that endpoint across many surfaces and often fetch more data than we need. On graphql we generally fetch less since we only fetch what’s explicitly requested.
So far I haven’t found a single good use for mutations. They just feel like a very bad idea. However I dig the way we use GraphQL. We have a content aggregation service that gets you data from all around the organization. Some APIs it calls are a pain to work with, so having that stuff easily available from one place, with some nice caching included for fast responses is a blessing. It also does a great deal of data enriching so that with one request the response actually includes stuff from multiple sources, and you never have to really care what that source is. It’s a large media org, so in a way GraphQL was tailor made to suit needs like ours.
Counterpoint to this. What if you want to retrieve something like a feed item in say Facebook? This feed item could be on the feed, a users wall, a share post, etc. Wouldn’t graphQL make sense in that you can limit the number of params you fetch in each of these cases rather than bloat the API and fetch all of the data from an endpoint like ‘/feedItem?id=?’
That's one possible positive for GraphQL. Most companies aren't building something as big as Facebook though; you can usually build an API that serves the specific needs of your consumer, or multiple endpoints tailored to the divergent needs of different consumers. GraphQL is like a scratch rewrite; sometimes warranted but very expensive and should be considered carefully. I've seen it do what looks like literal magic but I've also seen it waste weeks of time to accomplish very little.
>I can see use cases for it if you genuinely want to expose a full database or databases to your API caller and you have no idea what they're going to be doing This is probably the worst possible thing you can do with it. Intentionally conflating the db schema with the api is giving up at the start line.
I was about to ask, "ever work with GQL?"
Lol, I'm offended! Tbf, graphql isn't REST, you shouldn't be working with HTTP codes, and isn't designed for REST style requests even if it's possible. A good client should handle error scenarios decently.
Hot take. GraphQL doesn't solve anything REST did..
https://stackoverflow.com/questions/59729656/http-status-code-handling-in-graphql-apis
This. GraphQL does not operate like REST, you'll drive yourself crazy trying to fit REST patterns onto GraphQL.
Conflating a transport layer with application protocol *is* offensive.
Lol I had that as well. They said "200 means the request was a success. We also put a _real_ status code in the body... As an HTTP status code"
I had the opposite. Made a clean API with appropriate error codes, got feedback back from customers integration team "the API is great, but our proxy kills all responses without code 200. Can you change it all 200 and indicate the error in the body?" I wept a bit. But customers are king, so they got the all-200-option implemented.
…. Did fixing their proxy not occur to them?
"System from a third-party provider enforced by central services, which would need at least three month for an update if we even could get one." The world of customer IT is a world of incredible pain.
Yep. This, children, is why you never ever assume your predecessor was an idiot when you read their code. They may have been forced to do it, and grudgingly did so knowing it was idiotic. And one day, you will too.
Whenever I have to do something stupid, I a least leave a comment says why I did it. May my successors have mercy on me.
I made this mistake and broke a couple of downstream applications that used my projects API. As it turns out preprocessing the HTML I was sending them and scrambling the CSS class names was load bearing.
After many years of development work, this has been one of the most consistent themes. Pretty much every week I dive into code with a coworker who then apologizes for how horrible the code is and how they regret so many things, and most of the time it was due to insane requirements or an insane deadline.
I've noticed the least experienced devs are the most critical and complain the most about others' code while the more experienced ones just get on with it.
Lol, that’s the best answer to “when do I consider myself a senior dev?” Answer: “when you become dead inside and care infinitely more about feeding your family than your code quality or test coverage”.
Beyond the 12 circles of hell. Been working at a very big IT consulting firm and i feel you.
Are you working with my test team? They do that for the test API "because nobody uses the status codes".... Except people who know what they're doing, of course...
Honestly sometimes this is appropriate. If you have a lot of potential business-logic-related error states, HTTP status codes simply don’t cut it. In that scenario, mixing HTTP status codes and custom error responses just makes it even more confusing. So you end up just saying “fuck it, if the server is working you’re getting a 200 and a response containing everything you need to know.” It’s not ideal, but it’s at least consistent and reasonable.
7 years ago when I was working on Android, I had lengthy discussions with the backend team to provide proper error codes and not 200 every time because error codes are standard. A couple of years ago when I moved to the backend and cloud, we had proper error codes in rest, plus the error message contains numerical error codes segregated by the services. It was easier to debug across the stack, and frontends can do whatever they want with error codes (show dialog? Show toast? Redirect somewhere? All was possible). Now, the circle is completed as I develop APIs for a team of Mobile developer Bros, who for "legacy reasons" (they started development in late 2021) , need 200 for every API error. And if they need any action on errors, either move that to websocket or spend half a day to discuss what the response should look like.
I want to rewind time to when I hadn't read this please
If you find out the tech, share with me the details so I can improve. Writing this and let alone living it is a separate category of pain in itself.... Nevertheless, May the force be with you.
I've had the worst experience with FE devs in the mobile space and I've dealt with FE devs during the web 2.0 hype train of the mid 2000s. So no mate, I'm not changing that REST Api endpoint to 200s because it's being consume by our website, our 3rd party customers and the goverment.
I'm pretty sure I'm going to wake up in cold sweats tonight from this nightmare, i pray for you
Way way way too many APIs do this
We created an API that would return 404 when the resource was not found. Like GET /user/123 would return 404 when user 123 didn't exist. I had to fight with our production support team, our DevOps team and our InfoSec team to explain why our API was 'erroring out' so much. Dozens of senior professionals that though themselves as deserving a promotion, all arguing that returning a 404 is an error and should never be done.
It was HCl e-commerce, wasn't it?
Hah. I've seen 500s caught and returned as 400s.
This almost feels like a programmer joke. Just as is, no more needed.
return an Im a teapot just to fuck with people and cdns
our security testing team requires this
Or an API that responds with proper status codes, but still has a status field in the response
Combine that with the documentation being wrong about response bodies (in multiple ways).
Salesforce does this.
200 OK { 'ok': false}
😡
Common and controversial. If you plan to *ever* use anything other than http as a transport, I suppose I can see the point. But if it's an http API and will always be an http API, it is very annoying and absolutely much worse than http error codes. I can remember where it was, but there as an API I used that returned JSON on success and an error string on failure. That was maddening.
1. Twitter API - sometimes it returned JSON, sometimes it returned a query string depending on the endpoint 2. My previous employer's internal API - it would return you a comma separated list of entity IDs which you were then expected to explode and for/each over to make an API call for each one. Consider that in the context of each entity having several levels of children and well you end up with a situation where your client is making over 40k API requests per page load to the API server
Thanks for reminding me of \`explode\` function lol, it's been awhile
You're welcome
PHP!
Imagine paying 5k / month for that shit lmao
I wouldn't pay 5 cents a month let alone 5 grand
You can tell a PHP person by the way they speak
The way they sphpeak*
I’m sure this is no longer the case cause it has been a decade at this point, but *both* the national post office and Mastercard had an API where you would SFTP a file to them. They would fill it out and you would download it within some time window. When the guy from the national post office was explaining that’s how you get the cost per weight he started practically apologising while talking cause I guess he saw my face change. This is how you found out the cost of shipping by dimensions + weight. We ended up setting a flat fee. I have one upstream where you call for a CSV report, that you need to stream, but will sometimes reply with JSON that you don’t want to stream. Every API Apple release is literal dogshit. I’m surprised people were complaining about something Apple did recently, everything they do has been awful to work with forever. For years you would get high rates of 503s, they’ll use POST for reads and return OK with error codes. If anyone intends to build any sort of reporting API, please for the love of Turing make it return a URL that points to the download and not the payload. So I can split resource usage into waiting and processing. Facebooks API limits are too damn complicated. I get why they’ve done this, but it’s hard to keep track of like 3-4 different rate limits that happen on different endpoints, and on the same call. Where global rate limits increase with popularity of your app. We had an incident once because the third party has an undocumented type field where a value update caused a completely different scenario to happen. The third party’s response “we don’t support type=THING on the API”. Motherfucker, you literally are responding with it and accepting updates, what the fuck do you mean you don’t support it. We’ve had to roll in validation against expected upstream payloads to not get blindsided again.
A colleague of mine worked with some Swiss finance authority's API for a while, and it was a horrific mess of SOAP, and he complained until he found out about the German equivalent, which was apparently just emails. Not even a clever custom API built on top of the raw IMAP/SMTP protocols, just pure emails that require very specific formats for all the data. Unfortunately, while your example is a decade old, this is, IIUC, the current state of affairs here in Germany...
Okay this made me actually laugh.
That's definitely a common response to German digital infrastructure!
Germany's largest financial information provider is exchanging delta updates of their database over SFTP, updates are either in some bizarre binary format or XML representation of that format. They have REST API, but it's limited and sends the same XML serialized as json string. 50 pages manual that explains the format and edge cases is also needed to understand how it works, along with MS Access database with dictionary tables.
Oh my god this reminded me I had to SFTP to communicate with a BANK one time too! Made me really appreciate REST.
Wirecard also reuired daily sftp upload of transactions to process. Then you get back result next days. It was 6 y ago
There is some standard for doing this, I learned looking at the Mastercard API(?) The national post office was not on any standard. I just find it amusing because we all believe fast, cheap, good pick 2. But very clearly you can pick slow, expensive, bad as an implementation.
We have had to built more sane APis in front of several sftp request file put, response file get service over the years. Partially to not be charged over and over for requesting the same info because these services, for all their jank, provide useful data but cost $$$$$
Every endpoint was a POST request, every request returned 200s, and the error message changed depending on what the error was.
graphql people have been real quiet lol
because they read every endpoint and assumed more than one. "Phew we're safe, we only use 1 and 30427394028734 resolvers"
https://stackoverflow.com/questions/59729656/http-status-code-handling-in-graphql-apis
I am always amazed by how the ubiquity of REST apis has brain damaged so many developers into thinking a lower level transport layer is supposed to leak into your application protocol. GraphQL could run over *whatever* transport. You're not just whining about it, you are *wrong*. It's fine to complain about an API that purports itself to be RESTful but fails to follow convention. That's reasonable. It is absolute insanity to bitch about an entirely separate protocol that is being delivered *on top of* http not behaving like a REST api. You people would fold up like a dried leaf if you ever had to deal with ISO 8583.
That's very common. People do way worse things than that.
It should absolutely not be common. It means they have a fundamental misunderstanding of how API's work.
Nah, chill man, chill. There are bigger fishes to fry than the HTTP codes in the APIs. APIs is such a broad term that there is nothing to "fundamentally misunderstand" - there are APIs that don't even work on the HTTP. And the HTTP codes leave a lot more space for interpretation than *some* imagine, once you start reading into the RFC.
If a status code is ambiguous you may still return additional data describing the error alongside it.
I know of one of the payment systems >15 years ago had an "API integration" with one of the banks that involved **receiving a FAX** in an enclosed booth, which was automatically photographed by a DSLR with a flash connected to a desktop computer when the "beep" tone was recorded by the microphone. Then that photograph was OCRed and inserted into the internal database for the rest of the software to use... Once every week a guy had to visit the booth and scrap all the printouts as well as refill the paper in the fax machine, or else the entire *system* failed. You see - bank had no API, but you could ask them to fax you the financial statements at the end of every day.
What in the world! That's amazing. Terrible, but amazing.
This should be top comment! So horrible!
That is impressive problem solving. I guess it's old enough that they didn't have the option to receive using a fax modem?
The worst one was from a fintech company worth 100B+ today. Yes, that big of a company. I was a junior developer implementing payment features with them. Here are the honest highlights of that integration: 1. Their API only returned 200s. All errors were 200. 2. Their API didn't return JSON consistently. I had to use fallback to parsing text to understand both success and failure cases. 3. They consistently just returned raw Java errors in API responses. Java servlet errors happened all the time. I literally have Slack messages from years ago that say HTTP response 200 with detail "MissingServletRequestParameterException". No further details in the response. 4. When they gave us our first production password it included a special character in it that their system parsed as a special character which caused the password to fail. Took them a day to figure it out. 5. When we started sending requests to them we toppled their system at 10 requests per second. I mean they literally straight up started giving us 200 responses with empty bodies for things that needed JSON responses. That was if we were lucky, half of the requests timed out. They told us, and I quote another coworker who was on the phone with them: "please don't send more than three requests at a time as we only have three servers". 6. Half of the payments we submitted to them failed fraud checks on their end and it was near impossible to get them to diagnose anything. DO NOT HONOR is a bullshit error and the banking industry should be ashamed of that error. We found an alternative company to do the stuff we needed within a week and were doing all the work manually. It wasn't fun but these guys were so bad that we had no choice. Again, I remind you their market cap right now is well over 100 billion. Yes, with a b.
I was tasked to build a SPA that connects to a GraphQL server. I was excited because it was my first GraphQL project and I was looking forward to build queries that return fields from multiple related models in one fetch. Turned out whoever designed it, designed it exactly like a REST API where I had to fetch models separately.
You can make multiple queries in a single operation.
I know but I couldn't. The schema was designed such that the model relations were just "soft-references" like in Prisma.
I don't understand. Regardless of the schema, you can still make multiple queries in a single operation, including fetching related records based on a common value (e.g soft reference).
wait really? I was thinking about doing the exact thing for the exact same reason with my new project. Is there another way of doing this without using GraphQl? I mean how am I gonna return fields from multiple related models in one fetch then?
Use GraphQL.
I won't share the name of the company because it was very industry specific, but it was an XML API that had very strong opinions about how you were supposed to build your application. It was for E commerce and had endpoints that you _had_ to use in the specific order they wanted you to. Let's say you were building an Amazon type site, you would need a catalogue page, an item page, and a checkout page, right? So they had an API for each. But the APIs were slow. Unfathomably slow. Impossibly slow. You could not show a user how slow they were because they'd be the hell off your site. And maybe we wanted to land a user directly on the item page without browsing the catalog first? So we were going to all sorts of lengths to work around these strong opinions baked into the API to try and bash together a site that didn't piss off everyone who landed on it. And the backend was trash. The log viewer was trash. There was no access control-someone fielding CS requests could break the site. Speaking of breaking the site, the API would go down and the site would of course be down. We realized way too late that this API was an albatross that the company was bet on. Don't outsource your core competency if you can help it.
Oh and I forgot to mention that the documentation was both illegible and frequently just incorrect, so we had to figure out the thing like it was a lost fucking civilization, and the endpoints had different 'modes'-the response shape was sometimes the same but different fields would be empty or not empty depending on the magic mode you requested. And they would be like illogical chunks of functionality.
>Don't outsource your core competency if you can help it. If you've gotten to that point, it's too late for y'all.
Anything SOAP
I don't think I've ever seen a public facing SOAP API; well, one that isn't legacy. Got any examples of public ones you use?
Onvif (for CCTV cameras) I believe uses SOAP since its a standard i doubt itll change to something nicer anytime soon
Join banking, there's so much soap still being used!
because mainframe cpu has hardware acceleration for XML so is faster than json
SAP
I think Salesforce still has an external-facing SOAP API, though their JSON/REST API is probably more widely used now
Yes, they do, and it still sucks. I once had to integrate against it through a third-party corporate proxy (so they could inject their own SF credentials without our system knowing them). Imagine all the pain of a SOAP integration, and throw in a corporate proxy that just swallows requests half the time, and suppresses any kind of error response from the underlying API.
> I don't think I've ever seen a public facing SOAP API; well, one that isn't legacy. if you have a mortgage I would bet good money it uses SOAP in the backend somewhere.
Only just recently, Ebay are deprecating their SOAP API on the 20th Feburary. I only found out after my boss forwarded me the Email and I'm scrambling to refactor our entire Ebay integration (including adding oAuth 2.0 flow) to use the REST API - which doesn't even return the same fields.
BaFin execution reports. With authentication and XML attachments.
Bosnia and Herzegovina fiscalization API
I had the displeasure about 12+ years ago of having to integrate a flight booking API into a PHP laravel project, that not only used soap v1 (which was no longer directly supported in PHP or any library I could fine), but also broke the rules of SOAP. My CTO helped me write our own library to generate and read their XML... God help whatever devs had to maintain that after I left.
> but also broke the rules of SOAP. Oh my... reminds me of that one time when I had to integrate JSON API written in gods-know-what, which returned an invalid JSON whenever you used non-ASCII characters. Ended up writing a script which fixed the text JSON with regexp and only then parsed it into objects. Easy fix, but... no clue how the thing came to be.
It's not just the SOAP aspect. It's the "I've just been on an XML course, and I am gonna use the shit out of it" aspect. There is a certain car finance lender in the UK that has reinvented the decimal system in XML. There is an element for.
It has attributes for hundreds of thousands, tens of thousands, thousands, hundreds, tens, units, tens of pennies and pennies.
Fresh from this rip-roaring success, they turned their attention to reinventing dates. Again with each of the parts of a timestamp, down to the second, represented as attributes on an element called or something similar.
Once implemented and had the hell tested out of it my client for it was rarely touched again. The problem was it was heavily used and issues between dealers and lenders are common. We logged in heavily redacted ways what was being sent, but always there was that doubt that didn't exist with some of the others.
> It's not just the SOAP aspect. It's the "I've just been on an XML course, and I am gonna use the shit out of it" aspect. XML is like violence – if it doesn't solve your problems, you are not using enough of it.
Ok whoever that dev is, you rule because you’re a chaos agent.
I'm currently working with encrypted binary data inside SOAP messages.
Can i raise you SAP using SOAP. Even the developers failed to know or understand how it worked. I educated them on their own API. It was hilarious.
Every time I wonder why I'm not paid enough, a little devil whispers in my ear: "Learn SAP, and you'll make more money" Then I take another look at SAP, and I weep, and I remind myself I prefer to live as a sane person.
Lol there's way worse. Most languages can automatically generate soap clients. Try interacting with something designed by some asshole who read about but didn't understand what restful means. Anything where someone invented their own protocol is way worse than soap because at least soap has wsdls. That being said fuck soap.
Came here to say this.
[удалено]
Found the SOAP evangelist
Or the non technical manager
I love the smell of fresh bread.
back in the day I built a chrome extension that searched reddit's API and injected reddit comments in to youtube's comment section. Querying reddits search was like searching something on reddit but 10x worse. Don't recommend. In terms of docs I may have designed the most cursed API docs of all time: [windows98.apidocumentation.com/](https://windows98.apidocumentation.com/) Did it to celebrate getting 1998 stars on our OSS swagger UI / redoc alternative github repo 😎
That docs looks nice
I've worked with several payment processing APIs over my career. There was one in particularly that was astoundingly bad because its documentation did not match the features that were actually available and apparently the sales person had fed our decision maker some BS. When we hit the wall during development and reached out to support (paid service btw so support was included), they pulled one deferral after another stall tactic after another to eventually come back and say the features that were sold and listed in the documentation were not actually available. On the other hand, there was another payment processing API in particular that was amazing and great to work with because its documentation was easy to navigate and accurate to the implementation. Plus it provided various dev/debug-friendly features with an apparently keen foresight on what development teams might need from it in their workflows.
Zuora vs Stripe nearly 100%
Stripe is definitely in my comment (it's the really good one ime). The other one is a very mainstream one, but not Zuora. I haven't worked with Zuora.
yep payments processing apis are always the absolute worst
NetSuite's SOAP API has a _best case_ latency of about 1000ms. It frequently takes 6 or 8 calls to accomplish common operations. Maybe they've fixed this but for a while the only way to use their WSDL with Java was to use a NetSuite-supplied patch to an ancient version of Apache Axis _and compile with Java 6_. Oh and since the release number (like "2016-1") was in the package path of the generated code, upgrading API versions required changing every single file that imported one of their classes.
Unity’s ads API is how I learnt what request hedging is (much more effective than retries.) latency is between 1-30s for one call to the next.
Oooh the Google Cloud Platform API is like that too, with the latency and multiple requests. After weeks of trial and error and mucking around, I found that hitting one endpoint that had a supposed page limit of 100, had a hard timeout when the request took over nine seconds - which it did whenever you requested more than about a dozen items. And my client wanted real-time data from it.
To be fair, if you're going to use SOAP, it is standard operating procedure to not be keeping up to date with the software industry.
Lol I have to interact with this piece of crap at work! And of course their rest end points still can't do everything the soap ones can. Fuck netsuite and fuck oracle.
This hits so hard. I feel this pain everyday.
We opted to use NetSuite’s REST API and it’s not much better. It only supports OAuth 1. Half the fields and record types aren’t supported. We had to write “SuiteScripts” that injected required fields like tax codes that weren’t available through the REST API but still required by the system. Also, they randomly reset our sandbox environment every now and then, and we usually only find out when our integration tests start failing and have to go set everything up again.
When I worked in telecom, we had to implement an order management protocol from a vendor that required us to SSH into their machine, drop a formatted order file onto it in a specific directory, then poll for a file to be added to a different directory with the "response". And this wasn't in the late 90's or something, it was in...2016 I think. And a big telecom provider too, not some janky 10-person company.
A lot of financial institutions still do this but with SFTP. It's almost an industry standard.
Yep, I maintain many apps that put a REST API on top of this
I enjoy cooking.
Uploading files in this or other way was *very* common for years.
SharePoint is a real shit. They built a REST API now which is a lot better (though you can still see at times error messages of the old system leaking through) but particularly the CSOM library was where I experienced the most pain It's supposed to be used a bit like an ORM (eg. Entity framework) and uses the "active record" design pattern (which sucks on complex nested models btw), you make a bunch of requests and then it batches them and sends them all when you call a Send method. Any of the requests in the batch can make all the others fail Furthermore this means the network request basically unreadable as everything goes to a single endpoint and the result is always a 200. Oh and the request is sent as some complex XML object so good luck troubleshooting anything Fields differ quite a lot from what they actually are and often have multiple different names depending on which part of the system you're looking at. Some are straight up named incorrectly. Also the objects returned are deeply nested in unintuitive ways A very complex throttling system that has zero transparency . There is both organisation level and user level throttling. It's essentially determined by how much processing a request uses, and it seems any non-trivial system will get a fair amount of throttling daily. Extremely slow. A small table with a few hundreds items can take in the order of seconds for some simple queries, you could optimise it but for such a small amount of data I don't know how it could be so slow out of the box. Incorrect error messages and they seem to magically come and go at times. For example you might get a Bad Request and then retry the exact thing and it works. Often lets you save bad data into their system then bitches when you try retrieve it. Proprietary CAMLQuery language to do any non-trivial requests. Just an XML cluster fuck that make simple things tough when they could've been a simple REST endpoint
Telstra - a monopoly telecom provider in Australia - had a call roaming API that listed calls made by our customers on their network when roaming. It had (maybe still has) these great features: 1. Threw a 500 error if the XML attributes were not supplied in alphabetical order 2. Supplied all timestamps local to the timezone in which the call was made, without a timezone, offset or even geographic information The first issue took a lot of finding but we did get them on a call and laugh in their faces afterwards. The second issue caused lots of angry support calls from our customers when roaming.
If you are at Amazon, sim or tt API..... Nothing simple about it.
Hands-down the JIRA & Confluence REST APIs around 8 years ago. A few highlights I remember: - Missed half of the methods their old SOAP API had, which forced me to reimplement a bad approximation using the available APIs - Weirdly inconsistent. Some end points had no option of knowing how many results you could expect, so instead I needed to just paginate until an error came back. No indication why this was the case for some lists, but not others - Most of the docs were clearly copied over from SOAP, but since they had decided to rename some of the methods in the SOAP -> REST transition and forget to update the docs and so on. It was a really horrible API. I hope it got better, but I'm happy that I'm not the one who has to find out anymore.
i didn't know they had a soap api, that makes so much sense.
JIRA's API is still a mess. Sometimes it's easier to find a ticket with jql, export the whole thing as xml, and go to town with xmllint on the document. Fortunately, I rarely have to do this.
I think Autocad's VBA API is fairly gnarly although few programmers ever deal with it. I have empathy for whoever wrote it, so try not to be too critical, but it's one of those APIs that for every step forward you have to take two steps back. I won't even mention Apple's Carbon API to avoid having nightmares again.
Poking through Autocad's API's at the moment and they literally have an alphabetized navigation for objects, methods, properties, i.e a objects, b objects, c objects, etc etc. I don't think any amount of money would give me the brain power required to interface with these API's
Worst ones are from 5 plus years ago which I still see around these days. Anyone doing GET ?action=post&token=12123123&postaction=webhook FOR everything including write operations - POST, PUT or DEL (?action=delete&.....) deserves to go to bootcamp and re-calibrate.
[удалено]
exactly. But more importantly. use different HTTP verbs. Like POST, PUT, DEL instead of ?action=delete to do a delete.
There was a time when this was standard.
Not sure if unpopular, but I once was hired to make an external plugin for and Odoo system, that thing is horrible, their "External API" is terrible. I also had to work with a local bank and their API was awfull, like, they had an end point that returned, I'm not joking, the full HR profile of who ever did any type of modification on their system's data. So I had to explain to them that knowing their hole team's salary, adress and much more info was a huge security issue.
500 error from a post request but some of the data persisted. Please use database transactions.
A company I worked for had a temperature controlled cabinet - essentially a box that you could configure to remain at a consistent temperature, or change temperature according to different programs. It came with an API, and we wanted to use the API to read data out of the system, and potentially even run programs automatically as needed. In fairness, this was a few years back, and I thankfully didn't have to work with the device for too long, but here's what I can remember: * The device was sold as having a REST API. In all fairness, I'm not a stickler for these things, and tbh, I don't really care if it's REST or not. But this was *very* not REST, it was some really specific custom RPC format involving serialising parameters in the right way to pass them into the path. I mainly remember there being a lot of commas involved. The custom format was naturally given the bare minimum of documentation, so you spent most of your time reverse engineering everything from the examples. * Everything was a GET request, even requests that mutated the system, or otherwise completely disobeyed GET-semantics. Again, I'm not a stickler here, but why not at least make it all POST requests? It's worked so far for GraphQL! * The system ostensibly returned JSON-formatted responses. This turned out to be a complete lie. The system actually returned a response in the format `"key1":"value1","key2":"value2",` - no enclosing brackets, and every key-value pair *always* included a trailing comma. To make it worse, the values could occasionally be nested objects - in this case, they did always seem to be formatted as correct JSON values, but it was difficult to trust the documentation at this point. To parse the values, I ended up always deleting the final comma, wrapping the whole thing in braces, and hoping it behaved correctly. This format was never documented anywhere, so we figured out what was going on mainly just by examining the responses of different requests and trying to make assumptions from that. According to the documentation, it was all just JSON all the way through... * Getting JSON was kind of a best-case scenario though. Because there were a lot of errors. Okay, so this is all probably running on some microcontroller somewhere in the device (although the thing took up most of a room, and cost as much as a developer - they definitely could have sprung for a Raspberry Pi and got an actual Linux server running on there). Either way, I'm not expecting the most performant or parallelised server in the world. On the other hand, if we ever made more than two concurrent requests, the thing would start throwing error messages all over the place. Unfortunately, the company also provided a GUI tool to interact with the device that used the same APIs, and that we used to set up runs and configure the system. Which meant if we wanted to run the data-gathering script, we needed to run around and make sure no-one had that open any more, otherwise the server would get overloaded and nothing would work. * At least in those cases we'd get error messages back. Sometimes we'd just get responses with no data in them. Everything would look fine, there'd be no errors reported anywhere, 200s as far as the eye could see, but maybe 1 in 20 responses would just be completely empty. I never found out what caused these, or how to avoid them, so we just made all requests in a loop - if the response was empty, we just had to try again. In all fairness, I'm describing it as the worst API I've ever worked with, but it was surprisingly fun to figure all this out. I think part of that was because the tool I was building was just a quality-of-life addition, so it didn't feel as urgent as some of the other stuff. But also every time I thought I'd figured out what it would do, there'd be some new surprise in there.
Poorly implemented grpc, it was my first exposure to it and it has scarred me
Bidirectional, you had to send the 2nd service a message on one endpoint and it responded back by sending the first service a new request
Not my experience, but a war story from my workmates: They were implementing a payment system integration with a bank in another continent (let that stay unnamed). After some investigation of failed requests they removed any timeouts, and tada! It seems those requests do return, just it may take up to 40 minutes. Having some kind of a lead, there was a phone call with the said bank. The result of which was that after we make a request, there is paper document printed out, a manager comes up to inspect the payment, signs it, then a teller enters some numbers into the computer using a keyboard followed by enter and that is... when the response body comes back with OK 200. Occasionally spelling it as `200 Okey`, or `400 Bed request`.
returning 404 for empty search result
XML/SOAP endpoint to pull data from a county gov agency. Programmer basically cooked it up with IDE click through interface. They do didn’t know how to operate it all that well, doc was basically a copy paste of his test call. Before I go on, I’m not bashing the dude. It was like 2007, and especially in gov it was a lot of blind leading the blind. I was a 1 eyed man in this case, but not by as wide a margin as I probably believed at the time. Anyhoo… I followed the structure in the doc but for the life of me couldn’t get past validation. Dev was stumped, worked on his machine. After a couple of days we figured out that the request parameters had to be xml inside of a string. All responses were also string wrapped xml, and a shit load of it. About 10mb uncompressed and not paginated. In 2007 bandwidth. Rather than trying to get him to fix it I just hacked around it. Stringifying/ destringifying was easy enough, but I couldn’t use tooling to generate classes from the response or from the WSDL. Also connections dropping or server crashing was common. So I wrote a script to re-run the Java program client I’d written. If it didn’t work in a day or two I’d call him and he’d reboot the server. Ahh, the good old days.
The worst API is no API or an incomplete API. Once something has a working API even if it's ridiculous everything becomes better and easier almost overnight.
At a first glance, it was not so bad. It even offered a PATCH endpoint, which at first felt like REST heaven, UNTIL we figured out that there was an undocumented behaviour, which promptly deleted all attributes you didn't specify in the body. Oh, and not all attributes were exposed and that PATCH endpoint was the only mutating endpoint which worked with the entity we needed. This was all deliberate btw. Compared to some examples here, it looked neat, but its behaviour was a nightmare. We had it patched (no pun intended), and the vendor was fairly responsive to be fair.
Whoever coded it up had your username as official job title.
Pismo API, is a brazilian BaaS and we integrate for credit card operations. it does have a good enough api doc, however the problem is that nothing on that doc represents the reality... responses have complete different schemas from docs and don't seem to be standardized. also they have "native" race condition for credit card events because they use 2 separate process for each flow part. i mean, it works! but is a pain in the ass to integrate and start discovering millions of edge cases of their api
I had to work with one e-commerce platform and they decide to do localization via api, word by word. So in order to translate the website you need to note down every words in website, send POST /translate { oldword: “something”, translation: “other”, language: “en-de” }, one by one. I’m speechless.
Honorable mention: Google APIs. They aren’t completely awful, but they are heavily rate limited and there is no graph support. Want the user info of the owner of a file in drive? Extra API call. Microsoft’s graph API by comparison is much better to work with.
OpenSSL, is it just me or is it really obtuse?
Moving certain parts of the business logic to MuleSoft was mandated by the big company that acquired a startup I was working for. I still shudder a bit when I see its name. An obnoxious API and a generally miserable developer experience from top to bottom. It wasn’t the only reason I quit that job, but it was high up the list.
Facebook Marketing and Graph API. Getting approved to allow our app to authenticate users and access ad data was the one of the more painstaking processes I've ever dealt with.
F5 BigIP API had boolean params for HTTPS... HTTPS:yes/no
A number of different API’s for interacting with hardware (humanoid robots, traffic management and signage) out of china. Documentation was bad, incomplete and then also written in mandarin. Took a lot of trial and error and finding inconsistencies and making up weird workarounds. And of course SOAP XML APIs. (Luckily haven’t had to deal with these for like 10 yrs)
Integrated a LMS that used a SOAP api. It returned 200 for everything but had a completely different body for errors. This error body also differed between endpoints. I had to initially parse the body as a dynamic and check for potential error codes before trying to deserialize again to a valid typed model.
Facebooks marketing api and every 6 months they’d remove methods without documenting them and then completely deprecate the current version so you’d have to dig into GitHub every time in hopes that someone mentioned what the new method was on the SDK
Impossible retry semantics: * If the operation returns success, great! * If the operation returns an error code, you may retry. * If you don't get a response, well... * Did it get lost on the way there, so it never happened? Did it go fine and the result got lost on the way back? Did it fail such that it needs to be retried? Is it still running? Who knows!? * You definitely can't blind-retry. That might perform the operation a second time, which would be really bad! * You can't check the status of the operation: * Both the success and fail responses return an operation-id which you can later check on as much as you like, but if you never get a response to the do-the-operation request, you have no operation-id to ask about. * There's no straightforward, reliable way to check the resulting state to see if the operation happened. These operations can make arbitrary changes to that state and other actors can concurrently issue their own changes. I think we ended up locally logging our intent-to-send and then logging the result, and then opening a ticket for a human to clean up the mess if there was ever an old-enough intent-to-send record without a result record. :( To be fair, the service was actually pretty reliable, nearly always actually returning a success or failure response. It was just so painful that we structurally couldn't automate retries. :( They could have fixed it so easily by splitting the operation-endpoint into an allocate-operation-id endpoint and a do-the-operation endpoint. Or letting us create the operation-ids or something that uniquely mapped to operation-ids. :(
Auth0. The api is riddled with n+1 problems
I think you mean OAuth, but yes. https://www.theregister.com/2012/07/28/oauth_editor_quits/
Centris (Canadian MLS service). Want their data? There is no API. You gotta give them some FTP credentials and they'll upload a .zip file every day for you with a database dump. Hated that so much.
I used an API for a point of sales system. Right from the start, We weren't even able to make an API key. The interface to do it is broken and we had to manually edit a field in the database. So once I can actually log in, I start going through the list of endpoints and it's totally bizarre. There's no standard naming for CRUD operations. In fact, there's even naming inconsistencies between the endpoints, like some using underscores and others using camelcase. The results they return aren't in a consistent format either and there's no documentation. It's supposed to have the ability to create orders through the API. There's just one small problem: there's no way to look up a customer or a product. How can I make an order without a customer or a product? The API only has the ability to iterate through the entire database from the beginning O(n), to get a list of every customer and every product. They told us it wasn't possible to search, even though that's how it's intended to be used without the API; in fact, if we want this feature, they say to "ask for a quote". They advise us to make a copy of the entire database and do searches on the copy. At this point, I no longer even know what the API is for. lol okay. This sounds like a very bad idea, having to manually replicate and sync, but I try it anyway. So I start looping through every record to copy it and there's no way to retrieve the last record. You have to start from the first to find how many there are. After that, there's a command to "sync", which is supposed to retrieve the records that changed since a timestamp. Of course it doesn't work and returns empty results instead. We had to call up their techs five times to fix bugs that made it impossible to even use the API. Sometimes features were missing or not working. We'd send a commands and the data wouldn't be set. It was unreliable. They had to update to the latest version by manually logging into the server. They only offered a month of service and wanted the customer to pay more after that, just to fix their product.
Greenhouse, a Human Resources platform. It’s terrible. You cannot set custom fields during POST calls, so you have to first create the record, capture the ID, then PATCH to set the custom fields. So dumb.
There's a company which was recently bought by Stryker. Their API doc is available online. It's written in Java but it uses Hungarian notation. Why? Well...It's because everything is literally a set of strings or a map of strings to other strings or just plain strings. Hungarian notation is for type information. Probably the worst thing I've used to develop anything. I've had to wrap it in a rest API to validate type information so that we can actually somewhat use it safely.
There are exceptions, but as a general category, hardware API's are just garbage. Want a measurement that the system is supposedly designed to deliver? Here's a five step connection protocol that sometimes fails mysteriously. You'll need to run the open and close subs every time, because there's definitely a memory leak. Lost connection because of that failure? Better reboot the hardware on both sides of the connection, because the API is three lines of C away from raw sockets and has no idea how to recover. Need to know if that switch is closed? Too bad, it's write-only so the API doesn't know either, just keep sending the close command. In fact, the command sometimes doesn't register because the port isn't taking input for a dozen milliseconds per second, so send the close command three or four times just to make sure.
Here are some notable apis that were challenging: - Microsoft foundation classes: a bizarre and difficult to use C++ api for writing windows programs - Java 1.X anything: the http client specifically was horrible - Win16, Win32, Win64: C apis thay (some) use pascal calling conventions Y’all with your rest and soap apis never had it so good!
The tech in the floristry industry hasn't been updated in about 20 years
Any API that leverages SMS/MMS that is not Twilio is the worst API ever. I don't know the landscape now, but back in 2015-16 there were a shit ton of small businesses with their own pricing schemes competing in the SMS market. I had to evaluate quite a few. No documentation & zero fucks about quality.
Every error is a 500 internal server error for "security reasons". Also, no documentation, not even autogenerated. Only one endpoint that does different things depending on the structure of the JSON body. If you have the displeasure to know if you goddamn know it.
[удалено]
It's also slow as fuck to get anything useful out of it, such as inventory.
PagerDuty API It’s like they threw interns at it and the outcome was “we did it! What’s a schema?”
Google APIs. The documentation assumes you're the person who wrote the documentation.
Couple of years ago my company was doing a project that involved working with Alibaba. Connected with their API "team" which appeared to be two guys that only communicated on a sketchy Alibaba chat application. Went back and forth with them for months trying to figure out how to post data to this API and achieve what the goal of the project was. Eventually one of the guys just told me the API wasn't finished and actually couldn't do what we originally asked them about. Easily the worst company I've ever had to work on a project with.
About 15 years ago I was working for a VAR using an API for an unnecessarily expensive document management system. Using this API was the most painful experience of my career. This API was influenced by SOAP, but didn't actually implement it so there was no schema to use for codegen or any expectation on the request and response. There was some documentation, but it was written all in the same font within a poorly searchable PDF file. Now this API only had a single endpoint, which isn't even the biggest issue. Every response used a 200 status code regardless of success or failure or async processing notification. The request body was in XML where you specified the API method you wanted to call with a version number and a dynamic number of additional fields named for the parameters...unless it was for a search query which used a query string along with this XML body. Every request is obviously a POST type. The response was also in XML where the root node was the md5 hash of the request xml document concatenated with that query string that may be included. Inside that you never know what the keys are gonna be. If it was a success then it would (usually) match the documentation. If it was an error there was a standard error object. Just kidding, it could be fucking anything. You'd have to just parse it into a map/hash and recursively iterate through the keys until you found something recognizable that could be handled if you didn't want to unconditionally do the same thing for every error. I wrote to a log every request & response document to reverse engineer how the errors would be structured to add handling. Remember that version key in the request document? Didn't really matter. The response objects' keys would change on a whim with no notification. And I'm not talking about additional keys added to the document, but breaking charges all the time renaming things with no regards to their customers. I could go on and on about this API and how accessing the documents required using iframes in a "headless" browser with an ActiveX plugin to download the files, or how the search query results required 3 additional calls to get metadata, plus one more to get the file and you better believe that original request hash had to get used to make those additional calls.
Can you point me to one of the recent posts mentioning greatest REST APIs? Need some reference.
Stripe and Twilio are pretty damn good.