How To Build A Global FIX Spec

The latter has been the strategy of choice for large trading firms over the past decade, with M&A continuing to increase year on year. This expansion drive frequently results in a sprawling set of siloed trading services, APIs and systems, often spread across the world. Post-acquisition integration often takes several years, with pressure to realise the economic synergies of the deal and clean architecture falls down the pecking order. This often leads to an internal “spaghetti mess” of systems and increasing levels of inefficiency and technical debt. We frequently hear stories of similar trading services remaining so siloed post-acquisition that they barely talk.

Eventually, talk turns to efficiency, consistency, consolidation and the creation of a company-wide, “global spec”.

The benefits of this are obvious. Not only does it simplify the technology, reduce the overhead of managing multiple documents and improve brand consistency, it can also simplify the technical ability to cross-sell your services to existing customers. are more than likely also a customer of one of your other trading services. A global spec or a consolidated connectivity process creates a better, more efficient customer experience.

But how do you get there? Where do you start?

We’ve had several new customer conversations recently about how best to achieve this without disrupting (too much) legacy technology, and to ensure business continuity during a migration. Since the “stop the world while we re-engineer everything” approach is almost 100% guaranteed to fail, this has to be a multi-phase process of analysis and implementation… one that starts with a clear (yet flexible) roadmap. Critically, since BAU always takes priority, the plan needs to consider long-term maintenance and even the ability to pause and restart as priorities shift.

FixSpec labs was engaged in such a project for a large bank, and so here are the steps we proposed for the consolidation of several trading APIs.

Step 1: Collect What You’ve Got

The first step is to audit and collect everything you have from across the firm. How many specifications do you have? Where are the originals? How up to date are they? Who maintains them?

This can be a significant job; our client had over 40 FIX specifications with different internal brands and templates, and also a range of other explainer documents and workflow diagrams. This detail was collected on an internal wiki page.

The next step within this phase is to get buy-in for change from key stakeholders. A global spec is no small undertaking; it takes time, it means new tools and processes, and there is no quick or easy way to “unwind” it later. Speak now or forever hold your peace!

Step 2: Centralise and Digitise

Ever tried comparing 40 different Word documents? It’s not pretty, and is an obvious reason for a project to stop dead in its tracks. A better way (we think) is to import them into a tool such as FixSpec’s SpecServer. Even though you — as an end user — don’t see it, the act of loading your existing documents into an editing tool means that the data is organised and structured under the covers, and therefore becomes comparable. The visible outputs — PDF documents — can remain untouched at this point (although the content is generated from the tool).

The introduction of specialised software at this step is critical to the success of a consolidation project; moving from the manual maintenance of Word documents to using a consistent tool is what allows comparison to take place, while running in parallel to business-as-usual. If a business needs to make a change to its API, then that’s no problem — make the edit in the tool, regenerate your PDF, and that change is automatically visible to the consolidation project going forward.

Such a tool delivers a host of other immediate benefits too, including:

• acting as a central location for your specs (no more files locked by someone’s PC),
• internal teams can collaborate to edit specifications (no single-threading),
• clear version control (no more sales handing out the wrong version),
• automatic generation of machine-readable formats such as Quickfix and FIX Orchestra (no more manual maintenance), and
• role-based user permissions and a clear audit trail of edits

With this solid foundation established, it’s time to start iterating towards a global spec.

Step 3: (Iterate Towards) A Global Spec

FIX documentation held in a digital form within the SpecServer software can be organised and compared easily, with identified differences either accepted or eliminated, thus evolving towards a consistent, global spec.

We often hear firms looking to build a global spec describe some sort of “master document” that will somehow be handed out to customers and supply all of the answers they need. In our experience, however, this should not be the goal to aim for; at FixSpec we often rile against very long PDF documents, as we believe nobody reads them, and so the idea of an even larger “master” document fills us with dread.

Instead, we encourage firms to think about building their own (internal) version of the FIX protocol. One that represents the superset of all messages, components, fields and enumerations used across their API estate (including custom ones), but which doesn’t include the pieces of the FIX standards that you don’t use.

Creating and curating this central dictionary is the key to achieving centralised consistency across your documents, which then draw from this central repository. The repository may grow over time of course, and it may also be the case that individual specs naturally vary from this global dictionary either temporarily or permanently. This is entirely normal; the software should be there to help you identify and manage differences over time as opposed to imposing rigid structure.

Of course, FixSpec’s SpecServer software automates the creation of such repositories and offers advanced tools around identifying and eliminating differences, and so centralised management becomes a breeze. One of the largest market data vendors in the world has successfully used this approach for many years to align globally-distributed teams of business analysts maintaining hundreds of specifications against a centrally-managed dictionary. It is truly impressive to see this structure work at scale.

Step 4: Product, Customer & Functional Selection

Hopefully, you have understood from the previous step that we are advocating the creation of an internal spec or repository as opposed to an external spec for customers. We still see significant benefits in producing a series of product- or service-specific documentations as opposed to cramming multiple products into a single document, as it leads to much cleaner (and slimmer) documents that give your customers the best chance to understand your interfaces.

As a result of completing steps 1–3 above, a strategy for document-level re-organisation may emerge. For example, you may decide to create a single, common FIX session-layer document and remove this from all other documents. There is no right answer here; a documentation approach that might work for a large investment bank may not work for a small cryptocurrency exchange for example, and this is an area we can offer a view on.

But the segmentation of interface documentation does not only run along product lines, and this is an area where FixSpec’s software has a couple of other tricks up its (virtual) sleeve. Our background in conformance means that we think in terms of both “capabilities” (a collection of workflows that together represent a meaningful business activity), and “functional views” (presentation of a technical message within a given business context).

These are advanced functions and so the detail of these concepts is beyond the scope of this article; for now you can think of them as intelligent filters on top of standard FIX documentation to really refine what the end reader sees and make it hyper-relevant to their use case. The clearer and more relevant documentation, the easier and faster they should find it to connect to your API.

Imagine a world where your customers can self-select what functionality they want to conform to and then be presented with a customer-specific spec based on their selection. Not the full PDF that is sent out today. The system can build up a customer’s spec based on what they select using the pick and mix function; they see only what they need to see. This flexibility necessarily requires a shift away from static PDFs, however, and so can only be achieved with dynamic customer portals — a bigger strategic question — which results in a far more efficient and user-friendly developer experience that can be used as a springboard for further automation.

—