Align architecture.md to latest DIP, DEB & BEP#39
Conversation
michatrautweiler
commented
Jun 13, 2024
michatrautweiler
commented
- fix internal links, names & descriptions to current DIP, DEB & BEP
- remove texts not part of these three
- move requirements not part of these to new section ##API best practices
- update internal links, fix names and descriptions to correspond with DIP, DEB, BEP as of 5.2024. - remove texts not part of these / move them to new section ## API best practices
|
|
||
| ### `MUST` Reuse before make | ||
| Teams must reuse functionality of other teams when the desired functionality is already existing. We prefer contributions to existing APIs (e.g. following [InnerSource](https://innersourcecommons.org) principles) than to rewrite already existing functionality of other teams. | ||
| For new applications, we prefer market solutions over in-house development. We support a business need with an existing application and reuse it through APIs. |
There was a problem hiding this comment.
This change is imho not entirely correct. The meaning before relates to reuseing an api before making a new one, which can be defined in the api principles. The new statement is a generic one from the DEB (and is true) but it is not in the scope of the api principles to define or relate such architectural guidelines about applications.
I'll clarify the statement about reuse functionality.
There was a problem hiding this comment.
I agree with Thierry. The intention of this paragraph corresponds with rule 2 in the DIP (Chapter 2.3.2): Using interfaces
"We utilize existing data and functions through the available interfaces. When we need
data, we check the SBB’s API repository or data catalog to see if it is already available. If
so, we use that interface. If not, we request the provision of an interface from the data
master."
We're not referring to the BEP principle here (rent > buy > make).
| ## Architecture Design, Development and Operation Principles | ||
| *@see also: the complete [Architecture Design, Development and Operation Principle](https://confluence.sbb.ch/x/NqCydQ) \[internal link\]* | ||
| ## Design, Development and Operation Principles | ||
| We split up our applications along business functions, build them on the basis of development stacks and design them for sustainable and stable operational use. |
There was a problem hiding this comment.
API Principles should not offer opinions about the structure of applications. The statement itself is valid, but should (and afaik is) defined in other regulations.
There was a problem hiding this comment.
Agreeing as well. Furthermore, we should not build redundancies to our architectural principles. The functional design of applications is described in the DEB principle.
Also quoting the DIP:
"The data is aligned with the business-oriented domains. Where applicable, the data
meets the requirements from data target architectures and conceptual data models.""
| ### `MUST` Teams share business capabilities and data over APIs | ||
| Teams must focus on collaborating with other teams. They consume existing business capabilities and data over APIs. | ||
| We share and use SBB data and functions throughout the whole group. We handle data with care. When sharing and using the data, we adhere to its data privacy | ||
| requirements (e.g. data privacy regulations). |
There was a problem hiding this comment.
while the data protection part is corrrect (and a valuable addition) I would suggest also to add the dimension of confidentiality.
There was a problem hiding this comment.
While all of that above is correct, it's also pretty redundant with the DIP, where confidentiality is also included. Quoting:
Chapter 2.3.3 Publishing interfaces: "The documentation of
the interfaces includes the classification of the data transmitted through them with
respect to data protection and confidentiality."
Also:
"We make our data, interfaces, and their documentation openly accessible. Our data
and interfaces are generally freely available within the organization, provided this is
compatible with the protection needs of the data (see also [5]).
• When providing and using data, we consider their protection requirements (e.g.,
data protection and confidentiality rules), clearly indicate them and provide suitable
mechanisms for access control."
| We use existing functions and their data through the APIs available in the [API Repository](https://developer.sbb.ch). We obtain data from the leading application (data master). | ||
|
|
||
| ## API best practices | ||
| While not part of an official regulation, following API principles have proven to be valuable at SBB and throughout the software industry. |
There was a problem hiding this comment.
This statement in the first part of the sentence is imho not correct. The API Principles are part of an official regulation (the DIP refers to the api principles) and can be enforced in the moderation process.
There was a problem hiding this comment.
Thierry is correct, as almost always. See DIP, Chapter 3.1:
"3.1. SBB API principles
The SBB API principles regulate the requirements for the respective implementation and
publication of an API. They also provide detailed implementation guidelines."
| The owner and master of data assets must always be clearly defined and well know to both sides of a dependency. | ||
|
|
||
| ### `MUST` Composition of applications is done over well defined APIs | ||
| Dependencies between applications are always built over well defined interfaces (APIs). There must be no quick-and-dirty workarounds like direct access to a database of an other application. |
There was a problem hiding this comment.
What is the reason to delete the requirement the heading and the follwing statement? The DIP applies to APIs for data master but also for apis from systems who are not.
There was a problem hiding this comment.
Actually, you could argue that having this in the API principles is kinda redundant. The DIP clearly states, what is being said in the above.
3 participants
