A road map is essential for managing the change of any individual API. A road map communicates change with API consumers, but it also just grounds API producers regarding what is planned for the future. A road map balanced with a change log will keep us honest as API producers, showing where we fall short regarding what our priorities are and how they change over time.
API road maps don’t have to be complicated, just a date, title, description, and maybe a version reference. Keep the title and descriptions short and easy to read, explaining what is being planned to the best of your ability. Road maps can always be refined over time as things come into better focus and the impact of shifting priorities becomes more evident.
Rod maps will change (pun intended), and we can only predict so far out into the future, but we should try to make sure everything we end up changing began on the road map, with as much lead time for consumers and the rest of the team producing APIs as possible. The quality, honesty, and transparency of a road map, combined with the same present in a change log will become the tracks needed to move everyone forward in the same direction.