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
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!
Granular endpoints make clearer API contracts (70 s)
Error codes tell consumers when to retry (68 s)
Three ways to fix a high-latency endpoint (89 s)
Speaker: Thanks for joining. Before we get started, I just wanted to give an introduction. This session is about API design, so I will be sharing some of the key takeaways and lessons I have learned through both academically as well as at work. What are the things you need to keep in mind when designing an API? How do you think from your consumer's shoes while designing an API?
Speaker: Yeah. I'm Preeti Baskaran. I've been working as a software engineer with Uber Freight. It is very similar to Uber Ryzen Eats. My work here is mostly focused on APIs which deal with search optimization and improving the booking experience for our users. Before that, I was working as a software engineer at Navis where I was working on software Speaker: optimisation for shipping terminals. So most of my experience has been working on the back end side of things, designing and writing APIs. How do we improve the latency? How do we make sure that our consumers are happy with the APIs you provide? That's been my focus area for the past few years, and I thought I have learned a few lessons which I can share with the folks and also learn from you guys.
Speaker 1: Cool. It looks like everybody's able to hear fine and I can proceed. Cool. I hope you can also see my slides. I've not checked that before. Speaker 1: Okay, sounds good. Yeah. So today we'll focus on the big picture. What is the session is all about? What kind of examples we'll be walking through? And then look back at outages. How outages of API designs are related? And then look back at how Speaker 1: How outages of API designs are related. And then we dive into the key concepts and designs you need to keep in mind while designing or updating an API. And finally, you'll have a, I hope, I hope there'll be time for some question answers, but please do keep your questions coming in the chat. I'll probably take it as they come.
probably take it as they come. Yeah, so the big picture is what is API design? So before that, what is API? API stands for Application Programming Interface. It's an expression of functionality. That is, your service could do so many different things. And how do you express it to the outside? Oh, this is what my service does. This is what you should give as input, and this is what I can give you as output.
How do you express that functionality in a clear, concise form, and so that your consumers are not surprised about what are you suddenly giving me, and I don't know how to use your API. So keeping that communication clear is what this API design is all about. So throughout our session, I will be talking through some examples. So to start with, I wanted to keep it very generic.
Let's take a ticket booking app. So assume that I'm someone who owns a theater and I have a tech support team, which designs APIs like book ticket, cancel ticket, update ticket, et cetera. And there are third party platforms like BookMyShow, Fandango, whatever it's in your country. So different platforms to which I can book tickets. So these platforms will be leveraging my APIs to book the ticket or update these tickets.
So in other words, I am the producer or the service owner for these APIs, and they have a bunch of consumers for these APIs. So this is very important to keep in mind, that the focus that I am a producer, and there are a bunch of consumers. So with that first high level example, like how do I represent an API?
So like I mentioned before, API is nothing but a software intermediary, which lets two applications to talk to each other. Like every time you use your phone, you're using a Facebook to send an instant message, or you're checking the weather out. What you're doing is your weather application in your phone makes an API request to different services to get the weather information.
So that's the interface it talks to. So this API itself can be represented in different formats. Like you have Apache Thrift, Ideal, JSON. There are like tons of different ways to just present this interface, just like you have so many ways to write your code. So we'll not go into the internals of these languages and none of these concepts, I'm going to talk about the language specific, I'm going to just keep it at a very, very high level.
So at the same time, I want to give a high level overview of Apache Thrift, because examples I'll be talking through have some reference to Apache Thrift. So I just want to make sure that you don't get surprised at what these languages. So Apache Thrift is a lightweight language, independent software stack. For example, here you have a multiplication service.
So this is my service and API I provide is multiply. And I say that I take two inputs and the output is also an integer. So that's the kind of contract I established by consumers. This Apache Thrift can also take in structs, which are like request structs, response structs, which says these are the request parameters I can take in, and these are the response parameters I can give out.
And similarly, there will also be exceptions, which your API needs to provide when the things go wrong. We'll talk about that later. But yeah, I want to say the caveat that if Thrift is new to you, it's okay, because this presentation is more about the concepts to keep in mind, regardless of which interface definition language you choose.
Yeah, so looking back, exploring outages through the lens of API design. I want to call out that for your consumers, APIs can cause a lot of confusion and misunderstanding that can lead to outages. APIs, it's not just your concern as a producer, but also you need to think about what odd problems it can cause to your consumers.
For example, when API keeps changing, it's inconsistent or unintuitive for your consumers, there could be so many ways by which outages can be introduced. If you look at your service and think about how many outages have happened because of an API difference, I'm pretty sure you'll be able to find a few outages because the API was used to perform when it's not performing well.
So you can just measure that and figure out how much of the importance is API design. But on the other side is what is not measurable is how the effort you put into understanding these APIs. So good API design will help your fellow engineers to, you know, debug the problem and also keep the API consistent so that your consumers as well as the producers have a same life.
So other aspect is that as a consumer, you might realize that there is a lot of migrations happening from your producers and that what the API used yesterday might not be the right API today. Like for example, there's a lot of complexity involved. For example, if there is a new feature to be added, there's a high probability that the producer would start adding more and more data to the existing API.
And as a consumer, you might be confused about, oh, why is it now behaving in a different way? And second thing is reliability. Suddenly your service might start failing and you might wonder, I did not deploy anything. Why is it suddenly failing? It has been the same configuration. Why is it failing? It could be mostly because the API changes something in your end and it's causing an outage on your end.
And latency. Suddenly your API, which used to be blazingly fast, can suddenly become slower. And again, that's because the producer of the API is adding more and more data to it or they have done something internally which causes a lot of latency issues as a consumer. So these migrations are always a pain, but we have to deal with it.
But at the same time, we have to think about different ways to reduce the complexity, making sure it is latency efficient and reliable for your consumers. So, yeah, let's dive into, we talked about different problems. Let's dive into what are the tools and concepts to promote good API design. Yeah, so all the negative examples aside, three main area, focus area for a good API design is clear contracts, establishing the clear way to expose your data and having some kind of service level agreements about what you should expect in terms of latency and throughput from the APIs.
So, yeah, to start with clear contracts, it's very, very important as a consumer to have a very clear signature. For example, in our earlier example, we've talked about update ticket, book ticket endpoints. Say, for example, your update ticket endpoint is used to update movie date, time, available seats, movie name, metadata, everything, you know. So you have a version one endpoint which allows the entire ticket to be updated.
So, for example, here it takes a ticket ID, and then it takes an entire ticket info. So for me as a consumer, it's not pretty clear to me what all this endpoint is allowed to update. So does it update movie date and time as well, or does it update only the seats? It's not super clear to the user.
On the other hand, there's another version two endpoint which is more granular. That is, I say that this is the ticket ID, movie name, movie time, movie seat number. So I know for a fact that these are the different parameters that this particular endpoint is allowed to update. So carrying that kind of clear granular definition helps your consumers to know what to expect from your APIs.
The other aspect of clear contracts is error handling. That is, error is one of the important feedback to callers. This is sometimes overlooked. We don't return correct error messages in our APIs. For example, if you have an application error like authorization error or ticket already booked error, invalid error, it tells the consumer that there is something wrong with this ticket that it's already booked, or this user is not authorized to update the ticket or book the ticket.
So they wouldn't keep retrying on their end, you know, so that gives a useful feedback to say like what I need to do next. On the other hand, there could be like internal errors like writing to database error or some kind of a network error. So that shows to the caller that, oh, something is wrong. Let me retry it again.
Probably it will succeed. So that kind of feedback helps them to take the right action as a consumer. So it's very important to return the right error code for the right scenario as a producer of the APIs. The next aspect is optional fields. This is also a very overlooked aspect of clear contracts is making sure what is optional and what is required.
For example, in update ticket endpoint, of course, you need to get ID without which you cannot update a ticket. So that is considered as a required parameter. But whereas a movie name, time or seat number is optional because a user can update any of these parameters. So everything is considered as optional. So as a user, I know that these are all the required struct I need to pass so that the request succeeds and these are all okay to omit.
So it gives a lot of flexibility for the consumers when there are optional fields. I think the last aspect of clear contracts is API versioning. Like APIs keep changing all the time. You suddenly have some new requirements coming and you want to enhance it. So a lot of times you need to version the API. Just like you have software versions, you need to also have different versions for your API.
And the pros of having these versions is that you can build out new interfaces without impacting the existing clients. And you can also avoid this interface as you wish because there are no clients yet to this new version. So this gives you a lot of flexibility as well as not affecting your existing customers. But of course, there are cons as well.
That is, you need to, at some point, you need to migrate your existing clients to use a new interface because it's not realistic to keep maintaining two different versions all the time. So there will be some kind of overhead until all your clients migrate to the new version. But API versioning helps for you to, you know, make sure that you're not overloading the existing endpoint with too much functionality.
And your users, end users are also not suddenly surprised about why things have changed. So when do you do this API versioning? When you have, like, you have to add or remove one or more fields. That is, for example, for, say, by looking at ticket, the last name of the user was optional for some reason. And now you suddenly want it to be a required field.
So it's not realistic for your consumers to suddenly always pass a field because it was an optional before. So that would break the API from there. So you cannot do that in an existing API, making an optional to a required field. Or there could be some field type changes. Say, for example, your movie seat number used to be a numeric form.
And now you change the formatting to alphanumeric. And suddenly, you cannot expect your users to change the, send the corresponding data type. So any kind of this non-backward compatible change you're introducing, and if you want your clients to absolutely pass those, then you can have to consider about API versioning. So how do you do it? Unfortunately, IDEALS, that is, any interface definition language will not support versioning directly.
So you need to have different implementation interface files, like myServiceV2.thrift or myServiceV2.json, where you have your new interface and you have a new APIs. So it's, as I mentioned before, I think utmost maintain two different versions so that you don't have a lot of overhead. Once you have the version 2 ready, make sure that you help your consumers to make the version 2 before you move on to the version 3 and so forth.
Yeah. Before I move on to exposing data, I just want to pause here and see if anybody has any questions about establishing clear contracts. If not, I think I can move on to the next topic of exposing data in your APIs. So how does a domain expose data? So like we talked about earlier, we have endpoints, like this could be the trpc endpoint, they could be rest endpoint, drift endpoint.
So these are all different ways to establish your endpoints. You can have an endpoint, say, update ticket, which you update the ticket and gives you the new data back, the updated data back. Or you can use data streams like RabbitMQ, Kafka, which are all queues, which are not real-time. We'll talk more about a realistic example later. So you can use data streams to expose your data or have your data warehouses like Hive, relational, non-relational.
There are so many options. You can have directly access the database to get the data. So these are different ways to expose. So one thing is RPC, another one is a data stream. So RPC stands for Remote Procedure Call. That is, you use this when you want a real-time response. For example, if you say, if the user says book a ticket, you want the response back.
The consumer wants the response back in real-time. That is, the ticket is booked. It's not realistic for the user to keep waiting for the response. So any instant response you get from an endpoint is via an RPC call. So on the other hand, the data streams is for asynchronous operations. For example, again, I'll take the same book ticket example.
When you're booking a ticket, you get a response back that the ticket is booked. But you also need to send an email. It's not, again, practical to make your user keep waiting on the same mobile screen or a web screen waiting for the email. So you process that asynchronously via a data stream. That is true. So that's more like a data stream or offline approach.
So you can expose data both via an RPC as well as a data stream approach. So this could be, like, too many concepts, and it might go overhead. So I would like to just talk with the help of an example. So we'll take a simple flow, like when a user books a ticket through the app, and we want to send a confirmation email to them that this ticket is booked for this movie.
And let's assume that we're only talking about the flow where the user taps the book button and the endpoint returns success, the ticket is booked. That is, we are not considering edge cases like concurrency or the ticket is already booked. Let's not go into that aspect. Just look at the success scenario and just realize how many issues can come up in this scenario.
And the goal here is that the email should be sent within minutes of booking. There is an email service. And if that service goes out of service or there's a downstream outage, it's expected that the pending emails will be sent once the service recovers. And we should never have a booking without an email being sent eventually. So this is like a goal, like a simple user booking scenario.
And let's see different options we can design this and what are the different kinds of issues that come up that you need to consider. Let's take the first RPC approach. That is, in the book, your consumer calls your book ticket API, and then you update the status that the ticket is booked in the database. And you also send confirmation email by calling the email service.
So these both are real-time remote procedure calls. So what is the issue here? What would happen if your service fails before you send the email? Let us, you update the status in the database and your service fails. So that would cause a problem and you won't be sending the email. So one solution here is to add read tries.
So like you need to keep checking whether the email service succeeded or not. But what happens when you're retrying it again crashes. So there are multiple ways this can be addressed. But you need to keep in mind that service can crash at any time. And remote procedure calls need to have some mechanism to keep track of that.
So that's an issue with the remote procedure call where you cannot guarantee that the email gets sent. Let's take another approach. Is this a reverse way? That is, say that your consumer calls a book ticket to your service. You call the email service first and then you update the status in the database. So in this scenario, the issue is, I think you would have expected this, that you basically send the email.
But if your service crashes after sending the email, the status is not updated. So that has a lot of potential liability. It might cause bad customer experience because you sent the email, but the ticket is not actually booked. So you basically need both these operations to succeed atomically or just fail both the actions. So having an R2C call in either way, that is having doing one first and then the other second, will not help in either of these cases.
Let's take a slightly different approach with async. That is, say, book ticket is called to your service and you update the status in the database. And then you make a remote procedure call, like you trigger a background flow to trigger email. That is, you put up, publish a Kafka message to the RabbitMQ or to the Kafka queue.
And the email service reads from this queue. So what is the problem here? I think it's very similar to the first approach of R2C call. That is what happens if the service fails after you update the status in the database and you don't publish some messages to the Kafka queue. So again, there is no way for your email to be sent.
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. And there are certain issues to consider there as well. Now let's think of async email approach in a different way. That is, you are first triggering, you send the Kafka message to the queue and which will trigger the email.
And then you update status in the database. Basically, you're reversing the async approach you saw in the earlier approach. The issue is kind of pretty similar here as well. What happens if you send the email out and then the service crashes? But there are some workarounds here that before sending the email, you can do a double check.
Have I updated the status in the database? If not, don't send the email. You can do some kind of logic over there. But there are, that is something you need to be wary of that just because we made it async will not solve the issue. The third approach with async is, it's still not so great. That is, you update the ticket in the database.
And then after the database write succeeds, you emit events, DB events to the Kafka queue. So this will be your one domain or one microservice. And there's another microservice or another domain, which reads off this Kafka queue and sends the email. But what are the downsides here is that what would happen if you have a sudden database backfill?
Like you were doing some mass update of all the ticket names or ticket timings. So everything would provide a DB update event and you're just overloading your email service to process all these events. And you're potentially exposing your internal DB events to your outside consumers, which is not great. So this is still not a super efficient approach, but it's still better than your previous approach.
Because you're dividing the responsibility into two different domains. This can solve the problem to an extent. And the last thing is, this might be, in my opinion, better than any of the other approaches. That is, it's very similar to the before, that your book ticket service updates status in the database. You send out DB events. And then there's also an create external events module, which will only send out events that are relevant to your consumers.
You're not exposing all the data, all the DB events to your outside consumers. You're only creating specific events which are applicable for this use case. And that you're publishing to the Kafka queue, which the domain V or another microservice reads and sends the email. So in this case, the advantage is that say you're doing some mass backfill to your database.
Your create external events controller or your handler would be able to filter out those events and just send what is necessary. You have some control over what you want your outside world to see. So this helps to an extent to keep things separate and have separation of concern at the same time exposing the data safely. So, yeah.
So the question now comes is, is this a solution, right solution for all our use cases? But the main takeaway I want to point out here is that, no, it is just to highlight the different issues we need to think about. Like what happens and how do we want to handle a service crash or restart? What would happen if a retry cannot succeed?
Or how do we handle database backfill? Or what are the potential issues with database backfill that can cost your service? And what would happen if there is an outage? So these are the different scenarios to think about and have some backup plans. And the other thing is, it might sound like all the RPC calls are bad, but that's another point here.
That is, here I'm just trying to convey that there are some shortcomings which we need to understand. And we should make sure that we're able to use the right tool for the right job. So I will pause here as well if there are any questions. What is the difference between using RPC and REST in terms of synchronous blocking communication?
There is not much of a difference between, again, RPC and REST is very similar in terms of they're both real-time. I would just say they are different ways to implement a real-time endpoint. But both, as you say, they are synchronous and they can block the communication. It's just that some of them prefer RPC, some of them prefer REST, but there's not much difference as far as I know.
Next, I think we are a little short on time. Let's go to the SLA latency. What is service level agreement latency is? Latency impacts our network throughput. You need to have some kind of agreement that this is what my service accepts. This is acceptable latency. If you don't set that expectation right, it could cause a lot of timeouts.
You have frustrated users and less number of consumers. So I would like to highlight things to consider when you have to have this high-latency endpoint. How do you debug? And what are the things you need to avoid? First thing is avoiding, depending on slow downstreams with no timeouts. That is, say, for example, you depend on email service, which takes forever.
You need to have some timeout configured to make sure that your main endpoint is not affected by that. So it's very important to identify the downstream services and their latency. And then parallelization or async work. You need to figure out what parts of the API can be done in parallel. Not every action in an API needs to happen one after the other.
So figuring out what can be asynchronous, what can be parallelized, goes a long way in addressing latency issues. Other thing is, it is very common that your endpoints are doing too much than they're supposed to. Because as your functionality evolves, it's very easy to think to add to the existing service, existing API, because it's just easier. You already have the infrastructure built.
But if you think from a consumer's perspective, the latency might go up a lot, which is not good for your consumers. Other thing is storage. You might suddenly include a new DB index, sorry, new column in your table, but you're not adding the corresponding index. So the query pattern might take a lot of time. So every time you introduce a new change to your database, you need to make sure that you're adding the right indexes, right type of index as well when you're adding new fields to your table.
Other thing is redundant calls is very common than you think. That is, when you have a lot of things happening in your API, sometimes what happens is you're doing the same kind of validation at two different places. So you need to take an audit of what your API does. If it's loaded with so much data, so much information, figure out if you're doing the same operation twice in two different places, and how can you cut those?
And the third is, I think this is not a common problem these days. There's no replicas for reads. I think with AWS and autoscaling, this is kind of taken care of, but it's very important to have replicas for reads. And because cross data center queries can take a lot of time, forcing the reads to primary is pretty expensive.
The other thing is caching. I think this is also a highly overlooked area, though caching is a well-known concept to many of us. So you have to figure out what data our service owns, where can we cache it? For example, if the data is owned to another service, you first read from the service first. And then if the service B fails after certain timeout, you probably have read it from cache.
This would work if you're not super concerned about data accuracy. If the eventual consistency is something you are okay with, this kind of works. Instead of waiting forever for service B to return the data. Similarly, if you have the data your service owns, you can directly read from cache first. If there is a cache miss, then you can read from the database and then update the cache.
So this will also help you to not overload the database deets and use caching wisely can be helpful. Of course, caching can be sometimes difficult to implement in that, you know, you need to make sure that you're able to invalidate the cache at the right, then update the cache. So new to designing a caching solution also has its own, you know, little caveats there.
But definitely caching the right way can help your database latency to go down. Sorry, your API latency to go down. So yeah, coming to these concepts, how do I fix a high latency endpoint? First is your endpoint can only be as fast as the slowest downstream. That is, you need to do an audit of what all your API does and what other services it calls.
You need to do some math and figure out what I can do about that particular call. Should I have a certain timeout? Should I parallelize it? Should I make it asynchronous? Just doing that audit can give you a lot of different options. The second thing is, can the endpoint be split into simpler, smaller and faster endpoints? Like I mentioned earlier, it's very easy to bloat an endpoint with too much functionality because it's just easier and faster to develop.
But we just have to take a call whether, should I create a new endpoint to do this or can I just do it on the existing endpoint? If I just do it on the existing endpoint, what are all the side effects for my consumers? So just having that thought would help you to make sure that your service level agreements are met.
And the third thing is parallelizing and caching wisely. That is, we have to parallelize calls whenever possible. A lot of times your API does too many different things and figuring out where parallel calls make sense can help a lot. Even if you don't go into caching solutions, parallelizing alone can make a lot of difference. So again, introducing a caching layer and then removing the redundant calls.
And I think a lot of this has got to do with auditing your service and figuring out for each of the problematic areas, what can I do? So yeah, that's all I had with the latency. And yeah, thank you for listening to the session. I hope everybody has one or two takeaways from the session.
Transcribed automatically; names checked against the speaker record. Select a time to jump there.
Article based on this talk
How should you design APIs so consumers never inherit your outages?
Uber software engineer Preethi Baskaran shares practical rules for API contracts, data exposure and latency in microservices.
In short
Preethi Baskaran argues that good API design starts in the consumer's shoes. Clear contracts, careful choices about how data is exposed, and explicit latency expectations prevent the confusion, migrations and slowdowns that turn one team's change into another team's outage. She illustrates every point with a simple theater ticket booking service.
Key takeaways
API design
System architecture
Microservice API design
Why API design is an outage problem
Baskaran frames an API as an expression of functionality: what a service does, what it takes as input and what it returns. Her running example is a theater owner whose team builds endpoints such as book ticket, cancel ticket and update ticket, consumed by third-party platforms like BookMyShow and Fandango. The theater is the producer, and the platforms are the consumers, a distinction she asks viewers to keep in mind throughout.
From there she looks at outages. When an API keeps changing or behaves inconsistently, consumers pay for it in three ways: complexity, reliability and latency. Producers tend to keep adding data to existing endpoints as new features arrive, and consumers are left wondering why behavior changed. As she puts it, "Suddenly your service might start failing and you might wonder, I did not deploy anything." (7:00)
She also notes a cost that is hard to measure: the effort engineers spend just understanding an API. Good design helps fellow engineers debug problems and keeps the interface consistent for producers and consumers alike.
Clear contracts: signatures, errors and optional fields
The first of her three focus areas is clear contracts. She contrasts a version one update ticket endpoint that accepts an entire ticket object with a more granular version two that lists the ticket ID, movie name, movie time and seat number. The granular form tells a consumer exactly what the endpoint can change.
Error handling is the next piece, and one she sees neglected: "That is, error is one of the important feedback to callers. This is sometimes overlooked." (9:30) Application errors such as an authorization failure or a ticket that is already booked tell the caller to stop retrying. Internal errors such as a failed database write or a network problem tell the caller a retry might succeed. Returning the right code for the right scenario lets consumers take the right action.
She also asks producers to be explicit about required and optional fields. The ticket ID is required for an update, while movie name, time and seat number are optional, which gives consumers flexibility and clarity about what they may omit.
Versioning without surprising anyone
APIs change constantly, so Baskaran treats versioning as part of the contract. A new version lets a team build a new interface without affecting existing clients, at the cost of eventually migrating everyone. Versioning is needed for changes that are not backward compatible, for example turning an optional last name field into a required one, or switching a seat number from numeric to alphanumeric.
Because interface definition languages do not support versioning directly, she suggests separate interface files such as a V2 Thrift or JSON definition, and limiting the overhead: "Once you have the version 2 ready, make sure that you help your consumers to make the version 2 before you move on to the version 3 and so forth." (13:23)
Exposing data: RPC, streams and the booking email
Baskaran separates two ways of exposing data. Remote procedure calls fit real-time needs, such as confirming that a ticket is booked. Data streams such as Kafka or RabbitMQ fit asynchronous work, such as sending the confirmation email so the user is not left waiting on the screen.
She then walks through one flow in detail: a user books a ticket, and an email must follow within minutes, even if the email service is down for a while, and no booking should ever go without an email eventually. Writing to the database and then calling the email service fails if the service crashes in between. Reversing the order risks emailing a customer about a booking that never saved. Moving to a queue does not remove the problem: "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." (19:50)
Publishing raw database events to a queue splits responsibility across domains, but a mass backfill could flood the email service and expose internal events to outside consumers. Her preferred design adds a module that creates external events, filtering database changes down to only what consumers need. Even so, she stresses that the point is the questions, not a universal answer: how to handle crashes, failed retries, backfills and outages. "And we should make sure that we're able to use the right tool for the right job." (23:18) Answering an audience question, she adds that RPC and REST are both synchronous, real-time ways to implement an endpoint.
Meeting latency agreements
The third area is service level agreements for latency and throughput. Without clear expectations, consumers hit timeouts and leave. Her list of common causes is practical: slow downstream services with no timeouts, work that could run in parallel or asynchronously, endpoints that keep growing, new database columns without matching indexes, redundant validation calls, reads forced to the primary instead of replicas, and caching that is overlooked or hard to invalidate.
Her fix starts with an audit: "First is your endpoint can only be as fast as the slowest downstream." (28:24) From there, teams can decide on timeouts, parallelization or asynchronous processing for each call, consider splitting an endpoint into smaller and faster ones, and add caching and remove redundant calls where they make sense. She warns that bloated endpoints are tempting because the infrastructure already exists: "Other thing is, it is very common that your endpoints are doing too much than they're supposed to." (25:41)
Watch the talk
API Design and Architecture, Preethi Baskaran, about 30 minutes: https://www.womentech.net/video/preethi-baskaran-api-design-and-architecture
About the speaker
Preethi Baskaran is a Software Engineer at Uber, based in Fremont, United States. In the talk she describes her backend work on APIs for search optimization and the booking experience, and earlier work at Navis on software for shipping terminals.
Questions this talk answers
When should an API be versioned?
Why do error codes matter so much in an API contract?
When should data be exposed through RPC rather than a data stream?
Does making a flow asynchronous solve service crash problems?
How do you fix a high-latency endpoint?
Drafted with AI from the talk transcript. Editor review pending.
Frameworks and ideas mentioned
RPC (Remote Procedure Call)
REST
Service level agreements (SLAs)
API versioning
Eventual consistency
Cite this talk
Preethi Baskaran. "API Design and Architecture." WomenTech Network, 2021. https://www.womentech.net/video/preethi-baskaran-api-design-and-architecture