API API Lifecycle Specifications FinSpec Onboarding
It's been a few weeks since our trip to India, and so the time has come to share a little bit more about what we built - an idea we've called Mocky.
The first thing to explain about Mocky is that I view it as a "concept car" of FIX software. This is not something we are selling right now (but we may in the future), and while it may seem in some ways familiar, it is actually quite different... So what is it?
Mocky is an application that lets you send a FIX message to a spec and receive one or more responses that are both realistic and can be influenced.
That's a simulator, right? Well, not really... Read the sentence again carefully and two concepts begin to stand out. The first is that I say that your message is sent to a spec and not an app, and the second is that the sender gets to influence the result.
You see, Mocky addresses three of the biggest pain points we see with simulators today:
the need to re-script your simulator to match your system every time you do a release,
users shouldn't need to explicitly code responses in all cases, there should be a base level of automatic behaviour built-in, and
in the cases where the user does want a specific outcome, then it should be easy to achieve that (anybody who "hits themselves" in an order book understands what this means).
I'll explain more about the approach to Mocky in later posts, but the key point to take away from today is that Mocky is NOT a simulator like you've known them before and that it is driven 100% from the spec. No additional scripting.
When I refer to your "spec", I don't mean that dusty Word document you have lying around - that's useless. I mean an electronic spec in the open-source FinSpec (JSON) format. And that is the core reason we embarked on Mocky; because we needed to know what it would take to offer a schema that was comprehensive enough to fully capture an API, and practical enough to be used to build a mocking environment. For us, this is part of the DNA of FinSpec and speaks to how we are developing it. FinSpec isn't borne out of endless conference calls with a churning participant list who are only half-listening, FinSpec is an open-source project with a clear end vision, being led by a firm incentivised to build radical yet practical solutions to the problems we see.
At this point, you may think "OK, so I like the no scripting part, but I still need to write to your JSON format and so there's still work to do". And you would be right. While our SpecServer product makes the job of creating and maintaining FinSpec documents a breeze (and converting them to other common formats of course), the hardest part of moving to electronic formats like FinSpec is the need to add a load more detail to your specifications than perhaps you document today. And while that seems like a daunting task, the fact is that they are actually the exact-same questions your customers ask during their onboarding, including:
how are identifiers allocated and used to link messages?
which attributes will I receive on a response messages?
if I try to cancel an order do I get a pending cancel message before a cancel confirmation?
For me, this is the biggest lesson from our time in India - unless firms begin documenting their workflow, then we don't raise the quality and usability of API documentation. And if we don't raise the quality and usability of API documentation, then we will never escape the inefficiency of the current process.
The challenge for evangelists such as FixSpec is to show people what this new world means and to make it as painless as possible to move to it. Now we know the end state, our efforts pivot to reducing the effort associated with adoption.
I started out by describing Mocky as a "concept car". Perhaps the most interesting thing to focus on here is not the app itself, but rather the future that it opens up - an API lifecycle that is radically different from the one we experience today:
a shared artefact (the FinSpec) that delivers value to development, QA, onboarding and your customers, avoiding misunderstanding and duplication of documentation.
the possibility of "spec-driven" development where the first thing to be written is the spec (as opposed to it being an after-thought), meaning more consistency, less risk of error and less re-work.
the ability to spin up an interactive mock of an API without a developer writing a single line of code, allowing stakeholders to have a conversation about - and pro-actively design - API changes before spending precious time and resources building it.
continued availability of an early environment to allow QA to build test cases against that is independent of the API under test, thus avoiding the trap of brittle QA tests that merely "lock in" behaviour of a delivered API and allowing a greater focus on edge-case testing.
In later posts, I'll talk more about these - and many other - benefits of both Mocky and other tooling in the pipeline, but in the meantime, you should know that the future is bright for those willing to embrace it.
Watch this space!