Brendan Callum, engineering manager for the Pinterest developer platform team, discusses the “spec first” approach to API development and how it’s different from “API first.” Brendan speaks with host Kanchan Shringi about the challenges and advantages of adopting the “spec first” approach based on the launch of the v5 spec at Pinterest. The discussion explores learnings from the launch, internal APIs, team structures and approvals, as well as deprecation of APIs.
Show Notes
- Episode 387: Abhinav Asthana on Designing and Testing APIs/
- Episode 383: Neil Madden On Securing Your API
- Episode 376: Justin Richer On API Security with OAuth 2
- Episode 143: API Design with Jim des Rivieres
- Pinterest Developers
- Pinterest Developers – Introducing API v5
- developers.pinterest.com/docs/api/v5
- LinkedIn/brendancallum
Transcript
Transcript brought to you by IEEE Software magazine.
This transcript was automatically generated. To suggest improvements in the text, please contact [email protected] and include the episode number and URL.
Kanchan Shringi 00:00:16 Welcome all to this episode of Software Engineering Radio. Today we welcome Brendan Callum to the show to explore the “spec first” model of API development. Brandon is the engineering manager for the Pinterest developer platform team. Pinterest is a visual discovery platform and social commerce network with a mission to inspire. Brendan has also led other engineering teams at Pinterest. As a technology architect and strategist, Brendan specializes in helping organizations scale to match rapid growth. Welcome to the show, Brendan. It’s really great to have you here today. Would you like to add anything else to your bio before we get started?
Brendan Callum 00:00:55 No, thank you, Kanchan. That was great and I’m very excited to be here today to talk about “spec first” development, so let’s get into it.
Kanchan Shringi 00:01:02 Awesome. Just a couple of things before we jump in. I’d like to mention a few related episodes we have done in the past: Episode 387, Abhinav Asthana on Designing and Testing APIs; Episode 383, Neil Madden on Securing APIs; and 376, Justin Richer on API Security with OAuth2. I’ll put these links in the show notes. So, Brendan, what is the “spec first” API approach? How is it different from “API first”? Maybe you could start with explaining what is “API first” and then explain what is “spec first”?
Brendan Callum 00:01:40 Sure, yeah, great. Yeah, I see “API first” as sort of a product strategy or philosophy and “spec first” design — or “spec first” co-generation, as we’ll get into — as kind of a practical or tactical way to put that into practice. So, if you’ve got alignment from your product team, which is not always easy to get, but if you do and you have understanding that APIs are a powerful way to grow and scale your product, then the next thing that’ll come to mind is how do we actually make that happen? How do we ensure that the APIs we deliver and launch live up to our product goals, that they’re consistent and high quality? And “spec first” is, is one way to organize the process of development to ensure those kinds of outcome? Yeah, so I can talk a little bit more about how “spec first” works or some of the details there.
Kanchan Shringi 00:02:34 Absolutely.
Brendan Callum 00:02:34 Absolutely. So yeah, getting into it one level deeper, when you think about the different aspects of what an API is, one of the things that we often did in the past is kind of start with the business logic and work backwards from there as to what the specification or the interface should look like for partners. And when you do that, you often end up with an API that isn’t consistent with the rest of the endpoints that you’ve already released that meets the business goals internally, but maybe doesn’t make sense externally. And you’ve already made decisions as to how the wiring and the business logic should work. So, you’re kind of boxing yourself in to what the interface should look like. “Spec first” says no, like, first things first is how is a client of the API, how is a consumer of the API going to experience what you’ve built? What is their request going to need to look like and what kind of response should they expect? And then, everything internally that happens from the business logic perspective and on the back end is secondary to that. And that allows us to answer questions like consistency and standardization early in the process, rather than having to kind of at the last-minute figure that all out and throw out a bunch of work. So yeah.
Kanchan Shringi 00:03:49 Did you happen to have any example of being not consistent before you started on this spec-first approach, and what was the issue?
Brendan Callum 00:03:57 Yeah, great question. So, a lot of this was actually driven from partner feedback too. So, this is not our first current, as we call it v5 of our public API. This is not our first attempt at building external APIs. I’ve been at the company for almost about eight years now and I got to see some of the first iterations of our external APIs back in 2014, 2015. And we’ve continued to evolve and build and learn from our partners. And one of the biggest things that different developers would tell us is that they had a really hard time predicting how the API would behave from our documentation. They’d read the docs for one end point, and they’d tested out and it would tell a completely different story. And likewise, they learn how to use one set of endpoints for one use case, say campaign management and ads analytics.
Brendan Callum 00:04:51 And then they’d want to expand their application to call some of our other endpoints maybe around shopping. And when they would do that, they’d see a completely different design pattern, a different set of standards for how the interface works, sometimes even different rate limiting mechanisms. And so, what they’re really asking for was consistency, predictability, and not having lots of kind of undocumented changes that cause them to thrash and break their apps. Yeah. So, we considered all that feedback when we were launching this new version of the API, and we decided that we really need to flip our development process and we need to have a consistent set of core reviewers who look first at the spec design and the quality of the interface that we’re presenting to partners. Do the timestamp fields here and the formatting of this request match the kind of conventions we’ve landed on for our other APIs? So, are we doing request batching in the same way that we are across these different endpoints? And things like that need to be front loaded in in the process.
Kanchan Shringi 00:05:59 Makes sense. A follow up question on that is, so that did require a change to the process as you mentioned. Did that require other changes to the team structures, org structures, any kind of cultural changes you needed? Did you have to overcome objections or any hurdles?
Brendan Callum 00:06:18 Yeah, definitely. Definitely. So, I alluded to this a little bit at the beginning. “spec first” is kind of a tactical process for how to build an API, but you do really need product buy-in and buy-in at different levels of the company because not every team and product use case — depending on your business and what your goals are — not every team might naturally think of an external API component to how they build their products and how they reach their customers, right? So, part of our team’s role is to evangelize the potential and the possibilities of working with the API platform. And it’s really, if we go to those teams and we say here’s all this great stuff you can do, but there’s this really lengthy, convoluted, complex process for building and iterating and getting stuff out there, we might get past the product teams, but the engineers are going to look at that and say, well, we can’t prioritize this, or we don’t have the resources to do this.
Brendan Callum 00:07:17 So, we knew that part of enabling this change and getting people to buy in “API first” was making this process really easy, right? If you follow this standard open API format for defining your spec, if you use the linters and guidelines and recommendations we have for how to build and structure your endpoint, then the rest of this process will be really quick and easy. In terms of other process changes, I also mentioned earlier that we wanted to have a core group of folks, of engineers and some product folks and tech writers, who could do a lot of the spec review part, right? This is similar to kind of generic code review, but it’s with a specific eye to consistency across the whole spec. So, you might have a product team who owns like a shopping feature and they’re adding a new endpoint.
Brendan Callum 00:08:08 They’re not necessarily going to know everything else about what’s in the spec and what’s out there for partners, right? They might follow your guidelines, they might build something pretty great, but it shouldn’t be on them to read and understand the entire product space that’s out there for partners to use. So, one of the process changes we made was to form this core review group, rotating review group, to catch those kinds of things and do a partner-centric like consistency review of those spec changes. And because we’re doing the spec changes first and the spec is written in an open API YAML format, it’s not quite the same as reading complex business logic code or backend code, we can have maybe a broader audience of technical or technical minded folks who can contribute to that review group as well and kind of spread the burden across a larger group of folks.
Kanchan Shringi 00:08:59 That said, Brendan, did you encounter any cons of this new approach? Any examples of something that actually went wrong?
Brendan Callum 00:09:06 Yeah, that’s a great question. Of course, we’re always, as engineers, we’re always thinking about trade-offs. And I think it’s not necessarily a con, but there’s definitely a healthy tension between maximum consistency across the entire API surface versus designing, like, a single endpoint for a very specific use case, right? If an engineer is given the freedom to really only think about that one narrow use case, they might choose to do things a little bit differently versus having to slow down and think about, well, yeah, this might, in a vacuum, this might be the perfect option for this endpoint, but we already have 10 other endpoints that do something similar, so how can we meet in the middle here with our approach, right? So, I wouldn’t qualify that as a con necessarily, but it certainly adds a little bit of time to the review process to ensure that we have that consistency.
Brendan Callum 00:09:57 I guess the trade-off there is if you don’t do that and we kind of go back to the model we had previously, then it’s really a free for all and partners are just left holding the bag, right? They’re the ones who have to figure out, well this specific API has this one very arcane way of doing things and this other one is completely different. And some partners will go along with that journey with you because the value is there, and the interest is there and the will is there. But if you really want to scale and grow a sustainable ecosystem, that’s not the right way to go about it. At least, that’s not what we think.
Kanchan Shringi 00:10:30 So Pinterest actually had a specific “spec first” launch, I think you mentioned v5 of the API. What have you learned since the launch, both internally and externally and how did this learning come about?
Brendan Callum 00:10:43 Sure. Yeah, always important to take the time to kind of be a retrospective as we continue on this learning journey, API development journey. We launched v5, as you mentioned, which is the current available version if you go to developers.pinterest.com and look at our API documentation. We launched it in a limited beta at the end of last year, 2021, and then kind of went officially GA earlier this year in 2022. It’s already become our biggest API in terms of number of daily active apps and developers. And we’re also looking at daily active users, endpoint usage, and kind of overall impact on some of our business metrics and goals. And that’s, we think, in no small part due to the way we opened up the API and allowed kind of any interested developer to get started quickly and easily.
Brendan Callum 00:11:39 And the benefits from the “spec first” approach, so I mentioned earlier how one of the things partners were asking for is predictability. Well, with the “spec first” approach, we’re able to deliver just that, right? Because the spec is the source of truth and we generate our handler code, our server code, based on that spec, what partners see in our documentation is it’s the same code that our API server is using to validate in parse requests. So, there’s no more kind of guessing and wandering around in the dark hoping you’ve got the right request format. On the flip side, some of our previous existing partners who had already invested a lot of time and energy to understand our previous versions of the API with all of its eccentricities, they now have a potential migration at hand, and we hope there’s a clear incentive for them to do that with the new version and all the new development that’s happening. We also just launched an API sandbox and our first ever Pinterest official SDKS and client code. So, we’re hoping to incentivize all those existing partners to move to the new version.
Kanchan Shringi 00:12:48 Could you talk about some internal learnings as well?
Brendan Callum 00:12:50 Yeah, sure. One thing that we’ve really observed from launching this new API and now having a bunch of different product teams across the company build endpoints and, and work with our platform, Wikis, docs, written best practices are great, but IDE tools, validation rules, linters are even better, right? So, bringing the best practices and the guidance into real concrete actionable rules for developers. So, and also bringing it right to where they’re actually doing the development work has been huge. So, for example, one of the tools we use a lot in API development is VS code. There’s a number of plugins and things that can assist with open API development and working with spec files in that tool. And we also use a linter tool, an open-source linter called Spectral, to write those rules and help validate the specs. So those have been really important for helping people learn and guiding them on the right path, so that when it comes time for code review, we’re not going back and throwing out everything they’ve written and asking them to start over.
Kanchan Shringi 00:13:55 Do you have any other feedback from partners that you’d like to share?
Brendan Callum 00:13:59 Yeah, this is less feedback and more just another observation of, kind of, so we talked a lot about the technical changes. One of the new things with v5 was actually opening up signups to anyone, right? Obviously, you’ve got to have a Pinterest account and register on the site to use the API, but our previous like external APIs were very invite-only, kind of white glove service, and we weren’t really sure we could scale them and open them up to a wider audience without lots of challenges. So v5 was built with that scale in mind. One thing that we’re consistently learning and relearning is that you can never really lower that barrier to entry enough for folks who are maybe developing their first API app, right? So, our previous set of developers and our audience, maybe we could take some concepts for granted, like, hey, everyone knows how OAuth 2.0 works, in general, right?
Brendan Callum 00:14:55 Which if you’ve ever worked with OAuth 2.0, it’s a lot, right? And so, we’re consistently trying to add different kinds of docs, tutorials, code samples. We even had a teammate write an interactive tutorial on Glitch. I don’t know if you’ve ever messed around with that app, but it’s kind of a way to put up different code and apps and let people remix them and see all the source code. And that’s gotten a lot of great reviews from partners who are maybe learning OAuth for the first time. So, offering different kinds of resources for folks who have different levels of technical background and experience working with APIs is a great way to get to just broaden your audience and get more folks involved.
Kanchan Shringi 00:15:37 That’s a lot of very, very useful information there, Brendan. How do you actually get this feedback? Do you reach out to the partners? Do they reach out to you? Do you have a process?
Brendan Callum 00:15:47 Yeah. That’s another great question, right? Like you launch US API, you invite people to sign up, you’ve got some metrics internally, but how do you get that qualitative feedback from partners who are, that’s so valuable, right? Like I think as an API developer, you might not necessarily have the same signal that you get from someone using a web tool or a mobile app, right? And so, figuring out what was the experience for the developer as they were learning your API, as they were testing things, what does the raw set of request logs and traffic that you have internally not show or cover, right? So it is really important to think about how you can capture that. One of the things we’ve done really well since launching is, for each kind of new iteration or feature for the API, we will try to do it in a limited beta fashion first.
Brendan Callum 00:16:35 And so, we’ll open it up for interest and we’ll also proactively reach out to some of our partners who have registered or shown interest in the past, get a small and but large enough group but still manageable to kind of come on board with testing it and get early access to the feature. And then, they have a more direct connection with our product team and our program managers throughout the life of that beta. And we can get that valuable feedback directly. And we also encourage, as much as possible, we encourage our product engineering teams to sit in on those sessions, right? We don’t, as the developer platform team, we don’t necessarily want to be the bottleneck or the single conduit for all developer feedback to come into the company. Like, it’s great when the shopping teams and the monetization teams, and the other teams across the company can sit down and hear firsthand how developers are using their endpoints in their products. We also just recently started a developer community, so that’s a place where folks can go and start asking questions. We’re in there looking at questions, but also, we hope to grow that community more so that developers can share experience and best practices and things with each other. And it’s not just a one-way street from Pinterest down. And of course, we rely on a really great customer success and support team that’s answering kind of like reactive problems, questions, issues that come in through our help center and other social channels.
Kanchan Shringi 00:18:04 Certainly seems like a lot of learnings. What still keeps you up at night?
Brendan Callum 00:18:09 Yeah, good question. Yeah, I think we, I mean, it’s a good problem to have, but with success, with lots of new developers, with lots of new endpoints and use cases coming online to the API, there’s a challenge of scale and complexity, right? We made a decision when we launched v5 that we wanted to make one consistent API that covers pretty much all of the different things you can do with Pinterest from boards and pins to analytics, to campaign management to shopping. And I think that’s really paid off for us because partners are able to pick and choose the things they want to do and add and adjust really easily if these aren’t separate siloed APIs for them to use. Each new endpoint, each new use case adds to the overall complexity of the system and the API and, how do we continue to keep it simple, keep it consistent as we add more and more things? That’s one of the things that I’m always trying to think about and stay ahead of.
Kanchan Shringi 00:19:08 Let’s now get into some of the details of the design. So the launch announcement indicated that not only every change, but every bug fix, and of course every feature release, starts by considering the impact to the public spec. Do you have an example that we can use to walk through and see how the spec was impacted?
Brendan Callum 00:19:29 Yeah, sure, sure. Yeah, that’s right. It is really a commitment across the engineering and development process. So, one of the things I think that’s critical to Pinterest is, and amazing about Pinterest, is that a pin can really be anything, right? It can be a recipe that you’ve saved that you want to cook tonight, it can be a travel destination, or a new jacket, or a hat that you think you want to check out or maybe add to your wardrobe. And so with all those different kinds of data comes a really complex backend schema or structure for the kinds of data we store for each pin on the platform. Now think about trying to simply and consistently and succinctly represent what that pin could be to an external partner through an API, right? They don’t have all the context on the different data systems that store all of that information, where the images are coming from, how many images or videos are associated with each pin.
Brendan Callum 00:20:30 And so one of the things that the “spec first” process allowed to really clean up and produce a higher-quality experience was around creative formats for pins. So, whether it’s a single image or a product pin or a video pin, when we sat down and looked at what a pin should be in the “spec first,” what the request and response should look like, it allowed us to build a model that separates some of the common schema and shared attributes that go across all pins on Pinterest — so, something like a link, a description, a title — and then tie that with a more flexible media object where we could swap in and out using open API discriminators, different schema to associate with that. So now, we’ve got something that is consistent, but is also flexible, allows us to introduce new creative formats. So, as those product teams experiment and try out new things, we can introduce them to partners and say, hey, guess what? There’s a new pin format.
Brendan Callum 00:21:28 All of the same fields that you and love will be there, but this one is going to have some extra stuff and you can identify it using this same media type discriminator. So that’s one example. I think on the other side, once you’ve created some pins, once you’ve messed around with different parts of the API, one of the first things that partners want to then be able to do is get analytics about how is my pin performing? Is it getting seen by pinners across the platform? What do the impressions look like? What do the clicks look like? Right? And different product segments and use cases within Pinterest produce different kinds of metrics and analytics for those different things, right? A video pin is going to have different metrics than a shopping product pin than just a simple image pin, right?
Brendan Callum 00:22:19 And so starting from the spec again allowed us to identify like a common analytics framework that we could share across all of those use cases. Where was the overlap between product and advertising, and where is the overlap between video and non-video? And are the metric names the same? Are they slightly different? Can we get those teams to agree on a similar metric name, or can we just obfuscate that complexity for partners and maybe simplify it in the API? So metrics is definitely another area where we were able to make things a lot more consistent.
Kanchan Shringi 00:22:53 Were there any differences in designing the API for different person as, so I understand there are creators, then there’s the business users and then the pinners themselves?
Brendan Callum 00:23:03 For sure. Yeah, that’s a great question. Yeah, we spend a lot of time thinking about those different personas across the product, and their goals when they come to Pinterest are different, right? A pinner is coming to the platform to be inspired ,to get inspiration, to find a recipe for what they’re going to cook that night or to plan their next travel or redesign their room. And creators and businesses are coming to connect with those pinners, right? To share their unique products, their perspective, their knowledge, their creativity, and help inspire those people, right? So, they are truly like partners with us in that mission. And so, you know, when we sat down and looked at the kind of matrix of use cases and the different views across the pinner or consumer audience and the business or creator or advertiser audience, we identified a couple of things where there was, like, overlap and that became kind of the initial foundation of the API that the building blocks for this API. So boards and pins are, are really the building blocks of the platform, and they’re a centerpiece of our API as well.
Brendan Callum 00:24:12 Whatever you’re building, whatever the use case is, you’re probably going to start with those endpoints, right? So we know that that’s a common entry point for the API, and we knew we needed to invest a lot of time in getting that design right and making it future-proof and flexible. And from there, once you’ve got your boards and your pins organized and you’re allowing pinners to save stuff and you’re allowing businesses to publish new things and reach new audiences, you can build on that and get into advertising or shopping or analytics. And so, I think it was identifying that overlap area and then building out from there.
Kanchan Shringi 00:24:46 So for the approval process, you mentioned reviewers. Do you envision challenges in scaling this process?
Brendan Callum 00:24:53 Yeah, well we have had a lot of experience now with scale since first launching the API. The developer platform team were the ones kind of bringing this idea to the forefront initially. And so we took it on ourselves to do some of the design work and development work up front to kind of demonstrate to the rest of the engineering team, this is what the gold standard or canonical standard for what we think this API can be and what it can do. But since then, 90% plus of the development work that’s happened in the spec and in the API has come from other teams, right? So, we’ve really shifted from kind of the initial development innovation phase to now being consultants, being reviewers, offering guidance, and enabling those other teams to be successful on the platform, if that makes sense.
Kanchan Shringi 00:25:42 Earlier you had mentioned challenges of, or at least the need to educate your partners on migration and the benefits of doing that. So where are you at now with deprecating older versions?
Brendan Callum 00:25:53 Yeah, that’s a great question. So with the history of the company and the product and our previous versions, we’ve really made some great partnerships and have partners that have invested time and effort in building two previous versions of the APIs. And they’ve gotten value from those APIs and they’ve helped inspire pinners with the content they’ve created and all of the great things they’ve brought to our platform. So, it’s important for us to respect that, to appreciate that, and to make it as easy as possible for those partners to move. So, the first step we knew is, hey, this new API, it can be different, it can be consistent. We can take some big risks and some moves away from things we’ve done in the past, but we know that we have to be able to offer parity in terms of features, in terms of products, with what our partners are used to previously.
Brendan Callum 00:26:45 So we knew we had a couple different product areas we had to cover and support before we could really start beating the drum for migration, right? It’s never too early to let your partners know what you’re planning and thinking. They really appreciate it. Just like us, they’ve got development timelines and trade-offs they’re thinking about and making, and they’re probably integrating to other kinds of platforms. And so, they’re thinking about the work that it will take to migrate your API as well as other APIs and other challenges they’re dealing with. So, giving them lots of heads up and advanced notice is also really helpful. And then when it comes down to it, one of the things we try to do is, and we’ve got a number of these now on the site, is provide migration guides. So, calling out specific differences, calling out some of the biggest changes, and then getting into the details.
Brendan Callum 00:27:36 Sometimes endpoint point endpoint talking about what’s different. There’s a hunger to see that level of detail before partners can really estimate, okay, how much effort is it going to take me to move to this new version of the API? That’s the first question you get is, well, what’s actually different? What’s changed, right? And yeah, so we’ve reached that parity milestone. So, we are now able to offer on the five, a wide range of things that our previous siloed APIs had all in one place. And so now we’re letting folks know that it’s time to move and giving them the resources and the docs and the tools that they need to do that. So that’s kind of where we’re at.
Kanchan Shringi 00:28:12 Thank you for that, Brendan. I’d like to now explore some related API topics, so we can spend a few minutes on that. Open API tooling certainly seems like at the core of your practical approach. You did mention some other tooling as well, but initially as you were evaluating open API tooling, was there anything else that you evaluated?
Brendan Callum 00:28:33 Yeah, great question. Yeah, so launching this new API was a chance to really take stock of what our partners have been asking for and what the options are and kind of where this, the API development world is heading. So, of course, we looked at some other things like GraphQL, but coming back and grounding ourselves in kind of that partner feedback and experience, we continue to see RESTful APIs and open API as a common denominator in kind of our highest priority interface to build that doesn’t rule out possible GraphQL support. It’s definitely something we’re supporting internally for some of our own native clients on other APIs, but it’s for thinking partner-first and what they’re asking for the RESTful framework seems like the right choice. And once you kind of make narrow down that decision open API is a truly Open-Source and open framework that has a ton of tooling, a ton of support, a ton of documentation. So, it was kind of a no-brainer to go into that from there.
Kanchan Shringi 00:29:36 You mentioned GraphQL, is that something used for internal APIs? Maybe let me just step back and ask this about internal APIs. The announcement really focused on public-facing APIs. Does it cover internal APIs?
Brendan Callum 00:29:50 Yeah, good point. Give some context there. So, this API that we’re offering is built, first and foremost, for external partners, right? That is our audience, that is who we’re looking at. That is the audience that is guiding all of our design choices and our approach. Of course, balancing that with security, privacy, and are the APIs we’re offering going to actually help people get inspired and drive our business goals? But internally, obviously, we’ve got a different landscape and ecosystem and so, GraphQL is something we’ve been exploring and will continue to work on internally. So, for things like the Pinterest web app and Pinterest iOS and Android apps, what we’ve seen is a continued desire to iterate rapidly to launch lots of different experiments, as we do on the platform to improve our pinner experience, and to be able to craft more complex joins and queries across different kinds of data to power those experiences. So, those are some of the factors driving the GraphQL stuff internally, but for partners externally, it’s kind of a lower priority at the moment.
Kanchan Shringi 00:31:06 So maybe let’s take a segue a little bit, just talking in general about your internal APIs that you use to support your different clients, browser-based mobile clients. Do you feel any challenges in reusing some of those APIs? Maybe in terms of, chatiness, how much data is exchanged, any general guidelines or experiences in that area?
Brendan Callum 00:31:28 Sure, certainly, yeah, at a lower level with the v5 API and what we’re offering to partners, there is a level of shared framework code across internal and external. And so, it’s not a clean break, but in terms of the representation, in terms of the specification, the interface is quite different, right? And it is a RESTful API right? Whereas internally we’re exploring both, we have both REST and GraphQL options for internal clients. In terms of like chattiness, as you said, and network traffic, we’ve done a fair amount of work to think about how these different clients request data from the APIs, how they can even through REST enable certain kinds of joining techniques. So, are you looking for perhaps a board and a set of pins on those boards and all the users that are associated with those pins, right? If we know that the client needs that joint data upfront, then yeah, how can we craft the right interface and requests to provide that without lots of requests going back and forth. Definitely an area we’ve spent a lot of time, like, optimizing and building on for our internal APIs. Something that GraphQL kind of offers a different approach to right, than a set of RESTs endpoints.
Kanchan Shringi 00:32:47 How do you do this? Do you have KPIs and how do you measure performance?
Brendan Callum 00:32:51 Yeah, so KPIs always. Lots of KPIs, lots of metrics I think we can kind of break them into different categories. One is all about performance, stability, kind of nuts and bolts of how the service, the health of the service is doing, latency, request sizes, things like that, rate limiting. And then, of course, there’s measuring the actual business impact of the APIs, right? We launched an API for conversions recently, which allows advertisers to have a secure way to send us conversion data for all of the checkouts and transactions that are happening on their site. And so, one of the things we need to be able to measure: is that actually helping those advertisers get ROI from our advertising product? Is it actually driving adoption in in the way that we want it to? So, for those things we might have a much more standard set of metrics to measure across the API for kind of performance and reliability, but for each product use case, it is a bit of a partnership to work with those teams to understand, okay, when somebody uses one of these endpoints, what’s the downstream impact?
Brendan Callum 00:34:00 Is it kicking off some jobs down the line later? Do we need to measure adoption engagement after the fact for two weeks later to really truly see the impact? Or is it more direct, right? Is there a direct revenue number that we can tie back to, say, the budget of a campaign that was created through the API? So that’s something that I think we try to call out early when teams come to us to want to build in the API, we ask them what does success look like for you with launching this API? And if we know we’re going to need to capture some new types of metrics or join some different data together we call that out early so we can be ready to start measuring it when we launch.
Kanchan Shringi 00:34:40 Wanted to now focus a little bit on your team structures and DevOps processes as well, and with any emphasis on changes that have happened due to the “spec first” approach. So, my first question is that the announcement mentioned, and I believe you mentioned too, that different endpoints are born by different product teams, and do these teams choose their own tech stack for the API implementation?
Brendan Callum 00:35:06 Yeah. So yes and no, right? So we offer an API gateway and a spec service and request validation and kind of response handling. So, kind of the core of the API layer as a service to them. And that includes rate limiting, authentication, authorization, and then what the API actually does, the business logic, the meat of it, is up to them. There are some standard options, a lot of use cases share like a common backend system. And so sometimes, if a product team is adding something in an existing use case or space, that decision will sort of already be made for them. But sometimes in the course of building a new endpoint, there’s the spec design part, and then, okay, this is the first time the API service is talking to this system. What do we need to figure out? Are there region changes we need to think about? Are there new types of rate-limiting capacity changes? We need to think about what’s a traffic pattern for the endpoint going to look like versus kind of the rest of the API. So, we try to offer a template, but there is a fair amount of flexibility for how those product teams connect the API layer to whatever back-end systems they have.
Kanchan Shringi 00:36:22 So, your role is higher when it’s the first time and then later on that’s more delegated to the team itself, even with related designing the APIs? Is that fair?
Brendan Callum 00:36:32 Yeah, I think that’s generally right. I think if we’re a small team, right? We own the shared resources and the overall developer experience, but having a single API team build every possible API use case with the amount of stuff we’re trying to do and the range of things you can do with Pinterest just doesn’t seem like the right way to scale, right? So, we offer the API expertise and the guidance and overall kind of stewardship of the service, but we really want to get the different product teams engaged, involved, ramped up on what a good endpoint looks like, and then eventually when they build those endpoints, they’re identified as the owner for those endpoints. So that means things like traffic alerts or success rate alerts or other things can get routed to their team automatically, right? So that if it is a backend-specific or product-specific problem, they can look at it and deal with it versus something related to the overall framework.
Brendan Callum 00:37:31 I think what we found is that naturally there are different people across these different teams who are really excited about working with APIs and working with partners. And so, we’ve kind of built initially informal and now starting to be more formalized kind of group of stakeholders, API stakeholders who are not just thinking about their specific use case and their endpoint, but how to make the product better overall. And we welcome that kind of feedback, and we involve them in our planning discussions like we’re doing right now for 2023 planning. And we think that’s a great way to kind of build and maintain those relationships and connections with other product teams so that we can make sure that the service does what they need to do. If it’s a great API for partners, but no product teams internally want to build new features for it, that doesn’t leave us in a good place.
Kanchan Shringi 00:38:21 So, not directly related to APIs though, but these teams, product teams, do they own a complete vertical slice? Meaning, do they have UX designers and UX developers as well on the team?
Brendan Callum 00:38:34 Yeah, good question. Yeah. I would say for the most part, yes, right? So, oftentimes they will have some full stack developers who are kind of launching a new feature across, for example, our ads manager web UI, right? And our external v5 API, right? So, they’re launching a new campaign objective or a new type of creative format in the API and in one of our native interfaces or tools. And so naturally, the first kinds of questions developers have are what is the native product experience for this feature, right? I’m interacting at as a developer through the API, but what does it actually look like when it gets onto Pinterest, right? Can I see an example of that? Can I play around with it on Pinterest? Can I test it first before I build my integration? Right? So, we try to get involved early in that process and identify that kind of information with those product teams. And so, we don’t just want them to produce a spec for us to review. We want to understand a little bit about what the product is, what it’s going to look like, what the design, what the UX is going to look like. And so that’s a really fun part of the job is getting to be really broad and seeing across all these different teams and use cases.
Kanchan Shringi 00:39:51 So who has responsibility for testing? So, unit testing, integration testing across different endpoints, maybe performance, maybe security testing?
Brendan Callum 00:40:02 Yeah, I mean, we’re all responsible, all engineers here at Pinterest. We’re responsible for things that we’re putting out for pinners — to think about privacy, to think about security. I think one advantage of having kind of separation between our external and internal systems is being able to make different decisions about how authentication works, right? A token for the external API does or doesn’t have to work for an internal API or vice versa, right? In terms of testing, we do ask our engineers in general and our product teams to take a lot of responsibility with that, right? So, when they’re coming to us with new endpoints and new spec changes, the responsibility first lies with them to also provide those unit tests and also update our integration test framework. We are lucky enough to have some QA support as well, so some folks that are really experienced in just breaking APIs and testing all kinds of different edge cases and use cases. So, we try to provide that extra layer of coverage. We set the expectation upfront that you own the spec, you own the business logic, and you’re also going to update unit tests and integration tests with changes that you’re making.
Kanchan Shringi 00:41:14 Makes sense. Let’s talk a little bit about hiring and onboarding. What do you look for when hiring developers at Pinterest?
Brendan Callum 00:41:21 Yeah, that’s a great question. I mean, I’ll selfishly talk about what I look for on our team, but I think I can extrapolate that a little bit more generally too. I think the unique challenge and fun of working on a developer platform team is getting to work with developers around the world, right? They’re constantly surprising us with the ideas and the innovation and the different kinds of things that they build on top of our API, and that can be really fun, but it can also be challenging because no day is the same, right? Every day you’re seeing something kind of new. And so, I think there’s a certain type of engineer that really leans into that variety and different type of challenge every day versus maybe sometimes, and I think we’ve all had these different phases in our careers, but sometimes maybe you just really want to go deep in a specific subject area and focus on optimizing or making a certain process or thing more efficient.
Brendan Callum 00:42:20 That’s not really what our focus is day to day. So, we’re looking for developers and engineers who can have a broad range of experience and knowledge and are open to and interested in learning about new things, new systems, new languages, and working with lots of different product teams internally. We obviously appreciate folks that have prior open API experience and can kind of talk to different trade-offs and opinions about how to design an endpoint and what makes a good endpoint. But we also work with folks who come to us from other disciplines and just want to learn and grow. And so that’s one of my favorite things to do is to help grow those folks and mentor them and get them experience with the platform.
Kanchan Shringi 00:43:08 Thanks Brendan that’s quite useful. Trying to start to wrap up now. With all the talk we’ve had on APIs, what do you say to people that might still be scraping on Pinterest?
Brendan Callum 00:43:23 No comment. No, I mean, if you are interested in the data that we have at Pinterest, and as a developer, I think why wouldn’t you be, right? We’ve got this amazing web of connected nodes between boards and pins and folks that are creating content. If you’re interested in helping your customers, your users, or building an app for people that can help them get inspired to help them do real things in their life and go plan that trip that they’ve really been dying to do, then these APIs are made for you and we invite you to come sign up and try them out, and give us the feedback. We’re here, we’re a real team of people, we’re interested and we’re passionate about what we think Pinterest can offer. And yeah, so sign up and give it a shot.
Kanchan Shringi 00:44:10 Anything that we missed that you’d like to cover today?
Brendan Callum 00:44:12 No, this is a lot of fun. Thank you for having me, Kanchan.
Kanchan Shringi 00:44:15 So Brendan, how can people follow you or contact you?
Brendan Callum 00:44:18 Yeah, I invite everyone to join at developers.pinterest.com. Go there, check out our docs, register for an app and we’ll take a look and get you into the program. We also have our spec published to GitHub. So, if you check out github.com/pinterest, there is a number of public tools and repos, like a quick start guide and our first-ever client code, which is Python API client. So yeah, check out developers.pinterest.com, and our public GitHub presence as well.
Kanchan Shringi 00:44:50 That’s good. We can put those links in the show notes. Thank you so much, Brendan. This was very interesting. Really, happy to have you on the show today.
Brendan Callum 00:44:58 Thank you, likewise.
[End of Audio]
SE Radio theme: “Broken Reality” by Kevin MacLeod (incompetech.com — Licensed under Creative Commons: By Attribution 3.0)