Peer API Design Review Sessions

Public APIs have always benefitted from something that internal APIs do not always received—-feedback from other people. While the whole public API thing didn’t play out as I originally imagined, there is still a lot of benefit in letting other see, and provide open feedback on your API. It is painful for many developers to receive feedback on their API, and it is something that can be even more painful when it is done publicly. This is why so many of us shy away from establishing feedback loops around our APIs. It is hard work to properly design, develop, and then articulate our API vision to an external audience. It is something I understand well, but still suffer from when it comes to properly accessioning peer review and feedback on my API designs.

I prefer opening up to peer reviews of my API designs while they are still just mocks. I’m less invested in them at this point, and it is easier to receive feedback on them. It is way less painful to engage in an ongoing discussion fo what an API should (and shouldn’t) do early on, then it is to define the vision, deliver an API as code or within a gateway, and then have people comment on your baby that you have given birth to. It hurts to have people question your vision, and what you’ve put forth. Especially for us fragile white men who who aren’t often very good at accepting critical feedback, and want to just be left to our own devices. I’d much prefer just being a coder, but around 2008 through 2010 I saw the benefits to my own personal development when I opened up my work to my peers and let a little sunlight in. I am a better developer because of it.

One tool in my API toolbox that is growing in importance is the peer, and open API design review sessions. Taking an OpenAPI draft, loading it into Swagger Editor, firing up a Zoom or Google Hangout, and inviting others to openly share in the design of an API. I find it isn’t something everyone is equipped to do, but many are open to learning, or at least curious about how it works. Curious is good. It is a start. I think many folks aren’t fluent in the API design process, and are often afraid to appear like they don’t know what they are doing, and having an open discussion throughout the API design process helps them learn out in the open. Using a process that helps everyone involved learn together, and lower their guard a little bit when it comes to new ideas, new ways of doing things, and discussing the overall developer experience (DX) of delivering a quality API.

Peer API Design reviews is something I’d love to see more API design tooling support. If nothing else, more people just doing it with existing tools. You may not have fully embraced a complete API design first approach within your enterprise group, but openly discussing API design patterns is important. It is critical for any API developer to receive feedback on their design from other stakeholders, and other API development peers. It is important that we allow ourselves to open up to this feedback and sometimes criticism of our designs, based upon what others know, sharing potential views on how an API can reduce friction for consumers. Ideally, this process is also made accessible to non-developer stakeholders, and even business owners, but I’m thinking this is another post all by itself—-for right now, I just want to advocate for more peer API design review sessions.