This happens all the time.

Once fairly early in my career, a customer requested a custom REST interface to be added to our product. This interface was discussed at length during the customers “functional requirements” phase of a project to provide them with a customized solution; the customer’s internal processes demanded that there be a “functional requirements document” in addition to a “business requirements document” and a “technical requirements document.”

These requirements documents were an incredibly tedious and time wasting activity; it took 3 months of meetings to produce enough paper to get to the point where there was enough definition of what to do for us to start working. The problem was, we actually needed those 3 months to be working; my boss originally planned for 1 week of requirements gathering because the customer had a similar solution already and figured that they should therefore already know what they want. So once the business requirements document and the functional requirements document were both finished, we just started implementation work right away.

I was bored out of my mind at this point by all of these stupid meetings, so I was thrilled to just write something. So I wrote the whole REST interface in an afternoon. In the Functional Requirements Document, there was a giant table which specified exactly which values should be returned, and it also said it was to be returned as XML. Yeah, that’s pretty weird, but I read Roy Fielding’s paper about hypermedia being the engine of application state, so I knew it was not only possible but perhaps a preference someone might have. So I just wrote the thing to return XML and finished the interface pretty early in the project. It got released to the customer shortly afterwards in one of the early builds of the project.

About two weeks later, my boss and I are on our regular call with the customer to talk about the project. The main technical person on the customer side is there, and they have an exchange that goes something like this:

Customer Techie: We need to talk about this interface.

My Boss: Okay, what about it?

CT: This wan’t what we were expecting.

MB: How so?

CT: Well, we figured you’d like, talk to us about it first before actually doing it. That there’d be a whole discussion and everything.

MB: We did talk about it. It’s described in the FRD.

CT: Yeah, but the FRD isn’t actually very technical you know? We were thinking that we’d have another discussion to iron it out with the TRD.

MB: What’s there to iron out? It’s all spelled out right there. There’s a table and everything.

CT: Yeah, but it returns XML instead of JSON, and we’d have structured it differently.

MB: It says to return XML in Section 8.23. Complete with the exact table of values to return.

CT: Yeah but like, we didn’t think you’d actually just do that.

MB: Why wouldn’t we? My engineer implemented exactly what this thing says!

CT: Yeah, but this return value name is weird, we wouldn’t have use this name.

MB: That’s the name you told us to use, it’s right there in the table!

That discussion ended up going in that particular circle for another minute or so before everyone decided to move on to something more pressing than whether or not my return value names were camel case enough. There was other chaos with the project, so people quickly forgot about this exchange and the interface got deployed to production a few months later. To this day, I think it is still there exactly the way I wrote it; they bought the source code, but I don’t think they ever changed that interface.

The original comment on Reddit I wrote, from which this was adapted for this blog.