Skip to content

Align architecture.md to latest DIP, DEB & BEP #39

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
michatrautweiler wants to merge 8 commits into
base: master
Choose a base branch
from
Open

Align architecture.md to latest DIP, DEB & BEP #39

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
c3723fa
align architecture.md to DIP, DEB, BEP
Jun 12, 2024
8d50ae8
revert changes to non Vorgaben
Jun 12, 2024
ee38cce
align to DIP, DEB, BEP as of 2024
Jun 13, 2024
02e627b
Update architecture.md
Jun 13, 2024
171f860
Update architecture.md
Jun 13, 2024
fb7d565
Update architecture.md
Jun 13, 2024
5aa326d
Update architecture.md
Jun 13, 2024
22e9532
Update architecture.md
Jun 13, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 17 additions & 26 deletions architecture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,44 +22,35 @@ This section lists all high level architectural principles that have a relevant

---

## Consider reading best practices

We do recommend to read the best practices for [RESTful](/api-principles/restful/best-practices/) and [Event-Driven](/api-principles/eventdriven/best-practices/) APIs before designing and implementing a new interface. It is quite a long lecture, but for a deep understanding of the implications of some design decisions, we believe that you will profit a lot from this common knowledge.

## 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.
Copy link
Copy Markdown
Collaborator

@thpeng thpeng Jun 14, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Collaborator

@klauslechner klauslechner Mar 7, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

*@see also: the complete [Design, Development and Operation Principle](https://confluence.sbb.ch/display/VORGABEN/DEB+Design-+Entwicklungs-+und+Betriebsprinzip) \[internal link\]*

### `MUST` Team decomposition and architecture decomposition are aligned
Development teams build the core unit in the phase of decomposition and separation of concerns into different applications ... Each application is assigned to exactly one development team ... Dependencies between applications are also dependencies between teams.

### `MUST` APIs belong to business capabilities
An API itself is not a business capability, but it transports the teams core business values to other teams. Therefore, a team providing a business capability must own and provide the according API. This API must explicitly not be owned and/or maintained by other teams.

For engineering teams, focusing on building business capabilities, it is tempting to delegate the API capabilities to a team which is the expert of building and providing APIs. But during the last decades we have learned, that introducing an API team which publishes the API for an other team introduces an additional organizational and technical dependency which slows down evolution, complicates failure tracing and increases cost in creation and maintenance.
We design our applications along business functions in sizes that our teams can manage.

## Delivery Principles
*@see also: the complete [Software Provisioning Principles](https://confluence.sbb.ch/x/ugMtU) \[internal link\]*

### `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.
Copy link
Copy Markdown
Collaborator

@thpeng thpeng Jun 14, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Collaborator

@klauslechner klauslechner Mar 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

*@see also: the complete [Delivery Principle](https://confluence.sbb.ch/display/VORGABEN/BEP+Bereitstellungsprinziphttps://confluence.sbb.ch/x/ugMtU) \[internal link\]*

During the process of software provisioning, the most actual and applicable [API Principles](https://schweizerischebundesbahnen.github.io/api-principles/) must be part of the decision criterias.

## Data and Integration Principles
*@see also: the complete [Data and Integration Principle](https://confluence.sbb.ch/x/1wMtU)\[internal link\]*

### `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).
Copy link
Copy Markdown
Collaborator

@thpeng thpeng Jun 14, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

while the data protection part is corrrect (and a valuable addition) I would suggest also to add the dimension of confidentiality.

Copy link
Copy Markdown
Collaborator

@klauslechner klauslechner Mar 7, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

*@see also: the complete [Data and Integration Principle](https://confluence.sbb.ch/display/VORGABEN/DIP+Daten-+und+Integrationsprinzip) \[internal link\]*

Applications and their data are very valuable assets. Every team must publish it's business capabilities and data over well defined APIs using the [RESTful](restful/restful.md) or [Event-Driven](eventdriven/eventdriven.md) architectural style. APIs are accessible, well documented and designed with consumer oriented focus.

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.
Copy link
Copy Markdown
Collaborator

@thpeng thpeng Jun 14, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Collaborator

@klauslechner klauslechner Mar 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

### `MUST` Data master share business functions and data over APIs
As data masters, we share the data and functions of our business capabilities. We provide the functions and data to other applications through over well defined APIs using the [RESTful](restful/restful.md) or [Event-Driven](eventdriven/eventdriven.md) architectural style.
We published them in the [API Repository](https://developer.sbb.ch) for further use in conformance to the API principles listed here.

### `MUST` We reuse existing APIs from the API Repository
Before building up a new dependency between applications and teams, we check for existing capabilities in the [API Repository](https://developer.sbb.ch).
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.
Copy link
Copy Markdown
Collaborator

@thpeng thpeng Jun 14, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Collaborator

@klauslechner klauslechner Mar 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

We do recommend to read the best practices specifc to [RESTful](/api-principles/restful/best-practices/) and [Event-Driven](/api-principles/eventdriven/best-practices/) APIs before designing and implementing a new interface. It is quite a long lecture, but for a deep understanding of the implications of some design decisions, we believe that you will profit a lot from this common knowledge.

### `MUST` Hide Complexity
The Design of an API must follow the principle of [information hiding](https://en.wikipedia.org/wiki/Information_hiding). As already described above, APIs transport business capabilities, but they **must not** transport the complexity of the system behind the API. This means it is relevant that an API hides implementation details. An API should be understandable and intuitive for humans that are not very familiar with the API's business domain.
Expand Down