Pattern Sections
Pattern: Experimental
Preview 
a.k.a. Beta Program, Testing Sandbox, API Preview
Context
A provider is developing a new API or a new API version that differs significantly from the published version(s) and is still under intensive development. As a result, the provider wants to be able to freely make any modifications necessary. However, the provider also wants to offer its clients early access so that these clients can start integrating against the new API and comment on the proposed API functionality and structure (in support of an iterative and incremental, or even agile, integration development process).
Problem
How can providers make the introduction of a new API, or new API version, less risky for their clients and obtain early adopter feedback without having to freeze the API design prematurely?
Forces
The use of this pattern is driven by the following forces:
- Make room for innovations and new features (often developed iteratively and incrementally)
- Obtain early feedback (for providers)
- Focus efforts (in early development, e.g., avoid API governance efforts)
- Offer early learning opportunities (for consumers)
- Desire to be able to rely on API stability (from a client point of view)
When offering a new API version, or even more so when offering a completely new API, providers want to showcase interim versions during development to their future customers. This raises the awareness of the new API (version), facilitates feedback and gives the customers time to decide whether to use the new API and plan development projects to make use of them. However, providers are still actively developing the API and want to retain the freedom to make arbitrary changes and to rapidly address client feedback.
Pattern forces are explained in depth in the book.
Solution
Provide access to an API on a best-effort basis without making any commitments about the functionality offered, stability, and longevity. Clearly and explicitly articulate this lack of API maturity to manage client expectations.
Sketch
A solution sketch for this pattern from pre-book times is:
Example
Let us assume that a software development company X wants to create a new product that lets it leave its comfort zone because it goes beyond the functionality offered in existing products: X has been active in the development of a continuous build and deployment solution, currently offered as a cloud software service with a Web-based online user interface. Development teams use the service to build the software by fetching a revision from a repository and deploying the artifacts to configurable servers. Large customers have now requested an API to better trigger and manage builds and receive notifications about build states besides the Web interface. Because X has not yet offered any APIs and thus lacks knowledge and experience, the developers choose an Experimental Preview of the API and improve it continuously by incorporating feedback from the customers that decide to adopt it early.
Are you missing implementation hints? Our papers publications provide them (for selected patterns).
Consequences
The resolution of pattern forces and other consequences are discussed in our book.
Known Uses
- GitHub offers API Previews following this pattern, for instance for its GraphQL support (at the time of writing).
- Facebook also applies this patterns for its core API. For instance, there is an Audience Network SDK Beta Program.
- Google had a reputation to roll out and get stuck in beta phase for a long time; see for instance this opinion piece.
- eBay has the notion of Experimental APIs
- Sandboxes and beta programs are commonly used by many cloud service providers and their APIs; for instance the Platform-as-a-Service (PaaS) offering of Swisscom, a Swiss cloud provider, had this status in 2015.
More Information
Related Patterns
Experimental Preview is similar to traditional beta (testing) programs. It is the weakest support commitment an API provider can give, followed by Aggressive Obsolescence. When transitioning the API to a productive environment, another life cycle governance (a.k.a. evolution strategy) pattern must be chosen, e.g., Two In Production, Limited Lifetime Guarantee, or even (when really required) Eternal Lifetime Guarantee. When the N in Production variant of Two In Production is applied, an Experimental Preview can be combined with any of these patterns.
The Experimental Preview may have a Version Identifier but does not have to.
An API Description should clearly state which version is experimentally previewed and which one is productive. Specific API Keys can be assigned to grant certain clients access to the preview/the beta version.
Other Sources
For tips and tricks about beta testing, refer to the DZone article “Beta Testing of Your Product: 6 Practical Steps to Follow”.
In a Tyk blog post, James Higginbotham advises to “Keep Supported and Unsupported Operations Separate”, “Get Feedback Early and Often”, and recommends the following stability states of API operations: Experimental, Pre-Release, Supported, Deprecated, Retired (source).