Building a product that’s primarily a platform for others to build on top of, like web APIs or programming libraries, is often a good product strategy. However, software platform development teams may need to approach design, testing, and quality assurance processes differently from a software product with a user interface. A naive approach can result in platform features that are disconnected from real user needs and drift as the platform grows. This makes it difficult for non-developer stakeholders to engage with these.
Ideally, the practices applied when building a platform connect the platform features to real target use cases without locking the platform into supporting only those known patterns. Best practices also enable non-developer stakeholders to engage and provide feedback. Following are five tips to help a software platform development team find success.
Write orchestration tests that cover real use cases.
Follow longer orchestrations across features that platform users depend on. Your list of these will never be exhaustive but focus on core use cases. If the team only writes tests for features in isolation, there’s a risk of problems where features interact. These tests help protect behavior that real users expect to continue working.
For example, imagine we’re building a platform that’s an API-only email service. We’d want a test that proves that the first-time user workflow works. That could cover a flow through the APIs like this:
- Register for an account.
- Acquire an authentication token.
- Create an email template.
- List email templates.
- Edit an email template.
- Send an email using an email template.
In addition to protecting these important user flows from regressions, these tests are useful as documentation. They also prompt the team to consider the broad impact of what might otherwise feel like isolated feature work. Consider publishing documentation that covers these orchestrations as examples for platform users as part of the system documentation or quick-start guide.
Write tests for the platform features.
In addition to the orchestration tests, individual features should have a robust suite of tests in relative isolation. These tests help cover the complete functionality the team has built within the product. This should include edge cases or parts of an API that are less commonly used or internal, without the overhead of needing to place all of those usages within a larger orchestration and the combinatorial explosion that would probably result.
For example, imagine we’re building an API-only email service. We’d want tests around different scenarios and usages of email templates. We’d want to cover the full breadth and depth of the following:
- Get a list of email templates.
- Get a single email template by ID.
- Search for an email template in the list.
- Create a new email template.
- Delete an email template.
- Update an email template.
Plus, for each of the above, tests should demonstrate handling invalid inputs, authorization problems, system faults, etc. These tests are especially important for platforms. That’s because a platform’s users depend on predictable and clear behavior to build their applications, and the team needs to know when they’ve changed that behavior.
These tests support flexibility in how the platform is used. Because each feature is tested in isolation, any orchestration that uses the feature should get the same behavior from the feature. For example, it shouldn’t matter whether a user called the email template listing endpoint before creating a new email template. The Create Template endpoint should behave the same way regardless of the sequence of calls.
Build an internal reference implementation.
Non-developer stakeholders might find it difficult to engage with platform products during different segments of the feature design and delivery cycle. When a product has a UI covering its primary functions, it’s easier to discuss designs, let others try out new features, and get good feedback from stakeholders. But platforms don’t always have that, and, in my experience, the marketing team doesn’t want to learn how to use Postman or curl to make HTTP requests.
A reference implementation can help solve many of these problems.
Building a reference implementation simply means building something realistic on your own platform. We don’t have to overspend on visual design, scalability, etc. Rather, we should build something that makes use of the platform in the same ways that another developer would likely use it. Give stakeholders access to it so they can experience the platform more concretely. Use it to demo new features, and use it to explore and illustrate platform design options.
Similar to the orchestration tests, this also prompts the team to solve the issues likely to come up in realistic use cases for the platform. Done robustly, reference implementations can even help the team understand the platform’s performance and scalability. They shouldn’t be the only tools deployed in that space, though.
Share the reference implementation.
Teams that go to the effort of building a reference implementation or are looking for more value to justify its existence might consider sharing the reference implementation more broadly. You could use it as a sales demonstration tool, published for potential users to explore, or shared as a code repository for implementors to reference. Publishing the reference implementation may require additional polish in the UI, code structure, and tests, but it could be a worthwhile investment to expand the value it provides.
Partner with a first implementor.
When a team can create the opportunity to do so, partnering closely with a first implementor can help provide grounding in the real usage of a platform. It’s the ultimate test. Building toward that implementor’s needs assures that at least one real use case is satisfied, with the caveat that the team will need to guard against overspecialization to meet the specific implementor’s demands. This relationship requires the implementor to be flexible and open to potential refactoring and API instability, so make sure they’re on board before embarking on that journey with them.
What else is unique about platform products?
I’m sure that these are not the only practices that could help a software platform development team thrive. I’d love to hear your thoughts in the comments: What other practices help teams deliver platforms effectively?