diff --git a/connectivity/FEATURE_BLE/include/ble/Gap.h b/connectivity/FEATURE_BLE/include/ble/Gap.h
index b9ab4bf82c..5f34695f9b 100644
--- a/connectivity/FEATURE_BLE/include/ble/Gap.h
+++ b/connectivity/FEATURE_BLE/include/ble/Gap.h
@@ -1453,11 +1453,11 @@ public:
 #endif // !defined(DOXYGEN_ONLY)
 } // namespace ble
 
+/* This includes the concrete class implementation, to provide a an alternative API implementation
+ * disable ble-api-implementation and place your header in a path with the same structure */
+#include "ble/internal/GapImpl.h"
+
+/** @deprecated Use the namespaced ble::Gap instead of the global Gap. */
+using ble::Gap;
 
 #endif // BLE_GAP_GAP_H
-
-#if (BLE_API_IMPLEMENTATION == 1)
-#include "ble/internal/GapImpl.h"
-#else
-#error "please provide alternate BLE implementation"
-#endif
diff --git a/connectivity/FEATURE_BLE/include/ble/GattClient.h b/connectivity/FEATURE_BLE/include/ble/GattClient.h
index 3cf6dc3f63..7f3fbeb1bf 100644
--- a/connectivity/FEATURE_BLE/include/ble/GattClient.h
+++ b/connectivity/FEATURE_BLE/include/ble/GattClient.h
@@ -716,10 +716,11 @@ public:
 #endif // !defined(DOXYGEN_ONLY)
 } // namespace ble
 
-#if (BLE_API_IMPLEMENTATION == 1)
+/* This includes the concrete class implementation, to provide a an alternative API implementation
+ * disable ble-api-implementation and place your header in a path with the same structure */
 #include "ble/internal/GattClientImpl.h"
-#else
-#error "please provide alternate BLE implementation"
-#endif
+
+/** @deprecated Use the namespaced ble::GattClient instead of the global GattClient. */
+using ble::GattClient;
 
 #endif /* ifndef MBED_GATT_CLIENT_H__ */
diff --git a/connectivity/FEATURE_BLE/include/ble/GattServer.h b/connectivity/FEATURE_BLE/include/ble/GattServer.h
index 064f095fe0..57a603b364 100644
--- a/connectivity/FEATURE_BLE/include/ble/GattServer.h
+++ b/connectivity/FEATURE_BLE/include/ble/GattServer.h
@@ -667,10 +667,11 @@ protected:
 #endif // !defined(DOXYGEN_ONLY)
 } // ble
 
-#if (BLE_API_IMPLEMENTATION == 1)
+/* This includes the concrete class implementation, to provide a an alternative API implementation
+ * disable ble-api-implementation and place your header in a path with the same structure */
 #include "ble/internal/GattServerImpl.h"
-#else
-#error "please provide alternate BLE implementation"
-#endif
+
+/** @deprecated Use the namespaced ble::GattServer instead of the global GattServer. */
+using ble::GattServer;
 
 #endif /* ifndef MBED_GATT_SERVER_H__ */
diff --git a/connectivity/FEATURE_BLE/include/ble/SecurityManager.h b/connectivity/FEATURE_BLE/include/ble/SecurityManager.h
index 7494e7ff11..c18dcb7ac9 100644
--- a/connectivity/FEATURE_BLE/include/ble/SecurityManager.h
+++ b/connectivity/FEATURE_BLE/include/ble/SecurityManager.h
@@ -938,10 +938,11 @@ public:
 #endif // !defined(DOXYGEN_ONLY)
 } // ble
 
-#if (BLE_API_IMPLEMENTATION == 1)
+/* This includes the concrete class implementation, to provide a an alternative API implementation
+ * disable ble-api-implementation and place your header in a path with the same structure */
 #include "ble/internal/SecurityManagerImpl.h"
-#else
-#error "please provide alternate BLE implementation"
-#endif
+
+/** @deprecated Use the namespaced ble::SecurityManager instead of the global SecurityManager. */
+using ble::SecurityManager;
 
 #endif /*BLE_SECURITY_MANAGER_H_*/
diff --git a/connectivity/FEATURE_BLE/include/ble/internal/BLEInstanceBase.h b/connectivity/FEATURE_BLE/include/ble/internal/BLEInstanceBase.h
index 330bf9c3c3..befdadc66e 100644
--- a/connectivity/FEATURE_BLE/include/ble/internal/BLEInstanceBase.h
+++ b/connectivity/FEATURE_BLE/include/ble/internal/BLEInstanceBase.h
@@ -257,11 +257,9 @@ public:
  */
 extern ble::BLEInstanceBase *createBLEInstance(void);
 
-#if (BLE_PAL_API_IMPLEMENTATION == 1)
+/* This includes the concrete class implementation, to provide a an alternative BLE PAL implementation
+ * disable Cordio and place your header in a path with the same structure */
 #include "ble/internal/BLEInstanceBaseImpl.h"
-#else
-#error "please provide alternate BLE implementation"
-#endif
 
 /**
  * @}
diff --git a/connectivity/FEATURE_BLE/include/ble/internal/PalAttClient.h b/connectivity/FEATURE_BLE/include/ble/internal/PalAttClient.h
index c0017cade5..e3b8d72d3d 100644
--- a/connectivity/FEATURE_BLE/include/ble/internal/PalAttClient.h
+++ b/connectivity/FEATURE_BLE/include/ble/internal/PalAttClient.h
@@ -630,10 +630,8 @@ public:
 } // namespace interface
 } // namespace ble
 
-#if (BLE_PAL_API_IMPLEMENTATION == 1)
+/* This includes the concrete class implementation, to provide a an alternative BLE PAL implementation
+ * disable Cordio and place your header in a path with the same structure */
 #include "ble/internal/PalAttClientImpl.h"
-#else
-#error "please provide alternate BLE implementation"
-#endif
 
 #endif /* BLE_PAL_ATTCLIENT_H_ */
diff --git a/connectivity/FEATURE_BLE/include/ble/internal/PalEventQueue.h b/connectivity/FEATURE_BLE/include/ble/internal/PalEventQueue.h
index d3954c7924..b33e213c26 100644
--- a/connectivity/FEATURE_BLE/include/ble/internal/PalEventQueue.h
+++ b/connectivity/FEATURE_BLE/include/ble/internal/PalEventQueue.h
@@ -58,10 +58,8 @@ public:
 } // namespace interface
 } // namespace ble
 
-#if (BLE_PAL_API_IMPLEMENTATION == 1)
+/* This includes the concrete class implementation, to provide a an alternative BLE PAL implementation
+ * disable Cordio and place your header in a path with the same structure */
 #include "ble/internal/PalEventQueueImpl.h"
-#else
-#error "please provide alternate BLE implementation"
-#endif
 
 #endif /* BLE_PAL_EVENT_QUEUE_H_ */
diff --git a/connectivity/FEATURE_BLE/include/ble/internal/PalGap.h b/connectivity/FEATURE_BLE/include/ble/internal/PalGap.h
index 1f638df836..846267fd89 100644
--- a/connectivity/FEATURE_BLE/include/ble/internal/PalGap.h
+++ b/connectivity/FEATURE_BLE/include/ble/internal/PalGap.h
@@ -1635,10 +1635,8 @@ public:
 } // namespace ble
 
 
-#if (BLE_PAL_API_IMPLEMENTATION == 1)
+/* This includes the concrete class implementation, to provide a an alternative BLE PAL implementation
+ * disable Cordio and place your header in a path with the same structure */
 #include "ble/internal/PalGapImpl.h"
-#else
-#error "please provide alternate BLE implementation"
-#endif
 
 #endif /* BLE_PAL_GAP_H_ */
diff --git a/connectivity/FEATURE_BLE/include/ble/internal/PalGattClient.h b/connectivity/FEATURE_BLE/include/ble/internal/PalGattClient.h
index 063be1bddc..79e9f3da8b 100644
--- a/connectivity/FEATURE_BLE/include/ble/internal/PalGattClient.h
+++ b/connectivity/FEATURE_BLE/include/ble/internal/PalGattClient.h
@@ -630,10 +630,8 @@ public:
 } // namespace interface
 } // namespace ble
 
-#if (BLE_PAL_API_IMPLEMENTATION == 1)
+/* This includes the concrete class implementation, to provide a an alternative BLE PAL implementation
+ * disable Cordio and place your header in a path with the same structure */
 #include "ble/internal/PalGattClientImpl.h"
-#else
-#error "please provide alternate BLE implementation"
-#endif
 
 #endif /* BLE_PAL_GATT_CLIENT_H_ */
diff --git a/connectivity/FEATURE_BLE/include/ble/internal/PalGenericAccessService.h b/connectivity/FEATURE_BLE/include/ble/internal/PalGenericAccessService.h
index c852da2928..416b39ad23 100644
--- a/connectivity/FEATURE_BLE/include/ble/internal/PalGenericAccessService.h
+++ b/connectivity/FEATURE_BLE/include/ble/internal/PalGenericAccessService.h
@@ -73,10 +73,8 @@ public:
 } // namespace interface
 } // namespace ble
 
-#if (BLE_PAL_API_IMPLEMENTATION == 1)
+/* This includes the concrete class implementation, to provide a an alternative BLE PAL implementation
+ * disable Cordio and place your header in a path with the same structure */
 #include "ble/internal/PalGenericAccessServiceImpl.h"
-#else
-#error "please provide alternate BLE implementation"
-#endif
 
 #endif /* BLE_PAL_GENERIC_ACCESS_SERVICE_H_ */
diff --git a/connectivity/FEATURE_BLE/include/ble/internal/PalSecurityManager.h b/connectivity/FEATURE_BLE/include/ble/internal/PalSecurityManager.h
index 3007670231..48ba87227d 100644
--- a/connectivity/FEATURE_BLE/include/ble/internal/PalSecurityManager.h
+++ b/connectivity/FEATURE_BLE/include/ble/internal/PalSecurityManager.h
@@ -1029,10 +1029,8 @@ public:
 } /* namespace interface */
 } /* namespace ble */
 
-#if (BLE_PAL_API_IMPLEMENTATION == 1)
+/* This includes the concrete class implementation, to provide a an alternative BLE PAL implementation
+ * disable Cordio and place your header in a path with the same structure */
 #include "ble/internal/PalSecurityManagerImpl.h"
-#else
-#error "please provide alternate BLE implementation"
-#endif
 
 #endif /* MBED_OS_FEATURES_FEATURE_BLE_BLE_PAL_PALSM_H_ */
diff --git a/connectivity/FEATURE_BLE/include/ble/internal/PalSigningMonitor.h b/connectivity/FEATURE_BLE/include/ble/internal/PalSigningMonitor.h
index 4698246a6c..b337994e4d 100644
--- a/connectivity/FEATURE_BLE/include/ble/internal/PalSigningMonitor.h
+++ b/connectivity/FEATURE_BLE/include/ble/internal/PalSigningMonitor.h
@@ -76,10 +76,8 @@ public:
 } // namespace interface
 } // namespace ble
 
-#if (BLE_PAL_API_IMPLEMENTATION == 1)
+/* This includes the concrete class implementation, to provide a an alternative BLE PAL implementation
+ * disable Cordio and place your header in a path with the same structure */
 #include "ble/internal/PalSigningMonitorImpl.h"
-#else
-#error "please provide alternate BLE implementation"
-#endif
 
 #endif /* MBED_BLE_SIGNING_EVENT_MONITOR */
diff --git a/connectivity/FEATURE_BLE/mbed_lib.json b/connectivity/FEATURE_BLE/mbed_lib.json
index f63b2be268..97405f5982 100644
--- a/connectivity/FEATURE_BLE/mbed_lib.json
+++ b/connectivity/FEATURE_BLE/mbed_lib.json
@@ -2,16 +2,6 @@
     "name": "ble",
     "config": {
         "present": 1,
-        "ble-api-implementation": {
-            "help": "What BLE user API implementation is used. Available options: 1 (Mbed). You may add more. See headers in include/ble/.",
-            "value": 1,
-            "macro_name": "BLE_API_IMPLEMENTATION"
-        },
-        "ble-pal-api-implementation": {
-            "help": "What Pal API implementation is used. Available options: 1 (Cordio). You may add more. See headers in include/ble/internal/Pal*.",
-            "value": 1,
-            "macro_name": "BLE_PAL_API_IMPLEMENTATION"
-        },
         "ble-role-observer": {
             "help": "Include observer BLE role support (scanning for and processing advertising packets).",
             "value": true,