By Melissa Wood, Senior Integration Specialist at Sound Payments –
The gauntlet’s been thrown. A challenge has been waged upon you. A new API must be provided for the masses, which in this case are your company’s customers. To you, this API can only be “One API to Rule Them All” to draw in the clients. Your first thought is, “One does not simply write an API. There are methods, functions, and messages to be built. Not just that, the parameters, values and definitions must also be defined. To do it right, it cannot be done alone. It is folly.” But then you realize that for your company to succeed and become a leader in its market segment, you welcome the challenge and tell yourself, “I can manage it. I must.” Welcome this challenge and look at it as an adventure. And so, your journey begins.
The first part of your API journey is to understand your audience. The ones who will be drawn to this API will be wielding different swords as CTOs, technical project managers, systems integrators, and application developers. In the end, developers and system analysts will use your API as a map to build and test their integrated systems. While you want to show developers its power and greatness, you must also guide them how to use it wisely. What may seem like common sense and common knowledge to you is not necessarily known to your audience. You are the subject matter expert for your company therefore you must author this guide, this map, for your developers to use on their journey. The basics should be a “Getting Started Guide,” industry overview with day to day operation flows, architectural overview diagram and support contact info. Include links to online testing tools and other support services offered for assistance. While many people just go straight to the meat and skip over the basics (I’m guilty of this myself), you have provided guidance. Remember, the hasty stroke goes oft astray.
Now that you know who you will meet along your journey, you must convey your knowledge to ease their trek. The main reason for this API documentation is to clearly outline every endpoint, method, function, parameter, and possible values. Without this, it becomes a map with no legend. Keeping in mind that your audience will not read the documentation from beginning to end like a book, structure the guide in a simple to follow layout. An example is by Method, or Call, with a concise description. List the parameters, rules, format, and description for both Requests and Responses. Always include samples of the message in each format your platform supports. Response and error codes are a must. These are the swords by which software development can live or die. Your customers are your partners and you share this map for the journey.
Through any journey you will be tested. Shouldn’t that be the same for your API? Before releasing your API, it should be thoroughly tested. Testing should include obvious things like standard use cases for all methods and their standard functions. But it should also include testing things out of the norm because this could be an unexpected journey as well. Test as though you are a developer who has not read the “Getting Started” guide, test for exceptions, and test for error handling. Once exhaustive testing is complete, your API is ready to face any challenge.
The “One API to Rule Them All” is ready to introduce to your customer base. Its purpose is effective but what about updating it and maintaining it? Versioning should be clear. Major updates should follow the versioning convention of the product for which the API was written. Keep the same layout of the original documentation and use existing terminology to maintain consistency for the new features as you did the original documentation. If there are minor tweaks to the documentation, use minor versioning. Include a change log with links to the new documentation to make it effortless to find.
You rose to the challenge. You have “One API to Rule Them All” and with that comes great responsibility. This was just the first of many journeys. You will go there and back again, and again. Many times over. Each one will be different and each time you will find new challenges. Face each challenge by wielding Andúril and slay any obstacles that come your way