The five steps of our set of best practices work like a combination lock. They work properly only if they are followed in sequence.
Planning is perhaps the most important step in the API lifecycle because it puts forth the blueprints needed to build a sucessful API. During the planning stage, your organization needs to figure out two issues:
- The business value of the proposed API; and
- How this API gives you a leg over your competition.
Before you hand off instructions to your coders, you need to have a clear roadmap (think fresh blacktop, newly painted double-yellow lines) of the benefits this API will offer to both your end users and third-party developers. Then you need to be able to show how this API separates you from your competition, whether it is through some unique functionality or clever leveraging of a tool that others want.
Too often, businesses jump to the â€śBuildâ€ť step before completing the â€śPlanâ€ť step. This can occur for a number of reasons, including:
- The (mistaken) assumption that an organizationâ€™s coders need unfettered creativity to design something mind-blowing (as opposed to useful); or
- The reality that planning for APIs, as with most things, requires deliberation and consideration, (i.e., itâ€™s dull).
But as with most things, (L.A. traffic being a notable exception), shortcuts create more headaches than anything else. Consider these two real-world scenarios:
- A financial data firm builds an API that gives developers and end users free access to much of its copyrighted financial information â€“ for free.
- A companyâ€™s legal department, concerned about various risks, forces a new API to operate as a closed beta rolled out to a handful of developers. These developers must sign a 20-page terms of service agreement before they may access the API.
In the first case, the firm failed to place an accurate business value to the information its API would generate. And now that its users expect to obtain this data for free, the firm canâ€™t exactly say, â€śWait, we meant to charge for this!â€ť without generating ill-will among end users and damaging trust with the developers using the API.
The second case resulted from a lack of communication. Because the parties involved in devising and building the API failed to articulate the business value to the legal department, whose actions hobbled the API to such a degree that it became a nonstarter â€“ and left a nice opening for the companyâ€™s competitors.
So plan before you build. The structure youâ€™ve developed in this step should set you up well to tackle the subsequent ones.Â Â (And take this as a hint for what the next installment of this series will be)
By the way, if youâ€™re interested in learning more about our API lifecycle, please check out our YouTube video.