Have you heard of Opinionated Defaults ?

In the realm of API design, the principle of "Conventions over Configuration" paves the way for a powerful concept: Opinionated Defaults. As Shoutrange, we are proud to share that we are one of few, if not the first, that came up with and defined the idea in the context of API Design.

What does “Opinionated Defaults” mean ?

In the context of API Design, we define "Opinionated Defaults" as the practice of decreasing the number of required input fields and adjusting endpoint behavior based on the most common use cases of the real world integrators. This can be thought of the API equivalent of usage of default values and flows in UI design, but it is simplifying factor is much more bigger and important since APIs are by nature more complex than UIs.

This approach aims to simplify the developer, and by extension user experience by offering sensible defaults that work well for most use cases right out of the box, thus reducing the initial complexity and decision-making required from the developers integrating with the API. Using this approach you can reduce the Time to First Call (TTFC) or Time to First Hello World (TTFHW) metric, which is a critical indicator of API quality. We re-define this metric a little differently, as Time to First Live Integration (TTFLI), which will delve into later in more detail with another post.

Here is a real world example:

Lets say you have to design an API endpoint. Business teams provided you with a backend API and that API has a complex body that requires the following fields and all the fields in it are required.

{
  "sourceAccount": "DE97500105170000000001",
  "targetAccount": "GB90NWBK00000000000001",
  "amount": 500.00,
  "currency": "USD",
  "transactionMethod": "EFT"
}

Lets assume that your backend supports various transaction methods and currencies but you know from your previous data that almost all of your transactions are made using EFT and are between USD accounts. “Opinionated Defaults” design culture principle says that we should make “currency” and “transactionMethod” fields not required and use the most common values as default if any of these fields are not provided. So that the request input API can be as simple as this:

{
  "sourceAccount": "DE97500105170000000001",
  "targetAccount": "GB90NWBK00000000000001",
  "amount": 500.00
}

Now lets discuss, what benefits this approach brings.

Benefits of Opinionated Defaults

• Opinionated defaults dramatically simplify the API learning curve. Integrators are greeted with a setup that works "out of the box," reducing the need to wade through extensive documentation or make complex configuration decisions from the get-go. This user-friendly starting point is especially beneficial for newcomers, allowing them to dive into development without the intimidation of endless options.

• We are protecting the integrator from the business-specific complexities of our domain. Not everyone knows and cares about the monetary transaction types. Most integrators prefer hands on approach when integrating to an API, expecting APIs to be so simple that he/she does not even need to read the documents. This approach enables them to do just that.

• The approachability of APIs with opinionated defaults is a game-changer for integrators. By eliminating the paralysis of choice that often accompanies configuration-heavy setups, these APIs make it easier for users to get started and achieve early successes. This smoother onboarding process is invaluable in accelerating development timelines and fostering a positive initial experience with the API.

• In addition, by incorporating opinionated defaults, API designers effectively steer users towards best practices. These defaults are not arbitrary; they're crafted from the API team's extensive experience and understanding of the most secure, efficient, and reliable usage patterns. This built-in guidance helps ensure that applications built on these APIs are set up for success from the start.

In conclusion, “Opinionated Defaults” in API design represent a thoughtful balance between flexibility and guidance. By reducing complexity and emphasizing best practices, these defaults not only expedite the development process but also enhance the overall security and reliability of the applications they power. As the digital landscape continues to evolve, the adoption of opinionated defaults in API design stands out as a strategic choice for developers aiming to maximize efficiency and usability in their projects.