Merge pull request #9 from stakater/add-api-architecture-guidelines

add architecture and api guidelines

.vuepress/config.js

@@ -15,6 +15,8 @@ module.exports = {
                     '/architecture/rest',
                     '/architecture/microservices/',
                     '/architecture/eda',
+                    '/architecture/architecting-applications-for-kubernetes',
+                    '/architecture/12-factors',
                 ]
             },
             {
@@ -37,6 +39,7 @@ module.exports = {
             {
                 title: 'API',
                 children: [
+                    '/api/general-guidelines',
                     '/api/naming',
                     '/api/resources',
                     '/api/request-response',

Jenkinsfile

@@ -1,5 +1,7 @@
 #!/usr/bin/env groovy
-@Library('github.com/stakater/fabric8-pipeline-library@v2.8.6') _
+@Library('github.com/stakater/fabric8-pipeline-library@v2.10.2') _
 
 appWithDockerfileBuildRelease {
+    dockerRepositoryURL = 'docker.release.stakater.com:443'
+    deployApp = true
 }

api/general-guidelines.md

@@ -0,0 +1,35 @@
+# General Guidelines
+
+## Must: Write APIs in U.S. English
+
+Always write API's in U.S. English.
+
+## Must: Follow API First Principle
+
+As mentioned in the introduction, API First is one of our architecture principles, as per our Architecture Rules of Play. In a nutshell API First has two aspects:
+
+- define APIs outside the code first using a standard specification language
+- get early review feedback from peers and client (frontend) developers
+
+By defining APIs outside the code, we want to facilitate early review feedback and also a development discipline that focus service interface design on...
+
+- profound understanding of the domain and required functionality
+- generalized business entities / resources, i.e. avoidance of use case specific APIs
+- clear separation of WHAT vs. HOW concerns, i.e. abstraction from implementation aspects — APIs should be stable even if we replace complete service implementation including its underlying technology stack
+
+Moreover, API definitions with standardized specification format also facilitate...
+
+- single source of truth for the API specification; it is a crucial part of a contract between service provider and client users
+- infrastructure tooling for API discovery, API GUIs, API documents, automated quality checks
+
+It is important to learn, that API First is not in conflict with the agile development principles that we love. Service applications should evolve incrementally — and so its APIs. Of course, API specification will and should evolve iteratively in different cycles, each starting with draft status and early team and peer review feedback.
+
+API may change and profit from implementation concerns and automated testing feedback. API evolution during development life cycle may include breaking changes for not yet productive features and as long as we have aligned the changes with the clients. Hence, API First does not mean that you must have 100% domain and requirement understanding and can never produce code before you have defined the complete API and get it confirmed by peer review. On the other hand, API First obviously is in conflict with the practice of publishing API definition and asking for peer review after the service integration or even the service productive operation has started. It is crucial to request and get early feedback — as early as possible, but not before the API changes are comprehensive with focus to the next evolution step and have a certain quality (including API Guideline compliance), already confirmed via team internal reviews.
+
+## Must: Provide API Reference Definition using OpenAPI
+
+We use the OpenAPI specification (aka Swagger spec) as standard for REST API definitions. You may choose YAML or JSON as a format of your OpenAPI API definition file; however, YAML is generally preferred due to its improved readability.
+
+We also call the OpenAPI API definition the "API Reference definition" (or "API definition"); it provides all information needed by an experienced API client developer to use this API.
+
+The OpenAPI API specification file should be subject of version control together with source code management. Services also have to support an endpoint to access the API Reference definition for their external API(s).

architecture/12-factors.md

@@ -0,0 +1,24 @@
+# 12 Factor Apps
+
+One popular methodology that can help you focus on the characteristics that matter most when creating cloud-ready web apps is the Twelve-Factor App philosophy. Written to help developers and operations teams understand the core qualities shared by web services designed to run in the cloud, the principles apply very well to software that will live in a clustered environment like Kubernetes. While monolithic applications can benefit from following these recommendations, microservices architectures designed around these principles work particularly well.
+
+A quick summary of the Twelve Factors are:
+
+- **Codebase**: Manage all code in version control systems (like Git or Mercurial). The codebase comprehensively dictates what is deployed.
+- **Dependencies**: Dependencies should be managed entirely and explicitly by the codebase, either vendored (stored with the code) or version pinned in a format that a package manager can install from.
+- **Config**: Separate configuration parameters from the application and define them in the deployment environment instead of baking them into the application itself.
+- **Backing services**: Local and remote services are both abstracted as network-accessible resources with connection details set in configuration.
+- **Build, release, run**: The build stage of your application should be completely separate from your application release and operations processes. The build stage creates a deployment artifact from source code, the release stage combines the artifact and configuration, and the run stage executes the release.
+- **Processes**: Applications are implemented as processes that should not rely on storing state locally. State should be offloaded to a backing service as described in the fourth factor.
+- **Port binding**: Applications should natively bind to a port and listen for connections. Routing and request forwarding should be handled externally.
+- **Concurrency**: Applications should rely on scaling through the process model. Running multiple copies of an application concurrently, potentially across multiple servers, allows scaling without adjusting application code.
+- **Disposability**: Processes should be able to start quickly and stop gracefully without serious side effects.
+- **Dev/prod parity**: Your testing, staging, and production environments should match closely and be kept in sync. Differences between environments are opportunities for incompatibilities and untested configurations to appear.
+- **Logs**: Applications should stream logs to standard output so external services can decide how to best handle them.
+- **Admin processes**: One-off administration processes should be run against specific releases and shipped with the main process code.
+
+By adhering to the guidelines provided by the Twelve Factors, you can create and run applications using a model that fits the Kubernetes execution environment. The Twelve Factors encourage developers to focus on their application's primary responsibility, consider the operating conditions and interfaces between components, and use inputs, outputs, and standard process management features to run predictably in Kubernetes.
+
+## References
+
+- https://12factor.net/