Spent a lot of time designing a proper HTTP (dare I even say RESTful) API for our - what is until now a closed system, using a little-known/badly-supported message-over-websocket protocol to do RPC-style communications - supposedly enterprise-grade product.

I make the API spec go through several rounds of review with the rest of the dev team and customers/partners alike. After a few iterations, everybody agrees that the spec will meet the necessary requirements.

I start implementing according to spec. Because this is the first time we're actually building proper HTTP handling into the product, but we of course have to make it work at least somewhat with the RPC-style codebase, it's mostly foundational work. But still, I manage to get some initial endpoints fully implemented and working as per the spec we agreed. The first PR is created, reviews are positive, the direction is clear and what's there already works.

At this point in time, I leave on my honeymoon for two weeks. Naturally, I assume that the remaining endpoints will be completed following the outlines/example of the endpoints which I built. When I come back, the team mentions that the implementation is completed and I believe all is well.

The feature is deployed selectively to some alpha customers to start validation testing before the big rollout. It's been like that for a good month, until a few days ago when I get a question related to a PoC integration which they can't seem to get to work.

I start investigating and notice that the API hasn't been implemented according to the previously agreed upon spec at all. Not only did the team manage to implement the missing functionality in strange and some even broken ways, they also managed to refactor my previously working endpoints into being non-compliant.

Now, I'm a flexible guy. It's not because something isn't done exactly as I've imagined it that it's automatically bad. However, I know from experience that designing a good/clear/future-proof API is a tricky exercise. I've put a lot of time and effort into deliberate design decisions that made up the spec that we all reviewed repeatedly and agreed upon. The current implementation might also be fine, but I now have to go over each endpoint again and reason about whether the implementation still fulfills the requirements (both soft and hard) that we set out to meet.

I'm met with resistance, pushback and disbelief from product management and dev co-workers alike when I raise the concern that the API might actually not be production-ready (while I'm frantically rewriting my integration tests and figuring out how the actual implementation works in comparison to what was spec'ed).

Oh, and did I mention that product management wants to release this by end-of-week?!

  • 5
    Wonder why no one spoke up about not knowing how to implement the spec...
  • 0
    Everything about this smells like Oracle. Leave while you can!
  • 0
    That is quite a lot of effort to be wasted.
    Just make sure your ass is covered, and that the PM knew about the problems, and decided tobrelease anyways. Shitstorm will come down, make sure you get out on top.
  • 0
    Sounds like a job for GRAPH QL! Not because its any better than a restful api, but because if no one else knows how to build it, then you've got a clean slate to work with!
  • 1
    @magicMirror Yes, I figured I'll have to go in ass-covering mode. I hate it though, to realize that I'm now working for a company where this type of back-office politics is part of the day-to-day
  • 0
    @call-a3 Yup. welcome to the Corporate world!
    I hope you enjoyed the honeymoon, cause there will be some long day@the office now.
  • 0
    Take a cold tea and look at it blow in their face.

    You've already done your sage part, notified of not readiness of the "API".

    It's time someone learns the stupid self inflicted pain.
Add Comment