As a provider of HTTP(S) APIs, we are acutely of aware of maintaining backward compatibility for our integrations. An API, by definition Application Programming Interface, is a contact point between Nearmap and our customer's application. Any changes to the interface, even if they are fixes or improvements, may result in that application not being able to load Nearmap content. As such, we are focused on ensuring that our published APIs continue to work as expected. We run in excess of 5,000 automated checks daily, in addition to manual regression tests, to ensure that new developments do not break compatibility.
I find the topic of backward compatibility and unintended consequences of undocumented usage fascinating. This is pretty much a full time job for the API team at Nearmap. Many tech companies do the same, and you can find the best examples from Microsoft, especially by Raymond Chan. In the early days of Windows, Microsoft went to extraordinary lengths to maintain compatibility. Here’s an interesting story from Joel Spolsky, formerly of Microsoft. You may know Joel these days from StackOverflow, Trello, and the most incredible Excel training video.
According to Spolsky, “I first heard about this from one of the developers of the hit game SimCity, who told me that there was a critical bug in his application: it used memory right after freeing it, a major no-no that happened to work OK on DOS but would not work under Windows where memory that is freed is likely to be snatched up by another running application right away. The testers on the Windows team were going through various popular applications, testing them to make sure they worked OK, but SimCity kept crashing. They reported this to the Windows developers, who disassembled SimCity, stepped through it in a debugger, found the bug, and added special code that checked if SimCity was running, and if it did, ran the memory allocator in a special mode in which you could still use memory after freeing it.”
Whilst our backward compatibility efforts pale in comparison to the above SimCity example, we analyse seemingly innocuous changes for potential impacts to customer applications for every release. One of the more interesting fixes we implemented was allowing “wrapping” of tile x/y coordinates on our legacy API as we detected that some customers relied on this undocumented behaviour.
So, we maintain backward compatibility for existing APIs, but what if we want to introduce breaking changes because the existing APIs are suboptimal?
A breaking change, in our case, is a modification to the API that requires applications to make a corresponding change to continue working. An example of such a change would be changing the TMS endpoint from au0.nearmap.com to autiles0.nearmap.com and turning off the original endpoint. If we were to do this, hundreds, if not thousands, of applications would stop working overnight.
In order to avoid this kind of disruption, we are releasing the new API and running the old API in parallel. This allows new customers to start using the new API, and gives us time to transition existing customers onto the new API. As you can see from the documentation, the now-legacy API is still supported, with a note that it's now deprecated. We will publish a deprecation schedule early in 2019 and will kick off migration activities then.
The next post in this series will talk about the features we made available in the new version of the Tile API, and how you can use those to improve your application.
Igor Zevaka is the product manager for Nearmap’s content APIs. With a degree in software engineering from UTS, Igor creates new APIs to support emerging location content products. He is passionate about discovering new customer use cases to create fresh ways of accessing location content with Nearmap’s API suite. Feel free to drop Igor a line: email@example.com.