Maintaining and documenting API endpoints of many applications in a microservice architecture

Question

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?

Answer 1

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.}

Answer 2

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.