At WQA, especially for Enterprise, we are often building projects that sit on an already existing system or back end. That begs the question, what's the best way for our engineers to work with customers and their architecture?

Having done multiple projects with dependencies on a systems provided by our customers or a third party, we have gained some valuable insights on how to collaborate in the most efficient way possible, while keeping a healthy relationship between all parties.

A single place of truth

What we mean by a single place of truth is a document that describes the service that everybody has access to and is always up to date. It should be easy to interpret, while not leaving out any important information. Nothing is worse then knowing a piece of documentation exists, but not finding it.

This single source of truth should at least describe the following topics so all teams can stay aligned: The current state of the API, and the state of the API after the changes. The tool we like to use for this is called Swagger; it allows us to create a visual representation of an API.

For less technical people, it gives you a quick overview of what does and doesn't exists (yet). Developers can dive into the details of each endpoint and analyse what parameters to provide to receive the expected data from the back end. Thanks to this hub, there is much less back and forth between teams, giving us a net gain in overall productivity.