#35 - Lessons from API Communication

Learn Communication Hacks and Tips from API Design

---

Intro

An API illustrates the basics of communication and aspects we should consider. Let's explore an example of designing an API and applying its principles to real-world communication.

A product manager wants to design an identity verification flow for this example. The basic scenario is:

Given a new visitor wants to join our product
When she signs up
Then we will verify her identity
And block the registration if it wasn’t verified

When designing the new flow, we must adhere to various use cases. Let’s learn about each use case and apply the analogy to real-world communication.

The Verification Service is Down

The engineering team proposes an architecture where they will build a new verification service with which the authentication service will communicate.

They ask the Product Manager what should happen if the Verification Service is down (not available). Here are some possible scenarios -

Given a new visitor tries to sign up
And the Authentication process attempts to verify her identity

When the Verification service is not available
Then the Authentication process will try again for up to 10 seconds

When 10 seconds have passed without a successful result
Then the Authentication process will allow the registration
And it will send an email to the Compliance team

The Product Manager applied a retry strategy (try again for a defined time) and a fallback (if it fails, allow the registration with a warning notification).

Analogy: When someone doesn’t respond, don’t assume they’re ignoring you; they might be busy. Retry and consider a fallback (e.g., “If I don't hear back, I’ll assume you agree and proceed”).

Reliance on Third-Party Services

While building the new service, the team decided to rely on third parties for identity verification.

To mitigate risks, they considered several approaches:

• Implement timeout: Wait no more than 10 seconds for the third-party response.

• Error handling: Define behavior for unexpected errors.

• Backup provider: Implement an additional backup service to reduce risk.

Analogy: You must provide a project status update involving other teams (third party). Prepare for this dependency and create a strategy.

• Define the schedule: Like a timeout, let others know when you expect their updates.

• Interim updates: Like error handling, share the current status and address unexpected issues (e.g., “This is the current status, but I will have the final version tomorrow due to an unexpected delay with team X”).

• Escalate to other members: Like backup providers, if the primary person is unavailable, other team members can fill in.

Handle Delays

When testing the new flow, the team found the average verification time was 5 seconds. To improve user experience, they switched from synchronous (API-based) to asynchronous (event-based) communication. They also created a more user-friendly UI to show progress and handle account creation actions.

The Product Manager updated the scenario -

Given a new visitor wants to join our product
When she signs up
Then we will start a verification process for her
And will show a friendly loader until it’s completed

When the verification is completed
Then we will show its result to the user

When the verification status isn’t available after 10 seconds
Then the Authentication process will allow the registration
And it will send an email to the Compliance team

Analogy: If someone doesn’t respond promptly on Slack, consider sending an email (similar to asynchronous communication) and wait for a reply. Alternatively, subscribe to offline updates on projects, tasks, and tickets.

Improve Performance

The team noticed that verification always fails for some countries. Further investigation revealed these as high-risk countries where they wanted to block verification. They decided to skip third-party checks for these requests to improve performance, enhance service performance, and save API calls.

Analogy: Analyze the questions you receive and find ways to decrease response time, like -

• Projects: Bookmark links to all relevant documents in the Slack channel.

• Template Responses: Use a clipboard history tool for common responses to FAQs.

• Meeting Notes: Keep links to notes, slides, and relevant info handy for quick reference during meetings.

• Change Log: Maintain a log of decisions and updates to quickly answer questions like “When will this project launch?” or “What did we decide on this?”

Rate Limits

After a series of load tests, the team recognized that the third-party API had rate limits and throttling limitations. To tackle this, they decided to:

• Rely on a backup provider if they reach API limits.

• Use a Batch API to send verification requests in bulk every 2 seconds.

These decisions impact user experience and overall product implementation (e.g., cost and failure points), and the Product Manager must understand them well.

Analogy: Each conversation and medium has its limits. Be mindful of how focused others are and how often you communicate. Examples:

• Meeting Fatigue: If everyone is on their computer and losing attention, acknowledge it and take a short break.

• Move to Online Conversation: If you haven't resolved the issue after a few minutes and dozens of messages on Slack, consider a quick online call.

• Batch Requests: Sometimes, it's better to wait until you have a list of questions, then review them all at once instead of sending them individually.

Conclusions

APIs are a fundamental form of communication essential to the internet's functionality. Similarly, internal communication can either propel an organization forward or cause delays. By understanding and applying principles from APIs, we can enhance internal communication and improve overall efficiency.