Dieter Rams’ 10 principles of SaaS API design

For those of you who’ve spent time at design school, or even just walked past the halls of one, you’ve probably heard of Dieter Ram’s 10 principles of industrial design. For anyone who’s spent the odd decade or two building online and SaaS products, you’ve undoubtedly mediated a good many engineering debates on software design best practices. Engineers too, have their own lexicon of deep lexicon and idiomatic principles of software design.

Product leaders, you sometimes can’t help making a few cross-disciplinary conceptual connections. I’m not sure if old Dieter (who’s still kicking btw) has ever spec’d out, say, a payments API, but if he had…

Dieter Rams’ Design Principles
Core Principles Good API design
Good Design Makes a Product Useful – A good product must have utility and always balance form with function.

Before all other considerations, firstly your API has to do something useful. I like to say, an API is just a messenger. Don’t shoot the messenger if the real problem you have is that you haven’t yet built some useful services the world needs to be served over an API. Then to make that service useful, the API needs to offer the right granularity, call sequencing and inputs/outputs that at least minimally enables the solutions your customer will want to build.

If you’re having difficulty getting customers to integrate your API (or any new product), usefulness is the  assumption you really need to validate first – before assuming any other aesthetic re-working will solve your problems.


Good Design Is Innovative
The possibilities for innovation are not, by any means, exhausted. Technological development is always offering new opportunities for innovative design.
Innovative design always develops in tandem with innovative technology, and design can never be an end in itself

 

Great SaaS APIs unlock your customer’s ability to innovate, by being really good at one thing, so they don’t have to be. Innovation is cumulative, and engineering advances through useful layers of abstraction. Every good API a little giant for others to stand upon. Innovation also means differentiation, and avoiding commoditization. If there are many others already like it, what new value are you creating?

Conversely, good APIs are not led by Resume-Driven-Development. Be careful of the occasional impulse to leap upon new fashionable platform/language/frameworks etc as and end in itself.

Good Design Is Aesthetic – The aesthetic quality of a product is integral to its usefulness because products are used every day and have an effect on people and their well-being..

An aesthetic API picks a clear, readable, self-documenting style and is consistent. An elegant software design avoids ugly quirks or hacks to be effective.

A good API will steer (and not arbitrarily restrict) API users from making good design choices in their implementations. Aesthetic, UX tested reference apps or implementations can go a long way to set a bar or exceptions and help implementers make good choices. All of which will ultimately best improve changes success with end users and adoption.

If all else fails, just make sure your developer-docs site has a cool chill-wave vibe and renders well when viewed in ‘dark mode’.

Good Design Makes a Product Understandable – Good design leverages affordances, it can make the product clearly express its function by making use of the user’s intuition.

Good APIs are well documented. Starting with having accessible (preferably public) documentation. And that the API’s behavior actually matches what’s in the documentation and the examples (Sounds obvious, but surprisingly hard in practice to maintain). Good APIs themselves should be self describing as reasonably possible. Sure, ‘naming things’ is known as one of the Hard Problems in computer science. Nonetheless, endpoints, methods, parameters, and returned results should strive to use intuitive names that convey their purpose and functionality.

Following familiar conventions (like standard REST and JSON) makes APIS understandable and reduces the learning burden on developers. Consistency is Key across your API products, rather than forcing developers to relearn different idiomatic patterns arbitrarily. Next best practices are having language-specific examples, ‘recipes’ for different solutions, SDKs if applicable, mock/sample apps to demo and test capabilities.

Good Design Is Unobtrusive – Neutral, allows user expression.

One of the main reasons we build APIs as abstraction layers to our backends is to give flexibility to the front end implementation. A non-leaky abstraction is unobtrusive. A good API doesn’t force awkward or unnecessarily restrictive design choices for the front end. Good APIs can be opinionated about proper useage,  Minimizing  foot-guns and generally making it harder to use the API poorly. The art though is an inevitable tension between designing an API that is broad enough to support many use cases but exposes excessive complexity, data and surface area than is strictly needed for any one use case. Vs trying and failing to create a perfectly scoped API that becomes too narrow or restrictive to  support some important but newly discovered use case.

What I love best, is to design a clean set of versatile primitives. Each service simple on their own, but composable and flexible to serve diverse customer segments, usecases and solution types.

Good Design Is Honest – Truthful about product capability.

The Principle of Least Surprise Software should behave in a way that is least surprising or astonishing to its users. In terms of capabilities and performance, this means that a system should accurately represent what it can and cannot do, and how well it performs. 

Be up front about Beta vs GA readiness of your service.  You’d be surprised how much less concerned your customers are about absolute levels of uptime, performance, bugs vs what they experience relative to the initial expectations you set.

Good Design Is Long-Lasting – Avoids being outdated quickly. It avoids being fashionable and therefore never appears antiquated.

Extensible and Maintainable – Designing and launching some new feature is like the exciting ‘kitten’ phase of software ownership. But remember, the real cost is that, that you could now be on the hook for feeding and changing the litter box on this once-cute feature for years more to come.  Software must always be maintained, patched and supported. And you need to build with that in mind. Similar to durability, Throw-away work and tech debt happen, but try to be intentional vs accidental about it. You often end up living with those choices longer that originally imagined.

Don’t break your Customers – Allow your customers’ investments in your service to be as durable as reasonably possible. Good APIs should be extensible without breaking or requiring onerous re-integration and re-testing by existing users. New features should be optional rather than required, and existing users should see forced version updates rarely as possible. (protip: But maybe also include some contractual sticks/carrots to keep your customers from forcing you to support legacy versions beyond all reason 🙂

Good Design Is Thorough – Care in every detail. Robustness Principle or Postel’s Law: “Be conservative in what you send, be liberal in what you accept”. This means an API or data system should strive to be as accepting as possible of the input data it receives (while still ensuring security), and follow standards strictly when sending data or communicating outward.

Errors and Exception Handling Matters: Sweat these details in the requirements. Your API should provide meaningful error messages that help developers understand what went wrong when a request fails. A lazy API spec focuses only the happy path, leaving  other paths as ambiguous or undefined.
Good Design Is Environmentally Friendly – Conserves resources, does not deliberately or incidentally externalize costs and harms.


Literally environmentally friendly – not wasteful in use of resources, including memory, CPU cycles, and bandwidth. Both benefiting infrastructure costs of scaling and direct environmental impact of energy use.

Mindful of the Compliance, Security, Privacy Environment –  For example, a mindful API doesn’t ask for, nor return any private data not strictly needed for the usecase, and adequately protects any private data that is.

The digital, social and economic environment – a responsible API designer would not single-mindedly help drive-up online clicks and engagement, but while also incidentally undermining western liberal democracies in the process.  

Good Design Is as Little Design as Possible – Purity & simplicity.

The ideal API asks for only what it needs, and returns only exactly what is needful

Similarly, a nice API is not overly chatty, requiring more round trips (each round trip adds more latency, more resources, more things to code and debug) than should be necessary.

Of course, easier said than done. Rare to get the above perfectly right on the first release of an API spec, nor is it even reasonable (or desirable) to necessarily predict all future use cases for your web service. Nonetheless, ‘as simple as possible, but no simpler’ is an important ideal. Versatility and flexibility are also valuable, but I always like to think of anything that drives complexity, as a budget to spend carefully and to continually re-evaluate.

Generally, the less complexity you need to effectively get a job done, also creates less surface area you’ll have later for bugs, exploits and maintainability. The less complexity debt you assume now, the faster you’ll be able to iterate and innovate on your product in the future

 

Posted in Product Management | Leave a comment

How AI will reshape product teams in 2024

  1. leaner teams – Generative AI is pretty great, at a lot of generalized PM tasks. Anything that’s boilerplate or commonly used across organizations: product requirement outlines, commonly used frameworks, agendas, role descriptions, typical project plans. PMs often struggle to find enough time to write content and copy, or internal or external audiences. GPT can absolutely help with first drafts of user documentation or help content. It can also help you spin up, more personalized copy, implementation guides or docs in greater breadth or depth than you could otherwise ever do unaided. GPT and others are about 80% great at the basic stuff. It’s also pretty helpful (like in the sense of Wikipedia or google searches in the old days) for quickly learning, at least superficially, a fair bit about nearly any well-established technical, business or industry topic. And, having to know/learn a little bit about everything, is half the job product management. Generating basic code can be handy too, esp if you are a little rusty as a PM. Code interpreter can help with generating SQL or Excel VBA scripts to pull or scrub data. Up to and including kicking the tires your own or 3rd party apis with simple prototyping without fully distracting the engineering team.

    Of course, LLMs are still (and I can’t stress this enough) terrible at creating ‘new’ knowledge. Generative won’t help you much with anything that was never in it’s training set. To be sure, Sam Altman’s stated goal is to create an AI that can truly invent new ideas and new knowledge. But don’t expect that to change in 2024. You still need humans to bring true insight, to separate the salient signals from the noise and to actually innovate. In theory though, today’s AI should be allowing you a little more time in your PM’s oft-harried days to actually do that.

2. New tooling – I love tools like Otter.ai and Gong that can do remarkable jobs of transcribing and annotating live internal or customer sales/service conversations, and then turning those into collaborative assets for actionable insights and roadmap ideas. New design tools like visily.ai make it possible to import screenshots to figma. A couple weeks ago, I need a way to better visualize and idea for a client. So I navigated to an archetypal customer website and screen-shotted their checkout flow into an AI-generated figma. And in the space of one cross-country flight, mocked up multiple ways my client’s embedded fintech product could transform that category of checkout experiences.

If you are looking for more, Product school also maintains a moderately updated list AI-driven PM tools.

3. Mix Shift to Hard skills – Now lets talk about building AI, not just using AI. For organizations investing in proprietary AI tech, I am seeing engineering and data science leads driving the roadmap and product strategy. Somewhat less, for now, is the primacy of the UI/experience focused PM. It used to be, the riskiest assumption in tech was, if we build it, will they come? With AI though, the riskier, more expensive feedback loop is going to be can we build it? From data sourcing to training, tuning, retrieval augmentation and scalable inference – good AI is not trivial to build. And even when you can get good results can you manage for safety, compliance, un-good edge cases? AI than some of the past waves of web and digital tech. More of your engineering backlog is going to be consumed by engineering challenges, technical features, as well as more platform engineering and  data science. We’re also likely to see more product teams led by engineering or technical leaders.

Can AI replace your product team 2024? Well hardly, but I’d hope it’s helping them work at least 10-20% smarter and more efficiently as well as helping them be stronger generalists.

Between  the above effects of efficiency and mix shifts I do see likely change for the size, process and composition of product orgs. You may see a higher working ratio of engineers and data science to traditional PM roles. Some PMs will start to feel a little un-tethered if their skill sets are less well matched now, or more of the roadmap is increasingly out of their hands. It’s a good time now to have those career conversations with your team. Change can be hard, but everything is learnable, and the future is perennially something we’ve barely started to invent yet.

Posted in Uncategorized | Leave a comment

How do you get Big Banks to integrate your SaaS product faster?

A triumphant bank product manager

Signing big customers is hard enough, but it’s only half the battle. There’s an adage in fintech startups – banks can take longer than you can stay solvent. Especially in the current market. I’ve built SaaS products that could take one customer just weeks to go live with, and another customer literally 18 months from signing. Expecting regular project meetings, integration support from you all along the way. 

When a big customer lags on going live, it’s not just lost revenue opportunity. It’s also likely a significant cost in distraction and resources supporting that customer in their integration project. Resources that could have been better spent in getting after the next customer and the one after that.

Here’s a few of the recommendations I’ve provided to my own advisory clients and portfolio companies when they (inevitably) encounter problems with customer integration delays.


Support my work and get these posts directly to your inbox:


Pricing Strategy Sticks and Carrots

The goal here is both to create a better sense of urgency, and practical deadlines for your customers. But also to help you de-risk when you can start seeing, at least some, recurring revenue from each new deal. A key insight here is that most customers don’t think their project is going to be the one that goes off the rails and gets delayed, so some of these are easier to negotiate into contracts than you might think.

Start your recurring billing clock at time of signing. Make sure you have a component of your billing (a minimum volume, a monthly/annual license fee) that is recurring, not tied to volume, and that starts either immediately at signing, or within a fixed time from date of signing. 

Charge for integration support. Set a modest but reasonable integration fee. You may waive it, particularly for first-mover customers, but set the value of integration support in the minds of your customer. But then also make it a metered or recurring fee.

Cap integration support. Don’t let difficult customers drain your resources indefinitely. Whether you waive it initially or not, set an expectation that your team will provide a fixed amount (in hours, or for 30 days etc.) of support. If the customer needs more than that (intentionally or otherwise) then let them pay for incremental cycles of support. 

It’s not just about the one-time integration. Set expectations in your contracts clients will have to keep up with your future versions, including any reasonable level of retesting or reintegration over time. You can also build in provisions for ‘extended support’ where your service fees escalate in price if clients can’t keep up with some minimum reasonable upgrade cadence. 

Pricing incentives. Helpful  for unproven early stage products or network-value products. Provide pricing incentives for customers going live early, for participating in beta testing but also contingent on going live.

Air Cover

Arm your champions inside the customer’s organization. Think of your job as to make your main champions inside the customer look like geniuses to their peers and get them promoted. 

Do the customer’s job for them. Give them fill-in the blanks business and ROI models. Sample project plans. Sample test plans. I used to always build a mock bank app (see dogfooding) both as a test harness, UX testing tool and demo my own SaaS products, but ALSO as a reference implementation to share with customers

Support all the stakeholders. This one should have started early in the sales cycle. But it means having resources to help your customer team talk to legal, security, regulatory, ops, finance etc. There will be common questions/concerns everyone has, arm your champions with ready-to-go tools, collateral and answers.

Don’t forget the product as soon as it’s launched. Make sure they don’t forget to actually communicate, promote and actually use this fancy product they just worked so hard to buy and integrate from you (I’ve seen it happen). Help them with marketing, communication examples and templates, post-launch best practices to drive usage, metrics and reporting to provide feedback.  Put marketing clauses and potentially associated budget expectations in contract. As well as your ability to publicize the work/case study it.

Sometimes the contract can wait. When it’s not the technical integration but the commercials/legal, don’t let client legal be a blocking factor. You can start integration without final paper. It’s not the best practice but I’ve actually gotten major banks live in prod with an integrated product before all the final contractual and redlines were sorted out. Which means it can be done!

Design, Dogfood and iterate your Integration Experience

Clean API design. This means following and not breaking (without good reason) standard patterns like Restful API and well formed JSON. Be consistent. Try to make your APIs, data types and validation standards feel like they came from the same author and engineering philosophy. Conway’s law will creep up on you, but try not to make understanding your own organizational structure and history not your customer’s problem.  

Developer Friendly Sandboxes. Inline your sandbox with your developer documentation. Allow developers to test and learn api behaviour within the online docs themselves. Provide samples across multiple common languages/frameworks. Try to deploy all your products to shared sandboxes to better enable developers to test and experiment with creative solutions, potentially composed of multiple products/apis. 

Dogfood and iterate on your integration patterns. Build a mock customer app and integrate your service to it. Document your experience doing that. I’ve gone so far as to hire a third party shop to attempt to integrate an early version of your product, only using your first draft documentation. You will learn a LOT from that experience. 

Use generative AI. It’s actually pretty easy to train/embed an LLM on your product and integration documentation. Use that to help you more quickly spin up integration collateral, even highly customised for specific customers and usecases. Use that as an internal tool/refference, or just expose that LLM directly to customers as part of your toolset. GenAI can also be quite useful for generating synthetic test data. If done well, synthetic data helps to solve for privacy, security and compliance problems of how to test against realistic production data – without actually using real data.

Keep as much server-side as you can. Generally, the fewer the lines of code, data or logic the client has to own the better. Lower surface area means, less to build, less that can break, is easier to secure, version control and maintain later. For SDKs in particular, what’s the bare minimum of static code that needs to live client side or as native-ap code vs code can be loaded dynamically at runtime? You can update and improve your server side code continuously, with a big enterprise client, you might be lucky to get them to come back and upgrade your integration more than annually. 

Do the customer’s UX research for them. I’ve mocked up a big banks mobile app and UX tested and optimised the user experience with 3rd party research reports to back it up. Double bonus here, saves your customers time, and mitigates risk of big banks over-complicating or just mucking-up the end-user UX (which you just know they are wont to do)

Pave the elephant paths. For better or worse, your first integrations tend to be all hands on deck affairs. Engineering, product tend to be deeply involved. Bugs are found, key assumptions have to be corrected, gaps in documentation needs to be sorted out, new onboarding processes invented as you go. But your goal should be to make each new customer smoother than the last. Hopefully after just a few, you are handing over a repeatable playbook over to dedicated (and more scalable) support teams.  Make your integration machine continuously better, faster and lighter with each new customer. Track KPIs on integration speed and resources consumed to know if you are making progress. 

What’s your take?

Do you love these suggestions, hate them, have even better ideas I’ve failed to mention? Leave a comment and let me know.

If you enjoyed this bit of product wisdom, artisanally authored by a real human, consider subscribing to my substack, updated semi-periodically with more such gems of digital sagacity

Posted in Uncategorized | Leave a comment