Question Details

No question body available.

Tags

design architecture api uml use-case

Answers (2)

March 25, 2026 Score: 2 Rep: 86,026 Quality: Medium Completeness: 50%

If you represent them on a UML Use Case Diagram, then each external service would be a separate actor. In UML, an Actor represents "a role played by a user or any other system that interacts" with the system of interest. Since the roles of OpenStreetMap and Geoapify are different, they would be distinct actors.

However, there are some considerations.

First, when working with UML Use Case Diagrams, I always point out that there is often little value in them, making their creation (and ongoing maintenance) more costly than the value they add. This echoes sentiments also expressed by Martin Fowler. There is far more value in textual or tabular representations of the use cases that offer details on the goals, triggers, pre- and post-conditions, and scenarios.

Second, just because the actors exist in the system doesn't mean that you need to express them on a UML Use Case Diagram. Unless the external system is executing a use case as a primary actor, including supporting actors on a Use Case Diagram can increase the complexity and make it harder to read. These integrations with external systems and services would likely be shown on other diagrams, such as Component Diagrams, Activity Diagrams, or Sequence Diagrams.

March 25, 2026 Score: 2 Rep: 86,133 Quality: Medium Completeness: 50%

I would advise against using the Actor symbol for incoming API calls unless they come from a human or conceptual human entity. ie. a company sends you information.

If you have multiple APIs can can draw the diagram with subcomponents in a variety of ways, such as ports and gates, and keep the Actor symbol consistently to represent human users of the system eg.

sample uml

You want to be able to consistently list the Actors in your overall system, and if you use them as part of your internal structure of APIs this list will change as you restructure and be confusing.

There is an argument to be made from incoming information which is not triggered by your own system, ie you get stock price updates from a commercial supplier. But even here I would be looking for ways not to use actor if possible.

I wouldn't use it if I made the call out and got a response, so it seems an edge case to use it just because its a push rather than pull, or run by a supplier rather than internal.

I ultimately want to be able to reduce the diagram to a conceptual single component + human actors, this way it shows the overall utility of the system to humans, regardless of the technical implementation.