I have recently been working with a 3rd party API that I had to make so many custom quirky algorithms just to return the basic information that it has basically driven me nuts...

What is your worst experience with a 3rd Party API?


Again, not 3rd party, but if you've used the Facebook APIs, they are a disaster. All of the examples are broken, the documentation is out of date because they keep breaking backwards compatiblility, the forums are poorly controlled, and even some of the facebook people in the IRC channel seem delightfully unattached from what is happening. I'm pretty surprised anyone can use it.


The Win32 API.

One function, CreateFile, can do all of the following:

  1. Open, create, append to a file
  2. Open raw access to physical disks
  3. Open raw access to volumes
  4. Open file streams (NTFS only!)
  5. Open directories
  6. Open "changers" (whatever those are)
  7. Open COM/Parallel Port resources
  8. Open consoles (Consoles!!!)
  9. Open mail slots (what?)
  10. Open pipes

It's as if Microsoft engineers would have been penalized if they created another function to break this one up. But I imagine that this was purely a geek choice:

Well all these distinct resources abide by the same interface. Therefore, they should all be created by the same function. Eureka!!!






Well, one of the worst is Perl/Tk.

It's poorly documented.. even the O'Reilly book has terrible errors in it. The parameters to similar function calls are inconsistent. There are strange bugs, like scroll boxes not adding scroll bars when needed, but only if certain packing options are used. The widgets just look strange sometimes.. I could go on and on..



Microsoft Office OLE Automation... nothing like a dialog box popping up here and there telling me that my margins are too small...


Awhile back I was working with a fairly old COM component. I started using a few new functions on the component, wrote some tests and watched them fail miserably. Several days of debugging later I decided that I must have misunderstood what the new functions did because they were succeeding but not having the effect I would expect. I dug around a bit and found the source code and to my surprise I was greeted with something similar to the following

HRESULT SomeObject::SomeMethod() {
  // Even though we implement IFoo, we don't support this operation
  return S_OK;

Not a 3rd party really, but Solomon Accounting, which was purchased by Great Plains and then Microsoft, was absolutely, positively the worst piece of !@$% I've ever encountered.


Anything involving SOAP in Ruby. The mismatch between the two is so much that it just does not turn out well. The ruby soap library also does some fun things when generating code from WSDL. My favorite is that it doesn't namespace the classes generated from the webservice. If the webservice uses the same class names as your rails models, then the webservice classes override your models. If you want to use two SOAP services that have any overlap in class names, then the behavior is determined by whichever service code is loaded first. The gem version of soap4r versus the standard library version can also cause hilarity.


Not sure if this counts as "third party" since the API is by Sun and for Java, but it's an extension API: JAI (Java Advanced Imaging). As far as I can tell the designers of this API hated static type checking.

One of the core parts of the API is a class called JAI with a bunch of create methods that take a String identifying an operation and some number of Object and/or int parameters, and return an object representing the operation. You need to create these operation objects to do pretty much anything, and at the time I was using it (several years ago) the only way to do this was to go through these create methods.


OpenSocial API - a true nightmare.


DevExpress's set of ASP.Net components. The amount of configuration needed to get something to even display on the screen is astronomical. Their grid control for instance has about 60 properties(about 10 have a description of "Internal use only") and 3 of these properties are subclasses with another 20 or 30 properties in each class. And of course just because you assign an event to OnFocusRow doesn't mean that event will ever be reached. No no, you have to assigning a new clientside event first to basically do nothing but return 0 and then it will work. Why they couldn't have done this themselves I'm not sure. Their solution to a lot of problems is "well the source code is available for purchase"

Their Demo report designer(winforms) is also a huge mess. They brag about it being "customizable". It's almost easier to write your own report writer than to get one working out of there report-designing components.

And finally, the huge over abuse of strings. This is what happens when you drop an ASP.Net ReportViewer component onto a winform:

<dx:ReportToolbar ID="Toolbar" runat='server' ShowDefaultButtons='False' 
        ReportViewer="<%# Reporter %>">
            <dx:ReportToolbarButton ItemKind='Search' />
            <dx:ReportToolbarSeparator />
            <dx:ReportToolbarButton ItemKind='PrintReport' />
            <dx:ReportToolbarButton ItemKind='PrintPage' />
            <dx:ReportToolbarSeparator />
            <dx:ReportToolbarButton Enabled='False' ItemKind='FirstPage' />
            <dx:ReportToolbarButton Enabled='False' ItemKind='PreviousPage' />
            <dx:ReportToolbarLabel ItemKind='PageLabel' />
            <dx:ReportToolbarComboBox ItemKind='PageNumber' Width='65px'>
            <dx:ReportToolbarLabel ItemKind='OfLabel' />
            <dx:ReportToolbarTextBox IsReadOnly='True' ItemKind='PageCount' />
            <dx:ReportToolbarButton ItemKind='NextPage' />
            <dx:ReportToolbarButton ItemKind='LastPage' />
            <dx:ReportToolbarSeparator />
            <dx:ReportToolbarButton ItemKind='SaveToDisk' />
            <dx:ReportToolbarButton ItemKind='SaveToWindow' />
            <dx:ReportToolbarComboBox ItemKind='SaveFormat' Width='70px'>
                    <dx:ListElement Value='pdf' />
                    <dx:ListElement Value='xls' />
                    <dx:ListElement Value='xlsx' />
                    <dx:ListElement Value='rtf' />
                    <dx:ListElement Value='mht' />
                    <dx:ListElement Value='txt' />
                    <dx:ListElement Value='csv' />
                    <dx:ListElement Value='png' />
                <Margins MarginLeft='3px' MarginRight='3px' />
<dx:ReportViewer ID="Reporter" runat="server">

And yes, all of that code is required and intellisense doesn't help for strings.

Oh and did I tell you they reinvented the Label? ASP.Net's Label control didn't provide enough options for disabling it:

alt text


The visual studio API for creating language plugins. Not the extensibility API which isn't too bad but the VSIP api for actually creating new project types, debuggers etc. All ugly-ass COM interfaces with indecipherable names and very little documentation. Might have improved since I used it but uurch - it was pretty nasty.


Autodesk FBX.

It has it all, or at least had it all last time I checked!

  1. Memory leaks
  2. Memory corruption and crashes
  3. Multiple ways of doing the same thing.
  4. Binary only distribution
  5. Poor performance and memory wasting.
  6. C++ abi problems meaning there needs to be a specific library for every C++ compiler and runtime library
  7. Leaking of symbols that conflicts with your own during linking
  8. Unspecific about thread safety

The Adobe forms API (using OCX controls) was also pretty awful circa 2001.


Some APIs aren't actually methods to be called, instead they're complicated machine-readable data (sometimes using a binary format) to be parsed.


Gracenote cddb - we had to pay a lot of money to license it, and they got their information from volunteers. Then they kept releasing different versions to us via CDs in short timeframes and changing symbol names and library names so the code had to change. It was incredible.

Horrible company.

if I remember correctly the sample code was awful too.


Livelink (OpenText) API

  • Everything comes back as some bizarre form of a jagged array
  • The documentation provides absolutely no examples
  • [your favorite search engine] typically returns no results for a given API method
  • The support forums feel near abandoned
  • The only reliable way of understanding the resultant data is to run the data in the Livelink debugger
  • And the finally... the system costs tens (hundreds) of thousands of dollars

The wall next to my desk has an imprint of my head...

A very simple example of getting a value out of an API method:

var workflow = new LAPI_Workflow(CurrentSession);

// every Livelink method uses an out variable
LLValue outValue;
// every method returns an integer that says if the call was
// a success or not, where 0 = success and any other integer
// is a failure... oh yeah, there is no reference to what any
// of the failure values mean, you have to create your own
// error dictionary.
int result = workflow.ListWorkTasks(workId, subWorkId, taskId, outValue);

if (result = 0)
  // and now let's traverse through at least 3 different arrays!
  string taskName = outValue.toValue(0).toValue("TASKS").toValue(0).toString("TaskName");

Aaack!!! :D


The single most worst API I have had to deal with recently is the Brightcove developer API. It sucks, the documentation sucks and the support sucks.

Firstly, you have three ways of customising a video player - actionscript, BEML (Brightcove Experience Markup Language) or Javascript. I do not do Flash so I cannot comment on the actionscript API, but I have tried both the BEML and Javascript approaches and nearly drank myself to death.

Firstly, BEML is designed as an xml-based customisation language for their Flash players - except its hardly documented, and what documentation there is is woefully inadequate. For example, their documentation says that you can style components using CSS - but what they do not tell you (and I had to submit a forum question and an email support question to find out) is that its not actually standard CSS, its something they have made up. Also, not all selectors apply to all components - however, the only documentation for any of this is an example customised player, which again doesn't cover all selectors available.

Staying with BEML, the documentation does not mention that some components will only work as described when included as children of other components, or that certain stylings will only work when contained in certain components.

Secondly, the Javascript API means you end up basically with a blank player and recreate all of the Brightcove supplied parts yourself - and events that should be fired are not, while events that are fired are fired inconsistently.

Brightcove supply two options for retrieving data for usage in remote APIs - MRSS as xml, or json objects. The problem is, neither supply all the data you need, and thus you need to use both - as an example, the MRSS feed is missing the media:content tag, and thus is invalid against the MRSS spec but when querying this with support I got told 'we are restricted in what fields we can supply by the MRSS spec, so we cannot supply any extra.'

Trying to generate a video site map is mind numbingly horrendous as well. Brightcove supply two examples of video site map generation - the first one, if followed, produces a site map that Brightcove themselves admit (via a support email) is invalid, while the second one relies on a feature that severely restricts your use of players.