diff --git a/README.md b/README.md
index be0a46abe..876d9bc3c 100644
--- a/README.md
+++ b/README.md
@@ -50,11 +50,11 @@ provided pipeline library.
 
 ## API
 
-All steps are intended to be used by Pipelines. All the classes / groovy-scripts
-contained in the `src` folder are by default not part of the API and are subjected to change
-without prior notice. Types and methods annotated with `@API` are considered to be API, used e.g.
-from other shared libraries. Changes to those methods/types needs to be announced, disussed and
-agreed.
+All steps (`vars` and `resources` directory) are intended to be used by Pipelines and are considered API.
+All the classes / groovy-scripts contained in the `src` folder are by default not part of
+the API and are subjected to change without prior notice. Types and methods annotated with
+`@API` are considered to be API, used e.g. from other shared libraries. Changes to those
+methods/types needs to be announced, discussed and agreed.
 
 # Requirements
 
diff --git a/resources/default_pipeline_environment.yml b/resources/default_pipeline_environment.yml
index fe7ee797f..8cd70b04c 100644
--- a/resources/default_pipeline_environment.yml
+++ b/resources/default_pipeline_environment.yml
@@ -1,3 +1,8 @@
+#
+# ATTENTION: This file is part of the API, breaking changes here directly affect the consumers of the library.
+#            Please avoid breaking changes if possible.
+#
+
 #Project Setup
 general:
   productiveBranch: 'master'
diff --git a/src/com/sap/piper/API.groovy b/src/com/sap/piper/API.groovy
new file mode 100644
index 000000000..6721d6e8f
--- /dev/null
+++ b/src/com/sap/piper/API.groovy
@@ -0,0 +1,23 @@
+package com.sap.piper
+
+import java.lang.annotation.ElementType
+import java.lang.annotation.Retention
+import java.lang.annotation.RetentionPolicy
+import java.lang.annotation.Target
+
+/**
+ * Methods or classes annotated with this annotation are used outside
+ * this shared, e.g. in other shared libraries. In case there is the
+ * need for changing this methods this should be clearly announced
+ * in order to get a consensus about the change and in order to allow
+ * users of the corresponding class/method to adapt to the change accordingly.
+ */
+
+@Retention(RetentionPolicy.RUNTIME)
+@Target([ElementType.METHOD, ElementType.TYPE])
+@interface API {
+    /**
+     * API marked as deprecated should not be used and moved to non-deprecated API.
+     */
+    boolean deprecated() default false
+}
diff --git a/src/com/sap/piper/API.java b/src/com/sap/piper/API.java
deleted file mode 100644
index 92bbe7dc6..000000000
--- a/src/com/sap/piper/API.java
+++ /dev/null
@@ -1,19 +0,0 @@
-package com.sap.piper;
-
-import java.lang.annotation.ElementType;
-import java.lang.annotation.Retention;
-import java.lang.annotation.RetentionPolicy;
-import java.lang.annotation.Target;
-
-/**
- * Methods or classes annotated with this annotation are used outside
- * this shared, e.g. in other shared libraries. In case there is the
- * need for changing this methods this should be clearly announced
- * in order to get a consensus about the change and in order to allow
- * users of the correponding class/method to adapt to the change accordingly.
- */
-
-@Retention(RetentionPolicy.RUNTIME)
-@Target({ElementType.METHOD, ElementType.TYPE})
-public @interface API {
-}
diff --git a/src/com/sap/piper/ConfigurationHelper.groovy b/src/com/sap/piper/ConfigurationHelper.groovy
index 116fa8051..d8781eafd 100644
--- a/src/com/sap/piper/ConfigurationHelper.groovy
+++ b/src/com/sap/piper/ConfigurationHelper.groovy
@@ -2,6 +2,7 @@ package com.sap.piper
 
 import com.cloudbees.groovy.cps.NonCPS
 
+@API
 class ConfigurationHelper implements Serializable {
 
     static ConfigurationHelper newInstance(Script step, Map config = [:]) {
@@ -31,19 +32,16 @@ class ConfigurationHelper implements Serializable {
         return this
     }
 
-    @API
     ConfigurationHelper mixinGeneralConfig(commonPipelineEnvironment, Set filter = null, Map compatibleParameters = [:]){
         Map stepConfiguration = ConfigurationLoader.generalConfiguration([commonPipelineEnvironment: commonPipelineEnvironment])
         return mixin(stepConfiguration, filter, compatibleParameters)
     }
 
-    @API
     ConfigurationHelper mixinStageConfig(commonPipelineEnvironment, stageName, Set filter = null, Map compatibleParameters = [:]){
         Map stageConfiguration = ConfigurationLoader.stageConfiguration([commonPipelineEnvironment: commonPipelineEnvironment], stageName)
         return mixin(stageConfiguration, filter, compatibleParameters)
     }
 
-    @API
     ConfigurationHelper mixinStepConfig(commonPipelineEnvironment, Set filter = null, Map compatibleParameters = [:]){
         Map stepConfiguration = ConfigurationLoader.stepConfiguration([commonPipelineEnvironment: commonPipelineEnvironment], name)
         return mixin(stepConfiguration, filter, compatibleParameters)
@@ -103,7 +101,6 @@ class ConfigurationHelper implements Serializable {
         return this
     }
 
-    @API
     @NonCPS // required because we have a closure in the
             // method body that cannot be CPS transformed
     Map use(){
@@ -152,7 +149,6 @@ class ConfigurationHelper implements Serializable {
         }
     }
 
-    @API
     ConfigurationHelper withMandatoryProperty(key, errorMessage = null, condition = null){
         if(condition){
             if(condition(this.config))
diff --git a/src/com/sap/piper/ConfigurationLoader.groovy b/src/com/sap/piper/ConfigurationLoader.groovy
index f3c8a15a2..39f2a95a6 100644
--- a/src/com/sap/piper/ConfigurationLoader.groovy
+++ b/src/com/sap/piper/ConfigurationLoader.groovy
@@ -2,6 +2,7 @@ package com.sap.piper
 
 import com.cloudbees.groovy.cps.NonCPS
 
+@API(deprecated = true)
 class ConfigurationLoader implements Serializable {
     @NonCPS
     static Map stepConfiguration(script, String stepName) {
diff --git a/src/com/sap/piper/ConfigurationMerger.groovy b/src/com/sap/piper/ConfigurationMerger.groovy
index 4c3ec4675..20c58cc14 100644
--- a/src/com/sap/piper/ConfigurationMerger.groovy
+++ b/src/com/sap/piper/ConfigurationMerger.groovy
@@ -2,6 +2,7 @@ package com.sap.piper
 
 import com.cloudbees.groovy.cps.NonCPS
 
+@API(deprecated = true)
 class ConfigurationMerger {
     @NonCPS
     static Map merge(Map configs, Set configKeys, Map defaults) {
diff --git a/src/com/sap/piper/DefaultValueCache.groovy b/src/com/sap/piper/DefaultValueCache.groovy
index a620d3dce..7ae3ffd1e 100644
--- a/src/com/sap/piper/DefaultValueCache.groovy
+++ b/src/com/sap/piper/DefaultValueCache.groovy
@@ -2,6 +2,7 @@ package com.sap.piper
 
 import com.cloudbees.groovy.cps.NonCPS
 
+@API
 class DefaultValueCache implements Serializable {
     private static DefaultValueCache instance
 
diff --git a/src/com/sap/piper/JenkinsUtils.groovy b/src/com/sap/piper/JenkinsUtils.groovy
index e8c43005b..f49d158ff 100644
--- a/src/com/sap/piper/JenkinsUtils.groovy
+++ b/src/com/sap/piper/JenkinsUtils.groovy
@@ -4,6 +4,7 @@ import com.cloudbees.groovy.cps.NonCPS
 import jenkins.model.Jenkins
 import org.jenkinsci.plugins.workflow.steps.MissingContextVariableException
 
+@API
 @NonCPS
 static def isPluginActive(pluginId) {
     return Jenkins.instance.pluginManager.plugins.find { p -> p.isActive() && p.getShortName() == pluginId }
diff --git a/src/com/sap/piper/k8s/ContainerMap.groovy b/src/com/sap/piper/k8s/ContainerMap.groovy
index 5cdaae796..7a9402f57 100644
--- a/src/com/sap/piper/k8s/ContainerMap.groovy
+++ b/src/com/sap/piper/k8s/ContainerMap.groovy
@@ -1,5 +1,8 @@
 package com.sap.piper.k8s
 
+import com.sap.piper.API
+
+@API
 @Singleton
 class ContainerMap {
     private Map containerMap = null