API first for Products

Lead question : Why API First

Ask a product manager what is the different between made or order software and a product .He will tell you how product is general purpose for the given domain (not generic tough ).How it captures a broad set of use cases from the domain .How it is flexible in adopting to diff combinations of rules that are included in these use case .How it is future proof and is ready for future changes in domain .How it benefits from vast experience from we have in the domain/customers /consultancy . It goes on .

Yet when it comes to day in life a of developer he is often made to code first , code just what he has been asked for and ship it . It is obvious that a start up will only put coding effort into what sells but should that rule apply  to the very definition of the product as it is conceived  ?Is defining a product/service/roadmap same as coding it ? Such gap between what is “Seen” by product and what developers are made to do are solved by evolution read software design . API first is a prime example of being comprehensive and thus evolution ready yet riding the demand wave frugally .

Business scenario for  API first

• Integration /Consumption : Software need to be integrated by different parties as the success happen .Would you like to struggle to meet demands of this success come your way ? or would you like to be ready for it with some top-up effort .The answer is in thinking API first . Once you  think of well  thought of APIs  gluing them become easy and future successes becomes faster . This could mean integrating in or integrating out ie consuming (and monetization ).
• Aggregation/federation  : The internet economy of aggregation made famous by amazon/uber has made clear a case for softwares co-operating with each other .This increases market reach and revenue .However aggregation economy is volatile and competitive . One need to be ready at shorter notice than typical integration projects .The integrations also need to be robust for the parent party (and their customers ) to trust you .Another flavor could be federation of services amongst equals . A well thought of API on both sides make such integration easy-fast-reliable .
• Extension  : Acquisition ,Saas enablement  ,inhouse aggregation(called integration ) or even customization are typical cases of base capability of software being enhanced by extension .We may thinking of moving from web to mobile to chatbots/alexa . We may also consider taking base software and enabling that as multitenant offering .  While these extensions are value positive for every one they need be very liberal in capability but restrictive in scope .This help us keep sanctity of base software  yet allow creative but reasonable value add . An API layer will clear laid out  extension helps .

All of these driver point towards one fact that business that are built with well defined contracts stand to benefit from this opportunities as opposed to software that are inwards focused and need extra work for any opening up .While this discourse underlines that API first help us with readiness in terms of external forces , the same game plays out within the teams also .It is just that inter team play is seen in the light of following themes

Advantages of API first approach

1. Domain fitment : The tendency for Business analyst and developer to grab a piece of functionality under discussion and “just code it” .This has huge chance of teams creating code that is few layers higher in domain and miss out in fundamental building blocks .An API first approach also forces teams to think bottom up inside the domain where they are made to think of the “built up” of the functionality .This ensures that the domain of software in considered in totality before team chooses to pick up one slice of it and code it .
2. Parallelization : API also stand for clear contracts .So it allows teams to do more parallel work as api-first minimizes risk of large scale integration of parallel work streams .Productivity and time or marker related gains follow .Agile ie .
3. Testing : Since APIs are laid our clearly the function or security test team get more and enough time for deep thought testing approaches at all levels of test coverage .
4. Functional resilience : Since API commits to a final contract it gives a robust functional capability which is strength .At the same time there are many internal implementation details are that are open to amendments which adds to overall resilience .Think of a case where old rule based API is replaced with new Machine learning based API ,while the API is same the quality of algorithm is smarter .
5. Evolution : A well laid out contract also facilitates future evolution easy .It could be new version , a customized or localized flavor which offers changes in the same neighborhood as original older version of API (hence evolution ) . This however needs a better governance put in place .
6. Tech Debt repayment : A well defined contract also allows decoupling between team producing it and team consuming it . This allows the team to keep on changing internal technical detail of their API healthy and repay tech debt without disruption .
7. Other than code needs : There are many other than code needs like performance ,build , documentations , availability  , monitoring ,audit ,security which are get into motion after the software is committed to repo .API first lays out clear shape of the software to be and allows these team to think thought early on and facilitates these other than code needs at much deeper level of engagement .

Pitfalls and background of API First

API first is often confused with webservices .This often leads teams into thinking that if they are not exposing any url style webservices to anyone they are free .A better term for API-first could be contract first (but that’s very technical world so API is used ). This means that no matter whether one is creating piece of software that is consumed by outside world or other teams/developers in your company ,so long there is interdependency one need to commit to clear contract .And in order to see the gains of agility etc one need to commit to this contract first .This also means that all layers of software from external facing UI -webservices to components-frameworks in middle layer till data-integration layer one need to think  of defining clear contract .To that effect every component is an API that is producing or consuming other API . Even so-called cross cutting layers like logging are mater of laying out clear cut APIs.

The concept of defining clear interfaces in now new to programmers . We often talk of specifying clear interfaces and programming to interfaces .However this good practice start at individual program and ends at design patterns . May be it is seen as something only serve side programmer do . But , as we approaches more layered , more distributed(teams as well as software) , more integrated and more reusable (think open source ) , more componentized and so on the value of clearly laid out contracts between these seams is apparent . API first is this a mainstream realization of this fact , tough people confuse API with webservices only .

more reading ,Bezos Amazon API Manifesto and link to Yegge of Googles Rant : https://gigaom.com/2011/10/12/419-the-biggest-thing-amazon-got-right-the-platform/