In this modern world we live in, this ever-connected and ever-integrated digital world - wouldn’t it be great if there was a tidy, cohesive and easy to understand way of getting systems to work with each other and at the same time, be easy to understand.

Since the early days of computing, since the 1940’s, there have been ways of defining the way a programmer should integrate with a module of code, thereby defining a tidy, cohesive and easy to understand way of working with a system. At the time these were called Application Programmer Interfaces, but the name has - over time - been changed to mean Application Programming Interfaces or APIs.

The wheel: re-invented, but for good reasons…

Domino’s UK & ROI (DPG) have had a highly successful, robust, flexible and relatively well understood eComm system for some time. It has been working well, it has had many changes made to it throughout the years and whilst it may not be all that shiny and (from a technological perspective only) sexy - it has served Domino’s well and enabled some really important, valuable and impressive features to be added to benefit our customers.

That being said, all good things must come to an end.

Now, it is at this point where one could berate the legacy systems for being clunky, slow, technological antiques and many other terms… but that’s not the right thing to do, nor is it appropriate.

What would be is better is to learn from the legacy system to ensure its successor is better - and better in appropriate ways; not just to use cool tech because it is what “the cool kids” are using.

At the start of 2021 a major program of work was started to replace the bulk of the legacy eComm systems with something fresh, something using new tools and technologies, to allow new requirements to be added quicker, safer, more reliably and to make the technology accessible to anyone (the definition here of anyone is not necessarily the same as you are thinking - it is anyone who needs to access it that is outside of the codebase itself, so mostly internal systems rather than anyone out there in the world)

There’s a well known (and well used) description of the work, and it’s one that has been muttered by many companies around the world who are also undertaking a major platform transformation project…

Replacing the wings of the plane whilst it’s still in flight

Where we were, where we’re going to be

A blog post about technology, transformation and re-platforming just wouldn’t be right without a few diagrams and pictures - and this one is no different.

Where we were

The below diagram represents a very simplified view of the eComm estate before the transformation project started

If you’re familiar with this kind of architecture, it’ll be nothing new - a monolithic system designed and evolved over many years but as with all such designs, it has limits and there becomes a point whereby the cost (in terms of time and effort) of adding new capabilities versus maintaining the code makes it un-viable.

This challenge is nothing specific to Domino’s, it’s the same problem that many many companies have when working with a legacy monolithic system.

Along comes the new

From a high level architectural perspective, it is nothing more than introducing a scalable microservice architecture; using the power of the cloud, BFF’s, containers, container orchestration, service-mesh, eventing and modern coding techniques (and many others too).

From a Domino's perspective however this is huge! This transformation will allow a great deal of future innovation to be possible.

Let’s talk…

Having a new - microservice driven - platform needs to work in a particular way; there’s no value in all of the code living in its respective service boundary if there’s no way of understanding how any other system can interact with it and this is where API’s come into the picture.

Each micro service is built up of one or more “endpoints” - this is nothing more than a place in the microservice that can be talked to. (Clearly the language used in the previous sentence is incorrect when talking about system-to-system interaction but it gets the message across)

Consider the following example:

A customer visits the Domino’s website and wants to find their nearest store to see when it opens.
The micro service would be “store” as it pertains to activities and actions related to a store
The endpoint would be “store search” as it allows the customer to talk to it in order to answer a question.

Having the endpoint is great, essential really but, there needs to be a consistent, common and easy to understand suite of documentation to support this, otherwise how would anyone ever be able to know how to talk to it.

Walking the new path with a degree of swagger

Every developers least favourite task is authoring or maintaining documentation - it’s often “no fun” and it gets in the way of them creating beautifully written and well tested code.

There are two important words in the previous sentence that need to be clarified and expanded on - that are highly relevant to this post too…

“written” and “tested”

How do the developers know what to write? How do they know what to test? How do the test team know what their test-cases should execute to ensure that the new code “does what it is supposed to do”?

Documentation!

Before code is written, there needs to be an understanding of what the new endpoint needs to accept and what it needs to return - these are the contracts for the API.

With this simple set of documentation the whole development process can commence - developers can write their code, testers can write their tests with a common and consistent understanding of what to expect.

There’s a bonus here too - self generating documentation!

Okay, so it’s not truly self generating, it has to have the code written first to allow the documentation to be generated against.

Standard API specifications exist such as the OPENAPI specification which can interrogate the code (at compile time) and present standard documentation which can be used to “understand” how to talk to the API.

It’s all well and good having this documentation - indeed, it is invaluable - but there is a down-side; one that could lead to problems.

Suppose your well written, full documentation is available on the public internet, this could lead to major data problems with potential bad actors exploiting the APIs, obviously not a position any company wants to be in. Because of this, more often than not this complete documentation is disabled for production access and only accessible to internal systems on pre-release code.

Great! So close!

All is not lost - there just needs to be another set of documentation, one that can be shared publicly.

What, more documentation?

Yep, that’s right, another set of documentation is needed but this needs to be crafted to cater for a different type of audience, an audience that could be anyone and not just people from the development sphere.

This documentation needs to have textual descriptions, samples, generated sample code, be easily shared, have the ability to be executed in isolation, secure and up-to-date.

Making sure it’s baked to perfection

To address the wider documentation and associated points defined above, Domino’s looked to see what tools are already out there to aid in this - it didn’t take much looking to find the ideal candidate. Not only is this tool well known and highly regarded but, it’s already in use (to some degree) within the Domino’s development teams.

A letter, delivered by a specialist

The tool of choice was Postman (take a look at their website for the full info on what it can do as it’s extensive) as it met all of the immediate needs of the program, offered some easy wins and would allow the teams to become better organised and efficient with their delivery.

Getting the ingredients together, the right way and getting them cooking

An initial proof of concept was completed to ensure that not only is it the right tool but, it can work in a way that is right for Domino’s (it’s all well and good picking the best tool out there but it has to work with the internal teams and processes rather than against it). This was a resounding success and demonstrated not only how simple the tool is to use, but also how it can form a key part of the SDLC and deliver quality improvements across the whole of the re-platforming.

Some of the obvious and immediate benefits were things about defining API endpoints in Postman, adding human readable documentation, sample request and responses, immediate publishing of externally visible documentation for 3rd parties to consume, test-cases and test executions on the APIs deemed externally visible, compliance analysis automatically executed on each change and a big benefit was realised on collaboration - each member of the development, quality and architecture team had immediate access to the same suite of Postman specs without the need to share anything over email/Teams/Slack etc.

Letting others come to the party

The newly created APIs, the internal documentation and the externally visible documentation have allowed Domino’s to - with comparable ease and swiftness - complete an ambitious integration with a very well known Online Food ordering service called Just Eat. The elegance and completeness of the external Postman documentation alleviated so many traditional pain points of having to share PDF documentation, sample request and response payloads for myriad use-cases and, in the event a change is needed having to re-send them again - to many people whilst trying to ensure everyone has the same latest version.

The integration was so successful that the exact same process is being used to bring on another very well known food ordering service - Uber Eats - and the Postman documentation is proving to be invaluable for this engagement too.

The new APIs, the public and private documentation, the constant API level testing and the enhanced collaboration are huge wins for Domino’s and are leading the way for future innovations within the company and working with other 3rd parties.

Putting it in the box and sending it to our fantastic customers

It’s an exciting time to be working at, with and for Domino’s; the re-platforming, the engagement with 3rd parties and the technological opportunities made available as a result of these are going to be compelling - for the teams working here, for the franchisees and - of course - for our fantastic customers.

For the time being then, this (rather long) post can come to an end but the journey is only just beginning.

See you on the API side!

Peace!