Differentiating between observed APIs and modeled Application Services
=== ADDED 26-04-2021 === @kalin and I have proposed that we continue to work on this matter in a workgroup, see issue 35.
This issue is strongly related to issue 15 and could have been a part of it. However, as the discussion there has been quite extensive and will continue, I’ve decided to put this forward separately. Originally, I have proposed three options for representing API interactions; from the discussion, I have concluded that option 1 is the most appropriate.
However, option 2 is also correct (for a short while I thought it is not; comments from @kalin - check his comments in this issue - and this example convinced me of the opposite). In this proposed use (option 2) each Application Interface element represents a single API.
Option 2 has been invented for the following reason: If APIs (represented by Application Service elements) appear together with some other Application Services (that are modeled by architects) in the same model, one would like to differentiate between the two varieties. Therefore, it has been decided to use Application Interface elements (instead of Application Services) to represent individual APIs.
This is a scenario (showing the use of option 1) that describes the ratio behind option 2. It is further clarified with a hypothetical example.
Information about API interactions is being collected through automation and subsequently imported into an ArchiMate tool. The purpose is to align the architecture models with the operational reality when documenting the "as is" situation. The information that is being imported may be merged with an existing architecture model, or it could be the starting point in describing an existing system. Example: two APIs (called “Get this” and “Get that”) have been detected and represented in the import file as two Application Service elements. From some system documentation, it appears that those two APIs are the implementation of the functionality that has been modeled as a service called “Collection Service”. Therefore, as a result of the analysis, one may (manually) declare those two APIs to be parts of “Collection Service” (I’ve used aggregation – would it be better to use composition?).
Having no distinction between Application Service elements representing observed APIs and the elements representing services modeled by architects appears to be a matter of concern.
In summary: what would be an appropriate way to differentiate between APIs (web services, as discovered at the runtime) and application services that have been modeled? (@marclankhorst, @Wierda, @Michaelb, @kalin, @jbsarrodie ...)
My take on this is to differentiate only visually. In other words, to rely on the ability of the tool that is being used to provide for the needed distinction, while keeping that distinction out of the modeling language (except, maybe, in properties).
Below is the screen capture from Archi®. Presumably, other tools also provide some means to selectively visualize elements in different ways, preferably based on some properties.
One could also improve option 2 with specific visualizations (to illustrate, I'm using the same hypothetical example). Elements with the alternative shape and color and relationships depicted in orange are imported.
Relating API's to “Collection Service” might be less simple with option 2 than with option 1.