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.
| ## 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.
| ### `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.
| 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.
| 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.
