API Specifications Best Practice
Since I started my career in the trading connectivity industry, 14 years ago, I have always been exposed to API specifications: either as a client support, a project manager or a business analyst. Looking back at these exciting hours spent decrypting those documents, the thing that strikes me the most is how little the methodology changed over the years, and limited effort was invested to simplify the on-boarding process.
If you look at the FIX protocol for example: it evolved to become an international standard in less than 20 years. Yet, FIX shops, whether they are network providers, brokers, trading venues still need to find innovative ways to share their API specifications with the rest of their customers.
I wrote specifications myself and acknowledge how complicated it is to address all level of knowledge’s and cater various needs of your readers. Interestingly enough, most of us take for granted how a spec document should be laid out: a succession of tables that list the messages, the fields in those messages and the values of those fields. The rest of the technical verbose is left to the discretion of the writer. The final output is invariably a flat file (PDF being the clear favourite). No matter how much dedication the authors put into their document, they will always fell short of some readers expectations.
Today, I would like to share with you some ingredients that, I believe, constitute the base of a good specification recipe.
It is especially true when one’s specs is derived from a protocol frequently used in the industry (FIX, OMX, ITCH etc...) The document should be able to highlight the parts of the specifications that defer from the standard. This is what the reader is eager to find out. If the logon mechanism follows the standard, no need to spend pages on it.
This is one of the most complex aspect that writers struggle with. A user who already certified will not expect the same level of details and sophistication than a user totally new to the API. How to cater for those various expectations?
Some will assume that readers know the basics and skip them entirely. Other will cover every single details to prevent any misinterpretation. The JPX Osaka Exchange J-Gate document, for instance, is one of best reference on Nasdaq OMX protocol. But it comes at a price: a 600 page document, which must be a nightmare for its publisher to maintain through each new release.
A way to address various level of knowledge is to isolate the basics of the protocol in separate set of documents. These annexes will require less maintenance effort as their content is unlikely to be affected by technical changes.
Very rarely you will get a comprehensive mapping between functional and technical aspects of a message. Technical analysts have a hard time to understand how their code affects the product functionality. It is extremely helpful to show how a specific business workflow translates into a technical message content, and impacts the fields’ requirements.
Workflow diagrams are also a great source of information to capture the logic of client/server interaction. Ideally the workflows offer hyperlinks/references to the related messages description to ease the reader navigation.
Theory is good. But at some point, providing message sample is the best way to comfort users in their understanding and limit the risk of failure during the testing/certification phase. It is especially useful for more complex scenarios that cannot be easily reproduce in UAT environment (recovery mechanism, DR failover, etc…)
Specs editors don’t always do a good job on their versions change history, yet it is the most important part of the document. The readers rely on it to run a first impact assessment for any new release.
I found that ASX does a good job in providing comprehensive notices for all new releases of their trading environment. It contains the right level of details on the changes introduced, both at the technical and functional level. The drawback is that each notice lives independently from the main spec document.
All of these are not revolutionary thoughts. Most of my counterparts probably share the same ideas. My opinion is that we limit ourselves by the means and tools we used: those are not versatile enough to convey the full picture in a consistent manner.
Now that protocol messaging languages have merged into a few standards, it is time to rethink the ways we store and share the technical knowledge to help the on-boarding community to reach the next level of efficiency and cost-saving.
If you have any additional thoughts or different perspective on the subject, I'd love to hear them - feel get in touch.