In this thread we have a lot of suggestions and disagreements. I started looking for existing practices that we could copy, and here is the first thing I found. The top three hits in a DuckDuckGo search for "experimental APIs" [1] have in common the use of a run-time guard that prevents ordinary stable client software from accidentally using them by requiring an explicit acknowledgement action.
Chrome: you must enable Experimental Extension APIs in your browser, and "the Chrome Web Store doesn't allow you to upload items that use experimental APIs". Windows: "By default, these APIs are disabled at runtime and calling them will result in a runtime exception." OpenStack: "clients must include a specific HTTP header, X-OpenStack-Manila-API-Experimental". That's not something we've considered before. We could think of ways to implement such a thing, but, before we go there, even just having the possibility in mind may help us think more clearly about what we wish to achieve. [1] https://developer.chrome.com/extensions/experimental , https://docs.microsoft.com/en-us/windows/uwp/whats-new/experimental-apis , https://docs.openstack.org/manila/latest/contributor/experimental_apis.html -- - Julian