A change log for an API is a proven way for communicating change between API producer and consumer. A change log doesn’t have to robust, just a date, title, and description of what changed, with a possible reference to the version. A change is there to help both API producer and consumer understand how we got to where we are at with each individual APIs.
Change logs should exist for individual APIs, but can also be available for the overall API operation, or a specific domain within a larger API operation. Change log done well can become a simple historical accounting of what has happened over time, providing more context to any given moment in time. A change log can help ground decisions and keep us from be too reactionary in any given moment.
I can’t express the importance of a change log when it comes to grounding the delivery of APIs, giving both API producers and consumers more confidence. The process of documenting change using a change log, communicating with stakeholders, and making it available in a self-service way has profound effects on the reliability of our APIs–using a simple and effective formula for logging change.