Learning from Giants #2
JWT and API tokens, NoSQL data modeling, Building product judgment, Stripe's Payment APIs design story, and a secret management technique.
👋 Hi, this is Mathias with your weekly drop of the 1% best, most actionable, and timeless resources to grow as an engineering or product leader. Handpicked from the best authors and companies.
Did a friend send this to you? Subscribe to get these weekly drops directly in your inbox. Read the archive for even more great content. Also: I share these articles daily on LinkedIn.
An Opinionated Survey of API Token Techniques
JWTs aren’t a silver bullet.
As a software engineer, you probably know what JWTs are. But have you ever asked yourself if they were the right fit for your problem? How much do you know about their alternatives?
JWTs have become the go-to API token implementation for a lot of companies because:
They're standardized: there's an IETF working group and multiple RFCs
BigCos like Google & Apple widely use them.
They have an excellent library ecosystem due to 1. and 2.
Yet apart from JWTs there is a multitude of really good API token schemes:
Unreasonable: username & password
Boring (which doesn't mean bad): random tokens in a database
Somewhat complex: platform tokens, i.e. encrypted user data
Hipster: PASETO (Platform-Agnostic SEcurity TOkens) & Protobuf Tokens
Token-less: Cryptographic signature of requests with a secret key
(Too?) smart: Facebook's CATs, Macaroons, and Biscuits
📗 Fly.io's API Tokens: A Tedious Survey enumerates all of these token schemes to solve the API token problem: "How can I authenticate and identify users calling a set of API endpoints?". It's a visibly passionate, opinionated, eye-opening article.
After starting with the usual boring options, Thomas Ptacek goes on a rant against JWTs before writing a detailed introduction to Macaroons and their cousins. He then ends with a scorecard of solutions, rating their safety, hipsterism (yes! :), complexity, flexibility, and scalability.
Lot of wisdom in the conclusion too:
"I continue to believe that boring, trustworthy random tokens are underrated, and that people burn a lot of complexity chasing statelessness they can't achieve and won’t need, because token databases for most systems outside of Facebook aren’t hard to scale.
"A couple months ago, I’d have said that Macaroons are underrated in a different way, the way Big Star’s “#1 Record” is. Now I think there's merely underrated like the first Sex Pistols show; everyone who read about them created their own token format. [...] I’d hesitate to recommend them for a typical CRUD "application."
"But, don’t use JWT."
NoSQL Data Modeling Techniques
NoSQL does not mean anything. It's particularly true as the SQL language itself is becoming popular again. More and more databases that aren't relational are exposing SQL interfaces.
So I guess "SQL database" doesn't mean anything anymore either. Let's call them "relational". And for the lack of a better term, we'll keep NoSQL as a shorthand for "non-relational".
But telling which is the one true SQL isn't today's topic. I want to talk about data modeling.
Most schools still teach relational data modeling, so most of us can turn any problem into a relational schema. Foreign keys, joins, all of these are known concepts. Yet this doesn’t apply to NoSQL databases.
"NoSQL data modeling often requires a deeper understanding of data structures and algorithms than relational database modeling does".
I believe learning these can make you better at relational data modeling too! It never hurts to know what index tables are and how they work. By not allowing all operations whatever the cost (like SQL), NoSQL databases force you to treat them like white boxes instead of black boxes.
"Relational modeling is typically driven by the structure of available data. The main design theme is "What answers do I have?""
"NoSQL data modeling is typically driven by application-specific access patterns, i.e. the types of queries to be supported. The main design theme is "What questions do I have?""
📗 Ilya Katsov's NoSQL Data Modeling Techniques is a great read that will send you down many conceptual rabbit holes. After defining what NoSQL means and listing a few different NoSQL databases, Ilya describes 17 data modeling concepts that will change how you see such systems!
PS: Again, a good indication of a great read. Check out the article's References section. It's a gold mine of quality content.
Building Product Judgement
How can you be good at Product if you don't have strong Product Judgment?
If you're an engineer, designer, user researcher, product manager, or in any leadership position and have to make product decisions, do not panic!
"Product Judgment does exist, and it is learned."
"No one starts out with strong Product Judgment. It is not innate. It takes years to build, and therefore ranges from very weak to very strong. It takes deliberate work and dedication to build it."
📗 Intercom's Product Judgment: How some people can repeatedly create product success explores one of the most critical and understated characteristics of the best product people. Paul Adams explains why these people just seem to get it. How they have built domain and product intuition, and how you can do too with this simple trick:
“Product Judgment is obtained through direct experiences with customers."
But how many customers should you talk to before you start to get it? While learning is a continuous process and thus you should never consider it done, Paul tries to give a ballpark answer:
"To build strong Product Judgment in a specific domain, the answer is at least over 100 customers. For true proficiency, built over the years, you're looking at talking directly to many hundreds if not over 1,000 customers."
So stop what you're doing and start talking to your customers! It is probably the most impactful thing you can do for your company and career.
Stripe’s payments APIs: the first ten years
"Keep it simple, Stripe"
The $95 billion company runs on two powerful API abstractions: Payment Intents and Payment Methods.
But that's not what they started with. They initially had Charges and Tokens.
"Successful products tend to organically expand over time, resulting in product debt. Similar to tech debt, product debt accumulates gradually, making the product harder to understand for users and change for product teams."
Unlike user interfaces, changing APIs requires careful consideration, planning, and a lot of user empathy. You can't just change the name of a field 2 million customers, most of them probably not full-time software engineers, rely on.
You have one shot per 2-year period.
When Stripe scaled out of the US market and started to add more payment methods (3DS, iDEAL, SEPA...), they first tried to make Charges work for these use cases. But soon, forcing all workflows onto this abstraction they designed for Credit Cards resulted in confusing integration.
"It’s as if we were trying to build a spaceship by adding parts to a car until it had the functionality of a spaceship: a difficult and likely doomed proposition."
📗 Stripe's Stripe’s payments APIs: the first ten years tells how the company went from Charges and Tokens to Payment Intents and Payment Methods. Michelle Bu details the first attempts at patching Charges, the realization that overloading them was not going to work, and the path that led Stripe to the current Payment Intents API. A proper look inside what it took for such a company to change foundational aspects of their product. Even more impressive when you know how fast Stripe was growing during that time.
Simple is beautiful, but it's also tough to achieve.
Completed Staff Work: a powerful management technique
Manager: I often have to challenge my team's decisions. How can I give them more autonomy?
Team member: I'm tired of long back and forth when I require leadership approval.
"When I was introduced to the concept of Completed Staff Work, I felt like I had been handed a secret management technique. [...] The idea simply exploded how I thought of my work as a leader."
"Completed Staff Work is when you present your plan to a decision-maker, and they can just give it a thumbs up to approve it. If they say, "sounds great, do it!" then it's Completed Staff Work."
📗 Jade Rubick's Completed Staff Work is one of these simple, timeless articles that will give you a powerful tool for the workplace. Whether you have a decision to submit for approval or are approving many, you should be able to position your team and make progress on "the scale of how people talk, from being a follower to being a leader." Moving up this scale will significantly impact your team's autonomy.
Completed Staff Work is also decisive for the gaps it can help you identify.
"On the other hand, situations in which you aren't able to give the go-ahead represent a coaching opportunity. What did they miss and why did they miss it?"
Reply to this email to react, recommend articles, or just give feedback!
See you next week!