4 ms·
This is fantastic. Maintaining API compatibility is a fine art. A fun fact: for my previous job I developed a set of libraries to make Node API development typ
by eyelidlessness 6y ago
This is fantastic. Maintaining API compatibility is a fine art.
A fun fact: for my previous job I developed a set of libraries to make Node API development type safe and generally easy to use safely with a lot of help from the TS compiler. When I got the chance to prove it out for production use, I was tasked (well I volunteered) with porting a service that had one of the worst API designs I’ve ever encountered. It had no design, totally off the cuff for every route handler. But it was in production and critical, and API stability was a hard requirement.
A wonder of wonders: these libraries worked with almost no rework, mapped to an internal implementation that was much better to work with, and auto generated documentation that was 99% correct (I fixed the two bugs filed over 10 months).
Before I left we were planning a v2 API, and as far as I could tell literally no business logic/service code would need to change. Only the service boundaries.
And on my way out, doing knowledge transfer sessions, all the things that seemed inscrutable about the libraries doing all that work really clicked with the rest of my team. It was already doing the API translation that was the ugly part. Once they saw how it worked with APIs that were designed for use and development, nothing felt painful for the team I was leaving it with.
Planning ahead for this kind of thing is important. You don’t have to have the perfect API. You just have to have good abstractions in place for the inevitability you don’t have the perfect API.
- eyelidlessness 6y agoFollowing up since this is seeing a little bit of attention: I unfortunately couldn’t open source those libraries but I’m already working on their successor. And I have really good ideas how to improve on the original, including: - snapshot testing to identify unexpected API changes - auto generated integration/E2E fuzzing tests to validate API boundaries so you can trust you don’t need to test them yourself and can just trust the type system and your business logic tests - a fully transport layer agnostic interface so you’re not married to HTTP (or REST, or whatever) - the API boundaries are defined with standards-based primitives (JSON Schema) but simple declarative interfaces like io-ts for end users, but this internal structure makes documentation generation a first principles assumption - 400/validation errors will be automatically documented along with success responses - a “choose your own idiom” interface where you can go full on Option type/exhaustive pattern matching for responses, error/result tuple responses, or more TS/Node idiomatic try/catch semantics. But each interface will be type safe from request to response and you won’t have to sacrifice any of the other guarantees listed above. The only tradeoff here is since TS doesn’t have type checked exceptions the other interfaces will probably have richer documentation
- g_delgado14 6y agoany way to "follow" you? Either via a git{hub,lab} repo or twitter or something? Really curious to hear when this is released. Also, I've implemented my own typesafe route abstraction for express before so this is def a projecct I would enjoy contributing to.
- eyelidlessness 6y agoSame handle on GitHub! And Twitter. Currently building my personal tech site/blog (same name on GH Pages, probably everywhere since my last LiveJournal), then getting more focus on this project which I’ll also be blogging about on my site. I hope to have the site up and running next week.
- eyelidlessness 6y agoI wish I could reply to the dead reply. But since I can’t... > And now the business is left with another abstraction no one maintains on top of a legacy system no one understands. Good job. Well deserved promotion. The business made a business decision to evaluate the tech in order to save a critical service that had serious maintenance problems, and made another business decision to use the stack. I barely even advocated for it, I mentioned it one time, we decided to do a spike into feasibility, everyone was pleased with the outcome. The libraries themselves were extensively documented from the start. I made a presentation introducing them before the service port was launched. A greenfield service was under active development for several months before I resigned, and a grand total of two bugs were filed related to that (by me). The team using it had maybe five questions for me over that period. Other services were planned to be ported when feasible. I did two weeks of knowledge transfer during my transition out of the business. I took great care to spend extra time on the most complex parts and had special sessions for what I was unashamed to call the “bad parts”. Overall the reception was very good, and by the end of that there were very few questions. I’m reasonably sure I left my old team and adjacent teams on good footing to stay productive. And I offered to make myself available for free after the fact if anything needed further explanation (which hasn’t been needed). Honestly I know “NIH syndrome” is a smell, but goodness I wish people had a little bit more inclination to take a charitable interpretation and ask questions before attacking.
- notretarded 6y agoAnd now the business is left with another abstraction no one maintains on top of a legacy system no one understands. Good job. Well deserved promotion.