I think one of the biggest pain points in working with microservices is making sure that the APIs are well-documented and APIs do not change their behavior without affecting downstream applications. This problem becomes amplified when you have many services that are interdependent on each other. Perhaps at that point you doing microservices wrong, but I digress.

Let's say we have inherited 20 microservices that are owned by different teams and there is no clear documentation about which application uses which other application's API endpoint. Is there a prescribed way of documenting this? At first I thought of analyzing each application's endpoints and adding them to a database table, then creating FK relationship among each application and an application's route on a many-to-many table (almost all of these are rails apps). But I am not sure if this is a good way to handle this, or am I re-inventing the wheel here.

In retrospect, this might be a not so bad way to document application interaction if you are starting with microservices from scratch. This would just enforce that a single source of truth is maintained via the use of a database and any changes to the endpoints would be performed in the application in conjunction with the change in database. Thoughts?

2 Answers 2


A large part of the benefit of a "microservice architecture" is that you aren't documenting all of those relationships. Each service is its own product. And each service owner is responsible for the operation of their service as an independent product. That can include things like:

  • Publishing "marketing" docs, user docs, and change logs (including deprecations)
  • Provide a way for customers/consumers to request features / report bugs
  • Maintaining an SLA
  • Making updates as backward-compatible as possible and breaking changes
  • Knowing and watching news feeds for services they consume directly
  • Pruning dependencies when possible
  • Deprecating the entire service when it becomes irrelevant or too costly to maintain

And so on.

Above all, I'd stress, as one of the core benefits of a microservice, the opportunity for service owners to really focus on and specialize on the "one thing" their service does.

As to where each product or service owner should document their own dependencies -- that should happen "naturally" as they're added to your compiler's configuration (or build script). If you need to know what ServiceA depends on, ServiceA/Configuration.xml (or whatever) will tell you. I'd also normally expect each service owner to initially diagram their own immediate dependencies -- but not dependencies of dependencies and so on. And, given the information is already in code, I wouldn't necessarily expect those diagrams to be maintained going forward.

If you really want a global picture, scan the configs/build scripts. What you do with that output, how you store it and so on, depends entirely on what decisions the data will help you make.

  • I think this is a good way to attack the problem if you are starting off with building with microservices, but for existing setup I am planning on parsing apache logs to get some usage information and document those, as well as have a meeting with the application owners.
    – hyde
    Jan 25, 2018 at 19:55
  • @hyde Are you in a position where you can reasonably demand that the service owners each justify the existence of their service? (Supported with metrics and log data?) Or, are you the service owner? ... Do you have a centralized repository of repositories you can search those app configs for service references?
    – svidgen
    Jan 25, 2018 at 20:14
  • No, I am not in a position to change the way these applications are set up at this time, which I think is what you were implying by asking the service owners to justify their existence. ;) I was lucky to stumble upon JSON files in our production servers that list services and the URLs they use to reach those. While this does not provide a complete picture of the setup, I think it's a good starting point.
    – hyde
    Feb 2, 2018 at 2:52
  • Umm. Not really what I was implying. But, I worded my comment very poorly ... basically, if each service owner is responsibly doing the things I listed above, each owner should be able to tell you where their service fits in and what its dependencies are (or whether it's even being used).
    – svidgen
    Feb 2, 2018 at 2:57
  • ... Beyond that, at the particularly large company for which I currently work, the service interactions are so complicated that it cannot be fully diagrammed. And that's OK. Each owner knows their service's dependencies and makes promises to their consumers in the combination of promising backwards compatibility (usually), mailing lists for the exceptions, and SLA's.
    – svidgen
    Feb 2, 2018 at 2:59

I think a good idea is create a diagram of integrations and include this in your repository. Choose some free tool (like draw.io) that can export the diagram in a XML or JSON file and commit this file in your repository. If you use Github or Gitlab, generate the image from this diagram and include in the Wiki or even in the README.md file, so the image will be visible every time the developer visualize the repository from the browser.

The same strategy can be used for the database.

About the API resource documentation, Swagger is a good option.

This problem becomes amplified when you have many services that are interdependent on each other. Perhaps at that point you doing microservices wrong, but I digress.

This is a problem, for sure.

  • 2
    There are other alternatives, but it's worth keeping an eye on what API testing environments (like PostMan) support. RAML is another option in the same space. The same description JSON can generate HTML API docs and be used to describe your service to others. I.e. you can use it to generate web bindings. (both Swagger and RAML support this). Jan 23, 2018 at 19:39

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.