Write down the contract first: API-First
Most engineers are not used to defining the Interface first and then writing the implementation. Normally they write the implementation and then the Interface is automatically generated from that.
Product Lead: Provide me the API definition first, because I want other teams to start working on it also, let's lock it.Engineer: Ok, it is not a problem, it will be automatically generated.Product Lead: No, No! I want you to define the APIs in OpenAPI Specification, so all teams can have an agreement on this.Engineer: (not convinced at all), It is nothing but rework. If I can generate something automatically then why should I write it?Product Lead: So do you want all other teams to wait until you are done with your code?Or let's take it other way, your component development is dependent on X-Engineer's component's API and he has not started development yet which may take 4 weeks to complete.Do you want to wait 4 weeks for that API implementation and start working on this?Engineer: ( He is silent though still can not agree to put effort to write the API definitions first, so he comes up with the real reason) There will be lots of discoveries and changes in implementation in the future, APIs will evolve, will it not result in more trouble for all?Product Lead: That is where the versioning comes. And even for minor changes you can do the API definition change first with the version number and announce others to adjust. Rest can change accordingly and deploy things maintaining your new version deployment timeline.
Why the engineer is too reluctant to define the API first and then implement it. We can have lots of logic for and against. Though the basic problem I found is less experience with distributed systems development, parallel works, and collaborating with multiple teams on the same timeline.
Lazy to write down the concept/Interface detail with standard
In a simple case, A frontend developer and backend developer sit together to define the request parameters and response parameters. Either they may use note-keeping tools or a spreadsheet to define the parameters. And in most cases, when a newcomer engineer wants to start working on it, he feels like he is reading a doctor’s prescription and starts requesting for KT (knowledge transfer) session. Why is it so hard to use specification standards (e.g OpenAPI) to draft an API and collaborate on that? Maybe because there is an hour’s learning curve to adopt the OpenAPI specification way of drafting. And to avoid that learning curve, we skip creating an asset that can be used as a solid contract following proper standards.
Takeaway
Agree on the API following standard specifications before you start implementing it.
###
Disclaimer: The views reflected in this article are the views of the author and do not necessarily reflect the views of any past or present employer of the author.
