The Future of API Documentation

Chris Lees 21st Jun 2018
3 min read

API Specifications FinSpec PDF Best Practice

For six years now, FixSpec has been championing the idea of electronic specifications in financial services; documentation that can be used (and re-used) across the API lifecycle as the foundation for streamlined, less buggy, more auditable, more efficient, and faster processes.

We have poured thousands and thousands of man-days into developing the most advanced multi-protocol API documentation editor available - SpecServer - that integrates seamlessly into the most advanced multi-protocol certification platform available - Central.

But there is one ghost that continues to stalk the halls - PDF.

You see, we are not operating in a green-field space like other modern API documentation systems like Swagger or API Blueprint. No - most financial services protocols are 20+ years old, and in the late 90's the only meaningful mechanism of exchange was the PDF, and that's the historical baggage we all now share.

Our community is stuck in the twilight zone between the conflicting desire for the efficiency benefits provided by electronic documentation, and "traditional" requirements from internal departments (legal, marketing, sales etc) who expect a branded PDF with all the standard legal trimmings.

As a vendor, we have a ring-side seat and see this conflict first hand. While we don't expect people to maintain data in two places, and we do - of course - provide a PDF export facility, it's both frustrating and heartbreaking to see prospects throw away the massive benefits that modern thinking can bring just because of some trivial customisation for a PDF export or API quirk. It's both illogical and short-sighted because the future is not PDF and quirks; it's electronic and organised.

It's time to look forwards and not backwards.

For those who have never built an automated PDF export function from a website before (I guess that's 99% of readers), you may question why this is such a big deal - isn't it just code? Well... yes. But there's a bigger principle at play here.

All of the time and energy we spend tweaking PDF templates or tinkering with SpecServer to add some strange one-off API quirk, is time we are not investing in building the next-generation of tools to bring you more efficiency and automation. An hour here, or a day there add up over a period of years. It's time we (and you) will never recover. It's wasted time.

I'm reminded of the iconic 1997 Think Different video, which welcomed "the crazy ones" to Apple.

Here's to the crazy ones.
The misfits.
The rebels.
The troublemakers.
The round pegs in the square holes.
The ones who see things differently.
They're not fond of rules.
And they have no respect for the status quo.
You can quote them, disagree with them, glorify or vilify them.
About the only thing you can't do is ignore them.
Because they change things.
They push the human race forward.
While some may see them as the crazy ones, we see genius.
Because the people who are crazy enough to think they can change the world, are the ones who do.

We don't aspire to change the world as Apple have, but we do know we can radically change the financial services API lifecycle and lift everybody out of the inefficient and expensive rut that we all find ourselves in. To achieve that, we want to work with the crazy ones; the ones who know that the status quo can not continue, and are willing to let go of the past in their pursuit of a better, more efficient future.

If you are ready to make a difference, let go of PDF and think differently (or want to talk to people who do), then here's to you. Drop me a line and let's talk.

Image Credits: By Apple logo Think Different.png:derivative work: Stoopkitty (talk) 19:55, 31 January 2011 (UTC) - Apple logo Think Different.png, Public Domain,

Find This Useful?

To receive more tips for improving efficiency in YOUR connectivity process, sign up to our FREE monthly email newsletter.

Awesome - thanks for signing up. You can unsubscribe at any time by simply dropping us a line.