QuickFIX vs FIX Orchestra vs FinSpec — what’s the difference?
For almost a decade now, I’ve been evangelizing to people working in FIX connectivity — a niche API format within financial services — about a better way of working. Something that will free them from the daily drudgery of low-value tasks and open up a better, more automated future.
What’s Going Wrong?
At it’s heart, the problem with FIX connectivity is that it is so old. Really old in fact. As a relic of the mid 90’s, it is older than the commercial internet. Of course, over that time it has blossomed in terms of scope and what it can do, but still the original pioneers would still recognize “modern” FIX today.
It’s a protocol that has been a victim of it’s own success in some ways; it is so widely adopted, that it is almost inconceivable that a new trading platform wanting to attract large customers would NOT offer a FIX API. Indeed new crypto exchanges seeking to attract non-retail customers will almost certainly already offer FIX, or have it in development.
If FIX is so popular, what’s the problem?
The problem is in the working practices that surround FIX. While we’ve witnessed an explosion in REST APIs in the last decade, which increasingly offer OpenAPI-based documentation and associated tooling, FIX connectivity remains largely wedded to the idea of PDF-based documentation. The only major exception to this is can be found (again) in new, crypto exchanges who now take it for granted that their API documentation is a web page and try to cram FIX documentation into the same format.
Am I just suggesting that PDF should be replaced by an online documentation page then? For course not! The secret ingredient that makes REST APIs so much easier, faster and more pleasant to connect to than FIX, is the presence of the machine-readable OpenAPI document.
This superpower of this single document is its propensity to be re-used.
- Generate documentation (such as Redoc)
- Generate emulators and mocks (such as OpenAPI Generator)
- Generate code stubs (such as those from SmartBear)
- Generate test cases (perhaps leveraging Postman Collections)
The API First movement says that the OpenAPI document is the first asset to be written, rather than the last. Crucially, the OpenAPI document exists BEFORE the code is developed to implement it, allowing all stakeholders to agree intended behaviour (avoiding later re-work), and allowing QA tests to be written independently (as opposed to “freezing” already-written code).
None of this really exists in FIX today unfortunately. While firms offering FIX API believe they are still “doing what everybody else is doing” in documenting API specifications as PDF, the reality is that they are stuck in an endless cycle of inefficiency:
- Documentation is written last (often as an after-thought), and is therefore inaccurate or incomplete, causing client confusion and errors
- Whilst it is typically the developer who chooses the FIX tags to use, they do not write the docs, and so we play a game of telephone where the documents may not match the code
- The absence of a mocking capability risks developers burning precious time re-working code because issues are caught too late
- The absence of automated test case generation means that there is no way of catching documentation errors — they can’t be QA’ed.
So if we are looking for an OpenAPI-equivalent for FIX, what are our options? I want to cover three possible formats here.
QuickFIX
People who have been around FIX some some time have probably seen a XML file that is sometime referred to as a “Data Dictionary”.
This is technically a configuration file in the extremely popular open-source QuickFIX FIX engine (the same format is used in all language-specific engines), which explains why a lot of people have seen it. The format is so common in fact, that many other FIX engines (such as fix8) have also adopted it as their own configuration file.
Nobody “owns” the QuickFIX format and — as far as I can tell — there is no formal schema definition… it is what it is. As you can see from the above, it is a very simplistic list of messages and fields within them. Elsewhere in the document, there is also a field-level definition which maps to the numeric ID for each field, along with it’s datatype and valid values.
The crucial thing to note about the format, however, is that is does not contain any descriptive information; that was not it’s original purpose. Nor can it capture anything related to the workflow implemented in the API. These two facts make it a poor choice if we were to think about replicating the OpenAPI benefits in FIX; no descriptive sections mean no documentation, and no workflow means no mocks, emulators or automated tests.
FIX Orchestra
An XML format from the FIX Trading Community, FIX Orchestra is noticeably more comprehensive than QuickFIX, as the above screenshot demonstrates.
Not only can we immediately see that it is capable of capturing human-readable descriptions (of different “types” in fact) , but there are a lot of additional nodes which are related to metadata around the API. FIX Orchestra is capable of letting API owners express workflow; how API users are expected to construct inbound messages, and what they should expect to receive back under certain scenarios.
These two improvements (over QuickFIX) are very important as they combine to open the door to many of the OpenAPI benefits above; the ability to auto-generate documentation, mocks and automated tests.
The schema itself has been through a series of release candidates before being released as a “standard” by the FIX Trading Community in February 2020. There is a dedicated FIX Orchestra working group within the FIX Trading Community, that members of the organization can join if they wish to learn more about the standards or contribute to it’s future development.
FinSpec
FinSpec is an open-source JSON format which is open-sourced and supported by FixSpec.
As the example above demonstrates, descriptive information can be captured for both messages and fields. This could be simple text strings or rich HTML as shown here. (Unfortunately, HTML and XML don’t typically “play well” together, which is why FIX Orchestra leans towards Markdown in order to provide rich text formatting).
Just like FIX Orchestra, FinSpec also supports workflow definitions that can be the basis for future mocking, emulation and test-case generation.
One thing that FinSpec v4.0 has that neither of the other two formats offer, however, is a new content element. This is designed to be a large HTML string which can blend free text with reference markers to messages and component blocks described elsewhere in the FinSpec.
What does that mean, an why is it needed? Well, imagine the documentation that you could produce without this element. You would have a collection of messages and fields which are themselves described quite well, but the author would have quite limited ability to set the order in which those sections appear, and there would also be none of the descriptive text which “glues” various sections together to make it appropriate for human readers. This is the function that the content element serves, and which allows us render a FinSpec document into something that really does look and feel like a PDF-style reading experience for the users, while retaining all of the structured, machine-readable sections.
Final Thoughts
My purpose in this piece is not to argue the technical functions or benefits of one format or another, as we are far more likely to see multiple formats flourish in the early days before the industry coalesce around one.
No — the primary purpose of this piece is to help those people interested in the future of FIX documentation and tooling to understand the options that are out there, and to start a conversation about how to move beyond PDF.
What is clear, however, is that to unlock the full potential of this brave new world, there is a lot of work to do. In particular, moving to digital documentation doesn’t just mean putting it on a web page instead of in a PDF. It means structuring and organizing API data in a way that makes it machine readable and thereby unlocks dramatically more efficient and automated tooling.
But this step change requires effort; effort that a lot of firms have been reluctant to invest to date. Until there is traction in digital documentation (of any schema), our niche will remain stuck in a rut. Each firm will be destined to re-invent the wheel again and again and again, burning our precious development capacity building internal, non-differentiating, unsupported FIX “tools” to solve today’s internal pain without any thought to improving the process in the long term.
As an industry we will only move out of this (collective) rut if we solve the chicken-and-egg problem that plagues FIX connectivity today. That requires us to resist the temptation to do it manually “just this one time” and start thinking strategically.
OpenAPI has clearly demonstrated that an automated, efficient future is possible, but that it starts with digital documentation. The question is whether we — as an industry — are ready to adopt it.
Want to learn more about FIX from experienced tutors in a small, online, interactive group? Check out our training at https://fixspec.com/training.
