API design and cross-border collaboration - part one
Computers across the world communicate at scale using APIs. So I was curious to find if API design could also be used to improve team collaboration.
Remote Communication Challenges
It is intriguing to debug collaboration when you are distributed across different timezones. Whatever doesn’t fit in the data cable must stay behind, for better or for worse. And there's at least three factors I've noticed we may be taking for granted when getting into an online call:
nuance: you may miss out on at least half of the body language depending on the camera angle, tone of voice, facial expressions, and timing delays
time: it may feel like you've just spoken to them, but actually a ton of time can pass since the last call you've been on
distortion: your conversation may have mutated since you last spoke, especially if other collaborators are involved. Given nuance and time, you or your partner may have progressed down an unexpected direction
Given the three factors above, the job becomes 1. reducing the difference in information between persons A and B and 2. managing this successfully over time.
Long distance collaboration has been in practise all the way back since smoke signals, and has been solved for computers. Are there any lessons we can take from how computers communicate? Maybe the most important one is: be as intentional as you can.
Introduction to APIs
APIs are one way computers communicate. They stand for Application Programming Interfaces. You can use APIs yourself to talk with a computer, but more importantly to get many computers to work with each other. Jeff Lawson, former Twilio CEO, has written a very approachable book introducing them.
He uses banking as an example in the book. “Nowadays your bank is a mobile app and you like your bank if the software is fast, if it is bug free and if they regularly update it with new features and functionality that makes your life better”.
APIs are business models now. You can place a whole company - with hundreds, thousands of people - behind a set of APIs. APIs can very quickly be improved on in the background, served to many users and even get piped to other APIs.
Here are examples from Stripe and from Shopify (I’m not associated with them). These recipe books with sharp technical commands don't need UI updates, language translations or meetings for them to work. Each API section could be maintained by one or multiple teams and changed many times a day.
Examples:
Check your Stripe balance : GET /v1/balance
Get a list of your Shopify customers: GET /admin/api/2024-07/customers.json
These APIs are purposefully created to handle internet scale volume and speed, and whatever doesn’t fit in the API pipe must stay behind.
When you use smoke signals to signal danger to your tribe, attacks to your army, or a new pope, the recipients already know what it means from a preset list of answers. That's how you scale communications with APIs.
This is an excerpt from the Wikipedia page for smoke signals I found too interesting not to include:
"
Misuse of the smoke signal is traditionally considered to have contributed to the fall of the Western Zhou dynasty in the 8th century BCE. King You of Zhou was said to have had a habit of fooling his warlords with false warning beacons to amuse Bao Si, his concubine.[4]
"
Talking to other machines for fun
Time for a practical example. We’ll use your phone to get a custom notification using the same internet verbs that APIs use and adapt.
Download ntfy on your phone for this part. (I’m not associated with them). This will let you receive push notifications for free on your phone. It's free to use on public channels - for our purposes it's perfectly fine.
Think of a title for your channel. I’m picking chocolate_chip_pancake.
Whilst I’m working on embedding this, you can still try it in a very simple app I built here. Now make sure the title/topic is spelled the same way, and fire away! Sure enough, you will be able to receive your first ever self-made notification.
The code for the app is here. There is more discussion of ntfy here.
!WARNING! The app is not really using an API call! APIs themselves simplify and hide other tools that enable their job. For this app, the more low level tool being used to send a request to ntfy is cURL.
cURL takes care of delivering the message efficiently and securely, then showing you the server's reply. Connected software everywhere makes use of these lower level tools to work. In this case, the ntfy server does the rest of the work of piping that message to your phone as a notification.
You can try this code yourself in a terminal:
curl -d "It’s pancake time! 🥞" ntfy.sh/chocolate_chip_pancake
-d specifies there is data to be sent. This fun practical example illustrates:
how APIs work in everyday life and how easy it is to get started with them
the role of servers: behind every request you make to an app, there is a server waiting to answer
real-time notifications: you can start seeing how much information APIs process in real time like in this case to deliver your every-day messaging
Applying API Principles to Collaboration
Setting up a meeting cadence is just the tip of the collaboration iceberg.
You will also have to accept you will not have perfect communication.
This is a given for APIs. Between the art and science of designing one, integration, and deployment - API communication failures are not exceptions, they are the rule.
How can we relate what we learned to cross border collaboration?
Communicating is the 'easy' part 😮💨
Setting up the team to understand what it means is not!
How can you make sure your team's knowledge is growing positively over time?
Does your team work unite under a clear common vision?
Be intentional:
Intentionally communicate priority
Intentionally communicate nuance. Be open to more openly expressing how you're feeling or how you think the other person is feeling to compensate for the lack of body language, tone and timing information that you cannot get in a call
Intentionally communicate how you want the other person to mentally prepare. Do you want a critical evaluation or creative collaboration? Think about it in terms of the six thinking hats example here
If it's a difficult task to collaborate on, aim to complete it together with your partner in one go. It is worth booking a separate, longer meeting as long as you are clear about what you want to accomplish
Shorter loops:
Use async communication tools like docs to shorten the loops of communication and provide a compensatory effect for teams who are working at different speeds or timezones
During intense projects, look to balance focused, uninterrupted work periods with more frequent, clear moments of collaboration
Be relationship-driven
It is key to understand how you can best enable the rest of your team to do well
What makes me indispensable to my team? How can I amplify this even more?
What work that I create benefits my whole team the most? How can I do more of that?
Look to understand your working styles. It doesn't take that long and adds visibility to positive dynamics you can reinforce and frictional dynamics you can diagnose
What is important about how we want to work together?
How can we best support each other?
Create contracts
Understand yours and your team-mate's differences and commit to valuing them and integrate them effectively
What specific habits do you want to practise together?
How much time should you expect between responses given your time zone difference?
Be prepared for communication to fail - it is not a matter of if but when
Specialise and separate delegation when possible
Do not leave conflict to chance. In most situations, conflict is about unblocking the use of limited resources, so see it as another side of collaboration.
Do you have a good process to handle conflict? Here's a great example
Smoke signals eventually become noise
All you know is based off past memory. How can you keep an open mind to new information? How well can you adapt to it?
Can a 3rd party help you make sense of a conflict?
Give the benefit of the doubt more often than you normally do. This will help you overcome noise in your communication and collaborate more effectively in the long term.
Next up: API Design Principles Applied to Remote Collaboration
This is a taster of what we will cover on the next article:
Why do modern APIs look the way they look?
REST
Design principles for REST APIs