---
seo:
  title: "Digital API Docs"
  description: "Why trading platforms should replace legacy PDF FIX specifications with machine-readable API documentation."
llm_context: "Opinion and background piece arguing that PDF-based FIX documentation is no longer sustainable, contrasting it with the OpenAPI ecosystem and the AI-driven shift to machine-readable specs."
category: "concept"
related:
  - "/finspec"
  - "/portal"
  - "/platform/concepts/doc_library"
---

## Digital API Documentation

### The World Has Changed

If you are a trading or market data platform, the vast majority (possibly all!) of your customer order flow comes through an API. Perhaps it is FIX. Or maybe REST. Even where a customer is trading using your own UI, their orders are likely still coming through an API of sorts.

So now we've established that almost all trading firms are API businesses, the next question is how they explain their APIs to customers, vendors and partners.

In the (broad) world of REST APIs, the answer is [OpenAPI](#openapi-for-rest) - an open-source format with a rich, mature and expanding ecosystem that covers everything from automated mocking to code generation and documentation portal generation.

In the world of FIX APIs, however, the "answer" is PDF. Long, outdated, and - I'm sorry - _boring_ PDFs. Platforms produce them because "everybody else does", and Word/PDF is no-cost. Customers skim-read them (at best) and instead develop by failure. No wonder onboarding remains labour-intensive, error-prone and **slow**. PDFs are hard to reliably parse (even with AI) and so the ecosystem around them is almost non-existent.

FixSpec was established in 2012 with the core vision that the status quo is no longer credible or sustainable and must be replaced. The widespread adoption of AI from 2023 makes the move more urgent than ever as development increasingly moves to AI instead of humans.

:::info Important!
We are **NOT** advocating that FIX - the protocol - should be replaced.

We **ARE** suggesting that the PDFs we use to describe FIX needs to die.
:::

### OpenAPI for REST

There are many other resources which give excellent overviews of REST and OpenAPI principles, and so we will not repeat them here but instead refer you elsewhere.

1. [MDN Web Docs](https://developer.mozilla.org/) explains the foundation-level mechanics REST APIs, including HTTP methods, headers, status codes, and request-response cycles.

2. [Microsoft RESTful API Design Guide](https://learn.microsoft.com/en-us/azure/architecture/best-practices/api-design) describes various enterprise-grade architectural patterns for resource naming, error handling, versioning, and filtering REST APIs.

3. [Swagger OpenAPI Guide](https://swagger.io/docs/specification/about/) introduces the core principles of the OpenAPI format.

4. [APIs You Won't Hate](https://apisyouwonthate.com/) is a great resource to learn practical, design-first workflows, integrating OpenAPI schemas into development pipelines, and avoiding common API design pitfalls.

### FinSpec for FIX

FinSpec is an open-source format from FixSpec that aims to cover the core documentation requirements for both human and - increasingly - AI readers, as well as providing a foundation for a future software ecosystem. FinSpec is open-sourced under the permissive Apache 2.0 licence.

Other candidate formats exist (see the [frequently asked questions](#frequently-asked-questions)), but we believe that FinSpec is currently the best choice for machine-readable FIX APIs. [Extensive documentation](/finspec) can be found on this portal.

### The Project Ahead

We won't sugarcoat it - the move from a legacy, Word-and-PDF document mindset to a proper developer portal is a big project that requires wide buy-in. **The advantages, however, are worth the effort.**

:::stepper
::step[STEP 1 (TODAY)][Current World][#64748b]
**Manual editing across Word documents**

- Hand-maintained Word files
- Exported to PDF
- Emailed / posted as downloads

_Customer sees: a static PDF download_
::
::step[STEP 2][Digitisation][#3b62d6]
**1:1 conversion into machine-readable specs**

- One-to-one content conversion
- New editing tool to learn
- Basic site, optional login

_Customer sees: same document versions, now online_
::
::step[STEP 3][Governance][#12806b]
**Consistency and re-use enforced**

- Split into re-usable chunks
- Duplication removed
- Re-assembled, governed

_Customer sees: more accurate, consistent; same versioning_
::
::step[STEP 4][Portal re-organisation][#c17a2e]
**Restructured for a linked, self-service portal**

- Organised around navigation, not documents
- Tutorials, quick-start guides added
- Duplication fully eliminated

_Customer sees: free browsing and search; versioning is API-only_  
::
:::

The project starts with a pure digitisation step; migrating from your existing Word documents into a combination of machine-readable specifications and rich Markdown for informational sections. Instead of downloading a PDF from your website and reading it on the screen, they now view the same content on a website.

:::info Optional Authentication
It is at this point some people start worrying about "security" of putting data online (despite the fact that a downloaded/emailed PDF can - of course - be freely forwarded to whoever the recipient wants!)

Simple website authentication solves this problem immediately, and short-lived access links guarantee that customer contacts can't take your spec with them when they change job.  
:::

Once the initial conversion is complete and your customers can self-serve your existing material, we now introduce a governance layer. This phase can be hard, as you iteratively unwind a (potentially large) pile of accumulated documentation debt, improving consistency and removing duplication, but this is the foundational work to put your docs on a strong foundation. As accuracy and consistency rise, you should start to see faster onboards and fewer support calls.

In the final step, we dissolve the historic, siloed thinking that PDF documentation creates, reorganising content into a single, well-structured developer portal that lets users self-serve documentation in the most natural way for them. By choosing an AI-accessible portal, your documentation is now readable by both human and AI developers.

We'd all like to snap our fingers and jump straight to the end step in one leap. Unfortunately, there's no short-cut - it takes time and effort. But each step delivers value on its own, so you don't need to wait for the whole journey to see a benefit.

### Frequently Asked Questions

:::faqs
::faq[Why not use QuickFIX for FIX?]{#faq_digital_docs_quickfix}
The [QuickFIX engine](https://quickfixengine.org/) uses an XML dictionary for validation. This XML can also be used generate boilerplate code in some languages, but the extent to which this is used is unclear. The engine's popularity means that many platforms will supply a QuickFIX XML on request.

The XML is, unfortunately, unsuitable for delivering the full vision here - it was never designed for this purpose.

Not only is the format not formally documented, it is also deliberately sparse - it lists messages and fields, but can not even accommodate descriptive text, let alone model the complex conditionality that is the hallmark of trading platforms.
::
::faq[Why not use FIX Orchestra for FIX?]{#faq_digital_docs_orchestra}
[FIX Orchestra](https://fixtrading.org/standards/orchestra/) is an XML standard from the FIX Trading community which aims to provide a machine-readable format for FIX specifications. It shares many of the same objectives and covers the same core functions as FinSpec.

Real-world adoption of FIX Orchestra remains low, and the limited tooling that exists is often commercial or tied to FIX Community membership. **To be fair, the exact same criticisms currently also apply to FinSpec**. By open-sourcing FinSpec under the Apache 2.0 licence, and providing extensive documentation, FixSpec hopes to encourage FinSpec experimentation and adoption.
::
::faq[Why not use FIX Simple Binary Encoding (SBE)?]{#faq_digital_docs_sbe}
[Simple Binary Encoding](https://github.com/FIXTradingCommunity/fix-simple-binary-encoding) is a high-performance, binary format originally developed by RealLogic (now part of Adaptiv), and later donated to the FIX Trading Community.

The idea and tooling behind SBE is genuinely good, but it isn't an "upgrade" from FIX - it's actually a complete re-write. So if you want to offer a binary API (particularly for market data), then SBE is a solid choice. We can't use it, however, to document existing FIX connections.
::
::faq[Why not have a fully multi-protocol format?]{#faq_digital_docs_multi_protocol}
It's appealing to think that there may be some magical one-size-fits-all format that would work for all protocols found in financial service, but the reality is that each protocol is so different, a single format would quickly become a Frankenstein's monster. We believe it is much more practical to re-use what already exists (e.g. OpenAPI), and only backfill the gaps (e.g. FinSpec for FIX), allowing you - the user - to benefit from existing ecosystems wherever possible.  
::
::faq[Where do I find open-source portal software that can I use?]{#faq_digital_docs_portal}
There are a number of open source and commercial portal software options that you can investigate if that's the route you wish to take. Examples include [Docusaurus](https://docusaurus.io/), [readme](https://readme.com/), [Redocly](https://redocly.com/) or even [Github Pages](https://docs.github.com/en/pages).

FixSpec also offers turn-key [portal](/portal) software, built specifically for the domain of trading APIs, and is currently the only such service that offers FIX Protocol support.
::
:::
