0:0030:17

API Design and Architecture

Preethi Baskaran 30:17 2021

Your API change can take down a consumer who deployed nothing

A consumer's service suddenly starts failing although nothing was deployed, and an endpoint that used to be blazingly fast turns slow, all because the producer kept adding data to the API. Uber software engineer Preethi Baskaran shows how API design decisions turn into other teams' outages, using a simple movie ticket booking flow. If even booking a ticket and sending a confirmation email can fail in several ways, what should a producer design for?

Learn the contract, data-exposure and latency practices that keep API consumers out of outages

Watch on YouTube

In short

Preethi Baskaran, a software engineer at Uber, explains how to design APIs for microservices from the consumer's point of view. She covers clear contracts (granular signatures, error codes, optional fields and versioning), the trade-offs of exposing data through RPC versus data streams using a ticket booking example, and practical ways to meet latency agreements.

“First is your endpoint can only be as fast as the slowest downstream.”
“So there is, just because we made this asynchronous, doesn't automatically get rid of the fact that there can be service crashes. You need to retry.”

What you will learn

  • Design granular API signatures that make required and optional fields explicit to consumers.
  • Return distinct application and internal errors so callers know whether retrying will help.
  • Decide when a breaking change needs a new API version and keep no more than two versions alive.
  • Compare RPC and event-stream designs for failure modes such as crashes, failed retries and database backfills.
  • Audit a slow endpoint for missing timeouts, parallelization, indexes, read replicas, redundant calls and caching.

Key takeaways from the speaker

  • API design
  • System architecture
  • Microservice API design

Details

Level
Intermediate
Format
Tech talk
Technical depth
Practitioner
For
Early career, Mid-career, Senior individual contributor
Length
30:17
Published
June 2021

Questions this talk answers

When should an API be versioned?

When a change is not backward compatible, such as making an optional field required or changing a field type like a seat number from numeric to alphanumeric. She advises keeping at most two versions and migrating consumers before starting a third.

Why do error codes matter so much in an API contract?

Application errors such as authorization or ticket already booked tell consumers not to keep retrying, while internal errors such as a database write or network failure signal that a retry may succeed.

When should data be exposed through RPC rather than a data stream?

RPC suits real-time responses such as confirming a booking, while data streams like Kafka or RabbitMQ suit asynchronous work such as sending the confirmation email.

Does making a flow asynchronous solve service crash problems?

No. A service can still crash between writing to the database and publishing a message, so retries and failure handling are still needed; she prefers a dedicated module that publishes only the external events consumers need.

How do you fix a high-latency endpoint?

Audit every downstream call and set timeouts, split bloated endpoints into smaller ones, parallelize calls where possible, remove redundant calls and introduce caching wisely.

About this talk

Best practices and guiding light for API design in microservices. In this session you will learn how to design REST APIs to be easy to understand for anyone consuming them, future-proof, secure and fast!

Topics

Related talks

Browse the library