The page you requested could not be found. Try using the navigation {% if site.search_enabled %}or search {% endif %}to find what you're looking for or go to this site's home page.
-------------------------------------------------------------------------------- /_config.yml: -------------------------------------------------------------------------------- 1 | remote_theme: pmarsceill/just-the-docs 2 | 3 | title: API Principles 4 | description: The SBB API Principles 5 | baseurl: "/api-principles" 6 | url: "https://schweizerischebundesbahnen.github.io" 7 | 8 | permalink: pretty 9 | search_enabled: true 10 | heading_anchors: true 11 | aux_links: 12 | "API Principles on GitHub": 13 | - "//github.com/schweizerischebundesbahnen/api-principles" 14 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/bug_report.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Bug report 3 | about: Create a report to help us improve 4 | title: '' 5 | labels: '' 6 | assignees: '' 7 | 8 | --- 9 | 10 | **Describe the bug** 11 | A clear and concise description of what the bug is. 12 | 13 | **Chapter And location** 14 | The precise location of the bug in the documentation 15 | 16 | **Possible Solution** 17 | Describe possible solutions to the bug 18 | -------------------------------------------------------------------------------- /restful/restful.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | title: RESTful APIs 4 | nav_order: 5 5 | has_children: true 6 | permalink: /restful 7 | --- 8 | 9 | RESTful APIs 10 | ============ 11 | 12 | This section lists SBB's design principles and best practices of RESTful APIs. The **design principles** are subject to IT Governance and thus **must** be followed when implementing APIs. The **best practices** section is a collection of common knowledge and proven design ideas. -------------------------------------------------------------------------------- /eventdriven/eventdriven.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | title: Event-Driven APIs 4 | nav_order: 6 5 | has_children: true 6 | permalink: /eventdriven 7 | --- 8 | 9 | Event-Driven APIs 10 | ================= 11 | 12 | 13 | This section lists SBB's design principles and best practices of Event-Driven APIs. The **design principles** are 14 | subject to IT Governance and thus **must** be followed when implementing APIs. The **best practices** section 15 | is a collection of common knowledge and proven design ideas. -------------------------------------------------------------------------------- /adocToMd.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | #for f in *.adoc 4 | #do 5 | # ADOC_FILENAME="$f" 6 | # FILENAME="${ADOC_FILENAME%%.*}" 7 | # MD_FILENAME="$FILENAME.md" 8 | # XML_FILENAME="$FILENAME.xml" 9 | # 10 | # asciidoctor -b docbook "$ADOC_FILENAME" 11 | # pandoc -f docbook -t markdown_strict "$XML_FILENAME" -o "$MD_FILENAME" 12 | # #iconv -t utf-8 "$XML_FILENAME" | pandoc -f docbook -t markdown_strict | iconv -f utf-8 > "$MD_FILENAME" 13 | # iconv -t utf-8 "$XML_FILENAME" | pandoc -f docbook -t markdown_strict --wrap=none | iconv -f utf-8 > "$MD_FILENAME" 14 | # rm ./"$XML_FILENAME" 15 | # rm ./"$ADOC_FILENAME" 16 | #done -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/feature_request.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Feature request 3 | about: Suggest an idea for this project 4 | title: '' 5 | labels: '' 6 | assignees: '' 7 | 8 | --- 9 | 10 | **Is your feature request related to a problem? Please describe.** 11 | A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] 12 | 13 | **Describe the solution you'd like** 14 | A clear and concise description of what you want to happen. 15 | 16 | **Describe alternatives you've considered** 17 | A clear and concise description of any alternative solutions or features you've considered. 18 | 19 | **Additional context** 20 | Add any other context or screenshots about the feature request here. 21 | -------------------------------------------------------------------------------- /maturity/maturity.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | title: Maturity 4 | nav_order: 4 5 | --- 6 | 7 | Maturity 8 | ======== 9 | {: .no_toc } 10 | 11 | We have defined a maturity model in order to be able to differentiate between good and bad interfaces. This is an important precondition for the movement to better interfaces by fostering a high demanding API culture. 12 | 13 | --- 14 | 15 | ## Table of contents 16 | {: .no_toc .text-delta } 17 | 18 | 1. TOC 19 | {:toc} 20 | 21 | --- 22 | 23 | ## `MUST` Continuous improvement of API Maturity 24 | 25 | APIs must invest a continuous effort in increasing the maturity of an API according to the *API Maturity Model*. 26 |  27 | 28 | #### Rational 29 | {: .no_toc } 30 | 31 | Higher maturities of interfaces lead to lower costs due to ... 32 | - higher speed in the development of API consumers. 33 | - higher reuse coefficient due to better understandability, quality and functional precision. 34 | 35 | --- 36 | 37 | ## `MUST` APIs provide automated tests 38 | 39 | An API must provide at least one staging environment with full functionality and *close-to-production* testdata. 40 | 41 | #### Rational 42 | {: .no_toc } 43 | 44 | A production-like testing environment increases ... 45 | - speed in implementing new features in the API. 46 | - changeability and maintainability rates. 47 | - operational stability (e.g. less unknown side-effects). -------------------------------------------------------------------------------- /eventdriven/platforms.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | title: Platform specific documentation 4 | parent: Event-Driven APIs 5 | nav_order: 3 6 | --- 7 | 8 | Event-Driven APIs on specific platforms 9 | =========================== 10 | {: .no_toc } 11 | 12 | This chapter adds requirements and best practices for specific SBB platforms 13 | 14 | --- 15 | 16 | ## Table of contents 17 | {: .no_toc .text-delta } 18 | 19 | 1. TOC 20 | {:toc} 21 | 22 | ## Requirements Kafka Platform 23 | 24 | ### `MUST` comply with the Naming Conventions for Topics 25 | Infrastructure artifacts like topics and queues must be named according to the following naming conventions: 26 | 27 | `{application-abbreviation}.{application-specific}` 28 | 29 | - {application-abbreviation}:\ 30 | [a-z0-9-]+ (Sequence of:lower case,numbers, dashes). **Important:** For internal applications, use one of the documented names or aliases according to the EA Repository. 31 | - {application-specific}:\ 32 | [a-z0-9-.] (Sequence of:lower case, numbers, dashes, periods) 33 | 34 | ## Best practices Kafka Platform 35 | 36 | ### Initialload / state restore 37 | 38 | When building an AsyncAPI on the Kafka platform, you should ask yourself how a prospective customer can restore its state, 39 | using only the Kafka topics as a source. After all, the feature of sending *and storing messages in a longterm fashion* is the unique 40 | selling point of this technology. Consider the following hints 41 | * Are you sending self-containing snapshots or events (which require some kind of a baseline)? 42 | * Are there additional topics where your customer may obtain a baseline in a periodic fashion? 43 | * Are the retention time on the topic appropriate for this use case? 44 | 45 | If possible, refrain from building a backchannel to request a baseline. There is also always the possibility to build a baseline topic with Kafka Streams -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 |  2 | 3 | This is the repository for maintaining the SBB's API Principles, as part of the company wide *Integration Architecture* initiative. The principles are subject to constant improvements and are valid for all kind of software projects, independent of the chosen procurement model: reuse, buy, customize, make and also shoring. 4 | 5 | *See it in action:* https://SchweizerischeBundesbahnen.github.io/api-principles/ 6 | 7 | ## Repository Structure 8 | 9 | #### Documentation 10 | The [/docs](/docs) folder contains all the markdown files which are rendered with [jekyll](https://jekyllrb.com). The master branch is automatically being published using [GitHub Pages](https://pages.github.com). For styling, we use [Patrick Marceill](https://github.com/pmarsceill)'s awesome jekyll theme called *[Just-The-Docs](https://github.com/pmarsceill/just-the-docs)*. 11 | 12 | #### Versioning 13 | The applicable principles are the ones described in the version of the master branch. Minor changes and bugfixes will be merged, using the simple review process by the "Integration Team". We maintain Major changes and extensions in a Branch using the name of the next version following the rules of [semantic versioning](https://semver.org/). Releases of new major versions `MUST` be approved by the central IT architecture board and are afterwards merged into the master branch as the new applicable set of principles. 14 | 15 | When Introducing a new Version, Changes must be updated in the [CHANGELOG.md](/CHANGELOG.md) file. 16 | 17 | #### Styling 18 | Custom styling is overwritten in the [_sass/custom](/_sass/custom) Folder. For further information on customization, read the documentation for [customization](https://pmarsceill.github.io/just-the-docs/docs/customization/). 19 | 20 | #### Contributing 21 | You are always welcome to [contribute](/CONTRIBUTING.md) to our API Principles by filing a Pull Request (PR). 22 | 23 | #### Thank you 24 | - To Zalando for the publication of their awesome set of RESTful API Guidelines, which is published under the [CC-BY](https://github.com/zalando/restful-api-guidelines/blob/master/LICENSE) (Creative commons Attribution 4.0) license. We’ve learned a lot while reading and adopting them to our needs. 25 | 26 | #### License 27 | [Apache License 2.0](/LICENSE) 28 | -------------------------------------------------------------------------------- /collaboration.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | title: Collaboration 4 | nav_order: 8 5 | --- 6 | 7 | Collaboration 8 | ============= 9 | {: .no_toc } 10 | 11 | For the purpose of better collaboration on dependencies between teams, we suggest some methodologies that have proven to be very effective for teams working together over APIs. 12 | 13 | --- 14 | 15 | ## Table of contents 16 | {: .no_toc .text-delta } 17 | 18 | 1. TOC 19 | {:toc} 20 | 21 | --- 22 | 23 | ## `MUST` Consumers contribute to APIs 24 | 25 | Teams of APIs are open to contributions of other teams by following the [InnerSource](https://innersourcecommons.org) culture. API Consumers contribute the following types of code: 26 | - `MUST` Documentation 27 | - `MUST` Consumer Driven Contract Tests 28 | - `MUST` Bug-Reports and Feature-Requests 29 | - `SHOULD` Bugfixes in the API 30 | - `SHOULD` Simple API Features 31 | - `MAY` Complex Features 32 | - `MAY` Refactorings 33 | 34 | Teams maintaining an API should actively foster collaboration on their API and should therefore actively maintain a consumer community. 35 | 36 | #### Rational 37 | {: .no_toc } 38 | 39 | - APIs will eventually become "consumer driven" (see also the [API Maturity model](maturity/maturity.md)). 40 | - The Design of an API is more consumer oriented and therefore provides a better developer usability and more functionality. This leads to lower costs through higher reuse. 41 | - Better speed of API Consumer teams and much less waiting times of consumers for a feature. Solves the *backlog hibernation* and thus reduces [Cost of Delay](https://en.wikipedia.org/wiki/Cost_of_delay). 42 | 43 | --- 44 | 45 | ## `SHOULD` API Consumers provide interface tests 46 | 47 | APIs should allow and engage consumers to provide *Consumer Driven Contract Tests*. Tests can be provided over a pact broker like the one from [pact.io](https://docs.pact.io/pact_broker)) or over source code [contribution](collaboration.md/#must-consumers-contribute-to-apis). 48 | 49 | #### Rational 50 | {: .no_toc } 51 | 52 | - With consumer tests, API consumers take on responsibility of the changeability and operational stability of APIs. 53 | - This leads to early end-to-end testing of interfaces between teams. Early discussions between teams often lead to better collaboration, stability and quality. 54 | - Consumers are motivated to contribute to APIs (CDC is a an important entry-level step for the path to an *InnerSource* collaboration model). 55 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing 2 | 3 | We appreciate all kinds of contributions. As a contributor, here are the guidelines we would like you to follow: 4 | 5 | - [Issues and Bugs](#issue) 6 | - [Submission Guidelines](#submit-pr) 7 | - [Commit Message Guidelines](#commit) 8 | 9 | ## Found an Issue? 10 | If you find a mistake or unclear formulation in the documentation (sources @ [/docs](/docs) folder), you can help us by [submitting an issue](#submit-issue) to our [GitHub Repository][github]. Including an improvement suggestion helps the team understand the desired change. 11 | 12 | You can help the team even more and [submit a Pull Request](#submit-pr) with a concrete improvement or bugfix. 13 | 14 | ### Submitting an Issue 15 | If your issue appears to be a bug, and hasn't been reported, open a new issue. 16 | Providing the following information will increase the chances of your issue being dealt with quickly: 17 | 18 | * **Motivation for change or Use Case** - explain what are you trying to do and why the current state does not fit your needs 19 | * **Related Issues** - has a similar issue been reported before? 20 | * **Suggest a Fix** - if you can't fix the bug yourself, perhaps you can point to what might be wrong. 21 | 22 | You can file new issues by providing the above information [here](https://github.com/SchweizerischeBundesbahnen/api-principles/issues/new). 23 | 24 | ### Submitting a Pull Request (PR) 25 | Before you submit your Pull Request (PR) consider the following guidelines: 26 | 27 | * Make your changes in a new git branch: 28 | 29 | ```shell 30 | git checkout -b my-fix-branch master 31 | ``` 32 | 33 | * Write the changes in english and check the documents against an english spell-checker (e.g. [grammarly](https://app.grammarly.com)) 34 | * Commit your changes using a descriptive commit message that follows our [commit message conventions](#commit). 35 | 36 | ```shell 37 | git commit -a 38 | ``` 39 | Note: the optional commit `-a` command line option will automatically "add" and "rm" edited files. 40 | 41 | * Push your branch to GitHub: 42 | 43 | ```shell 44 | git push my-fork my-fix-branch 45 | ``` 46 | 47 | * In GitHub, send a pull request to `api-principles:master`. 48 | 49 | ## Commit Message Guidelines 50 | 51 | This project uses [Conventional Commits](https://www.conventionalcommits.org/) to generate the changelog. 52 | 53 | ### Commit Message Format 54 | ``` 55 | docs: