Okay, everybody, I'm gonna go ahead and get started. 0:01 I'm Kirsten Hunter. 0:04 I'll be talking about designing irresistible APIs. 0:05 For those of you who came to my workshop yesterday, 0:08 a lot of this is gonna look familiar to you. 0:10 But this is much more focused on the producer side. 0:13 Creating APIs that are gonna make 0:16 your developers happy, creating a successful API. 0:17 One of the main reasons I like to give this talk 0:22 is I gave a talk at OSCon a couple of years ago. 0:25 And someone ask, asks me a question about about performance and scalability. 0:29 And my answer was, if you don't make it a usable API, 0:35 nobody's gonna use it, and then you won't have to worry about scalability. 0:40 So, what I'm gonna do is I'm gonna try to help you understand 0:43 the things that you need to think about when you're creating an API. 0:48 So that you don't fall into some of the pitfalls that other companies have had. 0:51 I've been working with APIs for about ten years. 0:56 I worked at LinkedIn, I worked at Netflix, I've spent a lot of time supporting 0:59 developers and partners and trying to help them be successful with APIs. 1:06 So this is all based on problems I've seen with fairly large-scale APIs, 1:10 and I'm trying to give you the information about how to be successful. 1:17 My presentation style. 1:25 I'm using Haiku Deck. 1:26 It's a fantastic program. 1:27 It's an iPad app. 1:30 You'll see there will be pretty pictures. 1:32 That are sort of evocative and give you something to think about. 1:34 And there's just a few words. 1:39 I will make speaker notes when I put this on SlideShare, so that even 1:41 without my interpretive dance you can understand 1:45 what it was I was talking about. 1:47 When I put a lot of information and bullets on 1:49 the slides, what happens is, I talk a lot faster. 1:51 I read the slides to you, you read the slides. 1:56 And then it's like story time, and we all fall asleep. 1:59 So, what I want you to do, is I want you to listen to me. 2:02 And I also want you to ask questions. 2:06 I, I love making sure that the information I'm giving you is valuable to you. 2:09 So, at any time, you can raise you hand and ask questions. 2:14 There should be time at the end as well. 2:17 My handle on twitter is Synedra, S-Y-N-E-D-R-A. 2:20 And you're welcome to tweet you're welcome to ask me questions anytime after this, at 2:26 the conference or send me a tweet or an email and I'll be happy to help. 2:32 Okay, so, why do you wanna have an API? 2:37 A lot of the time what people hear is their VP says we need an API. 2:42 And so when asked someone asks you why you have 2:49 an API, the answer is cuz we wanna have an API. 2:51 Okay, so but a lot of companies have gone that route. 2:55 Netflix had the idea of, let a thousand flowers bloom. 2:59 If we make an API, people will use it. 3:02 It turns out, if you don't have a 3:05 directed strategy, if you don't know what the business 3:07 value is for your API, eventually someone in the 3:10 C-suite is gonna say what are those engineers doing? 3:13 And why? 3:15 If you can't answer that question, then you're, it's very possible 3:17 that your API will be killed or throttled back a lot. 3:22 It also makes it harder for you to communicate with your developers. 3:27 How you want the to use the API, what you want them to do with the API. 3:30 So thinking about that stuff ahead of time allows you 3:34 to make an API but is useful for your users 3:36 and also that you can defend to your management when 3:40 they ask you why it is that you have the API. 3:43 So I'm going to go over a few business cases 3:47 so you can understand what the sort of range is. 3:49 Mobile/Market Penetration. 3:53 so, getting yourself on mobile, getting market penetration. 3:57 Netflix is actually a great example of this. 4:01 Not the mobile exactly, but if you buy a device, a television, a DVD 4:04 player, a Roku pretty much anything but an Apple TV, it's gonna have Netflix on it. 4:10 It might have other things, it might have Amazon on it. 4:15 But Amazon has to work a lot harder, 4:18 because everybody expects Netflix to be on those devices. 4:20 Because they were there, they really pushed, 4:23 they work hard with their copartners to 4:27 make sure that they are the de 4:28 facto standard for streaming movies on these devices. 4:30 Drive Usage. 4:35 Twitter Twitter lets you use their website. 4:36 They like you to use their client, their mobile client, but 4:40 what they want is all the content that they can get. 4:45 They want people to engage with the content and retweet it. 4:48 They want you to share stuff that you find elsewhere. 4:51 There's a reason that there's little Twitter buttons, share on Twitter buttons. 4:55 There's a reason why they make it so 4:58 easy for developers to integrate Twitter into their application. 5:01 One of the things that they do is they, they do identity management which allows 5:06 more people to use Twitter, and then start adding to the, to the feed. 5:12 Adding good quality content about what people are thinking. 5:17 Defensive Strategy. 5:21 Okay, so this is, I'm, the example I'm gonna get, give is not exactly about APIs. 5:23 I can give you an API example which is Best Buy. 5:28 They wanted to protect themselves from Amazon 5:31 selling everybody all over the internet electronics. 5:36 With a Best Buy API you can see what's available. 5:39 You can sort of shop for things. 5:42 You can, and it's all very focused on electronics. 5:44 Circuit City didn't do that. 5:49 So who's doing better now? 5:52 And book, the bookstores are another great example. 5:55 So Amazon came along. 5:58 And Borders was like, yeah, whatever. 6:00 That internet thing is never gonna pan out. 6:02 No one's gonna do anything with that. 6:04 Barnes and Noble did a slightly better job. 6:07 They have the Nook, they sort of embraced 6:09 the e-book, as something that was important to them. 6:12 And they did put energy into their website. 6:15 So, now where's Borders? 6:20 they, they got eaten, by the people who were thinking about 6:23 what people were gonna be doing in the next few years. 6:27 Partner connectivity. 6:31 I cannot stress enough how important this is. 6:33 Federal Express FedEx has a lot of 6:38 competition, the US Postal Service, UPS DHL. 6:43 There's lots of people who will deliver stuff for you. 6:46 But FedEx was the first one to have a really good API. 6:51 Once you have caused a, a partner to integrate 6:56 with your system, with your API, they're kind of trapped. 6:59 I mean they could go, but there's more friction. 7:04 It's a little harder for them to leave. 7:06 and, and it's, this is a huge value for your business. 7:09 This might be the only value in your API, and it's huge. 7:11 If you can keep your big partners happy, and you can keep them connected to you, 7:15 and make it hard for them to leave, then your company's gonna do a lot better. 7:20 So, technical cases, Abstraction. 7:27 Reducing complexity. 7:30 In SendGrid, mail is really hard. 7:33 Sending mail, there's a lot of different 7:37 formatting issues, there's a lot of different clients. 7:38 So SendGrid makes email easy and 7:42 that's, that's their business, their technical case. 7:45 Simplify. 7:50 So Context.io also works with email. 7:51 What they do is they work on the client end. 7:54 So, if you have Gmail for instance, your ability to organize, and have activities 7:56 based on the information that comes into your email is, is limited. 8:01 Contacts.io I know allows you to make, make, make 8:06 applications that work with the things in your email box. 8:11 One of the hacks that I keep, keep threatening to make, that I 8:16 think would be hilarious, is, I wanna use contacts.io to look at my email. 8:20 And if one of my relatives sends me something that's on snopes 8:26 or an email that says, here's a chain letter send recipes to 8:29 all these ten people, put your name at the bottom, take the 8:34 name off the top, or you're going to burn in hell forever. 8:36 I don't want to see that email. 8:41 I want it to just leave my mailbox. 8:44 And then I would like it to use Twilio to call them at 8:46 3 o'clock the next morning with a very important message about email etiquette. 8:49 That's how annoying it is to me. 8:54 [LAUGH] probably that annoying to you guys as well. 8:56 Metered Usage. 9:00 Amazon, Heroku, these are companies where they charge 9:01 you based on how much you use the system. 9:06 This is actually a really great model for developers to use. 9:09 It's great that something is free, Heroku desk 9:14 have free tear for a very small amount 9:16 of usage, which makes them great prototyping and 9:18 having a system that is visible to the internet. 9:21 Amazon has, they charge you for how much 9:24 you use the S3 or the or the, the 9:29 service or whichever part of AWS you're using. 9:35 So this is a, this is, this is actually a modernization strategy. 9:41 You'll notice I haven't talked a lot about modernization strategies. 9:45 And part of that is because well, Twilio and SendGrid, or SendGrid and ContextIO 9:48 and Amazon do have monetization strategies that are kind of centered around the API. 9:55 I still say that partner connectivity and some of 10:01 the other values are just as important for your company. 10:03 So, even if your API's not making money, that's cool as 10:08 long as it's contributing to the stability or growth of your company. 10:12 Okay. 10:18 All of the above. 10:18 So, Twilio. 10:19 Twilio will send SMSs, they have metered usage. 10:21 They make things, hard, hard things. 10:26 voice, and, and SMS are actually very hard things to do without an API. 10:30 But also have a, an army of evangelists that 10:34 run around to techathons and help people do it. 10:39 And they have one of the best developer experiences out there. 10:42 Their goal is, if you go to their developer site 10:46 you can make a call, a successful call within five minutes. 10:50 If they don't meet that metric, they try to make their documentation better. 10:54 So, Twilio's money, monetization strategy is their API. 10:57 They don't have any other way of making money, 11:03 They are developer evangelists working in the marketing group. 11:06 But so that's another sort of technical case. 11:10 When you're building an API there are eight architectural considerations. 11:16 Affordances, what do you want people to do with your API. 11:20 You need to think about what, what kind of client do you want people to make. 11:24 Are you trying to make some internal clients and some external clients? 11:31 Are you going to have a website and, and mobile and that's it? 11:35 You need to understand what is important to you. 11:38 If you're trying to drive usage, then you should make 11:41 sure that it's super easy for people to drive usage. 11:44 I'm going through these things kind of quickly, because I'm 11:47 gonna, at the end, sort of give you a process that you can use to 11:52 take these ideas and create an API that is useful, meaningful, and successful. 11:58 Your Schema. 12:05 It's not as important as it seems, I think 12:07 of the schema as important only in that modeling 12:13 your schema deliberately and explicitly, allows you to see 12:16 where there are holes, where you are being inconsistent. 12:21 You want your system to be consistent, easy to use, and, and complete. 12:24 And it's okay for your schema to 12:30 have to-dos, just like in test-driven development. 12:32 It's okay to say, when we get around to doing 12:34 the profile stuff for the users, it should have this architecture. 12:37 In terms of, of, how to organize them, 12:44 I do tend to like it when resources are two levels deep. 12:49 So five plus or minus two is is the amount that people can remember. 12:56 So, you know, three to seven top level buckets and then the things underneath. 13:01 That's actually not important for the usability of your API, but it's 13:07 important for the developers to kind 13:11 of understand how your information is structured. 13:13 And how to think about, creating a product from your API. 13:16 [SOUND] Who Can Do What? 13:23 . 13:25 Okay, a lot of times, people mix up authentication and authorization. 13:26 They use the same word for the sa, both different things. 13:33 So, if I have a driver's license that says I'm 19, that's great. 13:36 It, it identifies me, it's a thing. 13:42 And can I buy cigarettes. 13:44 But I can't buy alcohol. 13:47 All right, so, I'm not authorized to do all of 13:48 the things that someone else with a different ID can do. 13:52 There's different ways to do authentication. 13:55 OF allows the user to use an identity that they've 13:58 established elsewhere and give you permission to act on their behalf. 14:02 In your application. 14:06 One of the things that people don't realize is if, 14:09 if identity isn't one of your core competencies, if you're 14:12 not super worried about security and privacy, it's sort of 14:15 a fun application, you can actually use some of these providers. 14:19 LinkedIn, Facebook, Twitter, you can log in with, a lot of people log in 14:23 with those services, even if you're not interacting with them in any other way. 14:30 This allows you to focus on the core, competencies of your application. 14:34 The more things that you can outsource to other systems, especially 14:40 when you're trying to get, first thing out the door, the better. 14:44 authentication, and authorization, it can be things you can do. 14:50 But it also can be 14:55 how many times you can do them. 14:59 So, most APIs have throttling limits. 15:01 Those throttling limits are based on a couple of factors from the business side. 15:05 Search is usually throttled for a couple of reasons, and 15:10 it's usually more heavily throttled than any of the other resources. 15:13 One reason is it's expensive. 15:17 You can't really cache search results. 15:20 People are going to search on new things. 15:22 So it's going to hit the server every time. 15:25 And that's the same search server that you probably use for your main product. 15:27 So you have to be pretty protective of that 15:31 and make sure that people aren't abusing that resource. 15:33 You don't want to bring down your main product by, by third party actors. 15:37 But the second reason, and something you need to realize, 15:44 especially if you are working with you know, the C suite. 15:48 This helps you protect your data, your data is likely your intellectual 15:53 property, the thing that makes your, your system important to people. 15:59 So by limiting the number of times people can do searches you make it 16:04 much more difficult for people to rebuild 16:09 your database elsewhere and compete with your product. 16:11 Sales people will generally think that if you have an API, everyone 16:15 is going to steal all your data and make a competing product. 16:18 That's very rarely the case. 16:22 If someone wants to do that, they'll scrape. 16:23 and, there's ways to get around that, but, the 16:27 API is not actually a vulnerability in this case. 16:30 [SOUND] So, building a successful API. 16:33 First, your API is a product. 16:39 Your API needs to be a first-class product. 16:42 You need to treat it like, as, as, 16:45 as something that's as important as your other product. 16:48 You need to not try to slap it on. 16:51 Okay so, a lot of times especially in really big 16:55 organizations what happens is people say, oh we need APIs. 16:59 So what we're gonna do is every time a developer makes 17:02 a thing, not only do they have to make documentation which 17:06 they don't wanna do or tests which they really don't wanna 17:08 make, but also they now they have to make an API. 17:12 So usually, they'll like shove it through some library that spits out an API 17:16 that doesn't really have a purpose other than being a check box for that developer. 17:19 That developer's not thinking about the end 17:24 user, use case, they're just thinking about 17:27 making an API because that's on the list of things they have to do. 17:30 They're being measured on writing code. 17:34 Usually they are measured on the quality of there documentation or tests, and 17:37 when we have APIs, they are usually not measured on the value of those. 17:41 So we end up with a potato and a bunch of really 17:46 ugly sprouts, that are not related to each other in any way. 17:50 It's hard to use, it's ugly, and it's not going to be successful. 17:54 I'm gonna talk about API First. 17:59 You'll all be like I can't do that. 18:03 API First is the idea that everything your company does should go through APIs. 18:06 Your website, your mobile devices, any other products, your 18:13 API should be the point of truth for your company. 18:17 That means that if you add a feature to your website, your 18:22 API has access to it as well, your mobile device automatically has it. 18:26 You don't have duplicate code in two different places. 18:30 Worse, is, the, the, the worst part is 18:33 that usually, the duplicate code isn't exactly the same. 18:36 so, the API does things slightly differently and when there's a bug 18:41 in the website, there's probably a similar bug on the API side. 18:44 But but it doesn't get it doesn't get fixed. 18:48 I, I refer to places where the API is not a first class product. 18:54 People who don't use API First as, worlds 19:00 where the, the API is, is sucking hind tit. 19:05 It's the ninth puppy, there's no milk. 19:08 It has to wait its turn. 19:12 And the idea is, developer makes a new feature on the website, great. 19:13 The product is good. 19:18 And then when he has time, do himself, extra 19:19 spare time as all developers do, all the time. 19:24 He's gonna go over and make a meaningful API that meets that same future need. 19:27 That doesn't happen, it's not reasonable. 19:32 And whenever you try to slap an API on as a side thing. 19:36 You're going to end up with bugs. 19:42 You're going to end up with a very difficult to maintain 19:44 API and it's not going to work as well as you'd like. 19:48 So the first thing you want to do is figure out what your Business Value is. 19:53 So I talked about a few different things driving usage. 19:57 Do you want people to. 20:00 Interact with your system more often. 20:01 If it's a social s, sorta site then 20:03 yeah, you probably want people to access the system. 20:05 And, and learn, and, and read and, and write to it. 20:09 So that might be the business value. 20:12 Getting new users, that's, that's a value. 20:15 All, always think about those partners. 20:19 If you wanna be a successful company, you're gonna need to 20:22 partner with and really support some of the larger companies like Microsoft. 20:25 Microsoft, expects well formed APIs. 20:31 They're very smart. 20:35 they, they push really hard. 20:36 So, depending on your business value. 20:39 I mean this is what should happen if you 20:43 stand in the elevator with the CEO for 11 seconds. 20:44 And he says, hey what is it, we have API for anyways. 20:47 Partner integration. 20:51 Driving usage. 20:53 Modernization is rarely what you want from your API, 20:55 but if you have a plan for that, that's great. 20:59 So you have to have a business value. 21:02 And from that business value, you make some use cases. 21:05 If one of your use cases is mobile, that rest potato, is not going to work. 21:10 Because what that rest potato usually ends up 21:18 being is your database schema barfed into REST. 21:21 And a mobile developer wants to make one call per screen. 21:27 They have to deal with the fact that a user's 21:33 gonna walk into an elevator, or drive into a tunnel. 21:35 So they can do a retry if they're making 21:38 one call to get all the information for a screen. 21:40 But they are not going to want to make 21:42 50 calls to get all the information they need. 21:45 So, figure out what your use cases are, what they have to look like. 21:48 Those are the things that should be super easy to do with your API. 21:53 I'm gonna tell you here, following the REST guidelines as you 21:57 understand them is not necessarily going to be what you want. 22:00 You need to understand what your customers want. 22:04 You need to think like your end users. 22:06 And you need to have use cases 22:08 that you understand and that your developers understand. 22:10 And then here is another thing that's gonna help you with that C-suite. 22:15 Measure success. 22:20 What metric are you using to measure success? 22:22 Your business value is usage. 22:25 Great, count how many times people do things on the API. 22:28 Your API is gonna be cheaper than the website. 22:33 If, if there's a configuration, a form on your website. 22:35 And you have an API, maybe what you're gonna measure is what 22:40 percentage of, of changes to the configuration are made by the API. 22:43 And maybe we're gonna try to drive more to the API. 22:49 It's cheaper, it's actually easier for your partners to automate. 22:52 And when I say partners in this case I'm also talking about third party developers. 22:55 You wanna, even if they don't have a, a 23:01 monetary contract with you, you wanna treat them like partners. 23:04 copy. 23:11 There's some really fantastic APIs out there. 23:12 They might not be exactly like yours, but you can 23:15 learn a lot by looking at APIs that are successful. 23:19 Twitter's a great example. 23:22 They're, they're developer portal is really strong. 23:23 Sometimes you want to have authentication and the best 23:28 way to do that is to use existing libraries. 23:32 Don't try to build everything from scratch. 23:35 Go ahead and use other API's if you need to. 23:39 Just be aware of the vul, vulnerability that you have and have 23:42 a strategy for what you will do if that API goes away. 23:46 The developer experience. 23:51 This is one of the things that will drive the success of your API. 23:53 And I'm not just talking about external APIs, I'm talking about internal APIs. 23:57 Even, I would say it's even more important for internal APIs. 24:02 Because if someone is forced to use your API and it's a difficult experience. 24:06 They're still forced to use your API and you're gonna have 24:12 a lot of support debt that you'll have to deal with. 24:15 You want to document it. 24:19 You want to make it so that most of the time they can just do what they want. 24:20 It's quick, it's easy and they don't talk to you. 24:24 When you have open developers what you have to remember is 24:27 that open developers are like wild animals on the Savannah. 24:32 Wandering around looking for a watering hole. 24:37 So they're gonna give you about five minutes. 24:40 They're gonna come in, they're gonna think, What? 24:42 But, what is this thing? 24:46 What can I do, and how can I do it? 24:47 And why, like, what problem can I solve with this? 24:51 You need to make those things really easy to understand. 24:55 And again, Twitter does a really good job of this. 24:58 Twilio does as well. 25:00 And, I encourage you to look at some successful 25:02 developer portals to help make a great developer experience. 25:04 Communication. 25:11 So communicating with your developers is critical. 25:13 Don't just tell them what your API does. 25:18 You know what your business value is. 25:22 You know how you're gonna measure it. 25:23 You know what your use cases are. 25:25 Those three pieces of information are not going to 25:26 sync your company if you share them with the developers. 25:31 On the other hand, what they're going to do is they're 25:34 going to convince those developers that you have thought about this API. 25:36 You have plans for this API. 25:39 This API is a real product. 25:41 They can use it. 25:43 They can trust you. 25:45 There have been many cases in the past where 25:47 people have made APIs without a real good strategy. 25:50 And then people used it and they sorta made modernization things. 25:53 And then, the API got shifted or pivoted or whatever, and 25:56 all of a sudden it wasn't available for the developers anymore. 26:00 So the developers who had invested their time in 26:05 using this API were kinda shot in the foot. 26:08 So you need to build that trust. 26:11 And one of the best ways to build that trust 26:14 is to tell the developers why you have an API. 26:18 How you're measuring success. 26:22 What you're trying to accomplish with it. 26:23 Show them the use cases. 26:25 Make those tutorials. 26:27 Give them example code that works. 26:28 In as many languages as you can. 26:31 Encourage your community to do that as well. 26:33 Marketing to developers is different than marketing to regular people. 26:38 Regular people, you show them a pretty picture of 26:43 a ketchup bottle or whatever, and they're like, [NOISE], ketchup. 26:45 Or bacon, bacon's always awesome. 26:49 Developers want to feel engaged. 26:54 Most of them are gamers of some sort. 26:57 They enjoy leveling up. 27:00 They enjoy feeling like they've accomplished something. 27:02 It's one of the reasons I think Twilio has such a great onboarding experience. 27:05 They want, within five minutes, for you to have done a thing. 27:09 Created a call that works. 27:13 Because now, what's happened? 27:15 You're invested in, in the API. 27:17 So that five minutes that you were gonna give 27:20 them, now it's turned into a half an hour. 27:22 And they, the more it feels like play. 27:25 The more likely they are to stay. 27:30 The more it feels like work the more likely they are to go do something else. 27:32 I wanna give a shout out to Firebase. 27:36 They have a great tutorial system for learning how to use the system. 27:39 It feels a lot like Codecademy. 27:45 It's it's very step by step. 27:47 When you make a documentation, you also want to think 27:53 about how the developers are going to get to that documentation. 27:56 So for instance, Hiroko. 28:00 Which is a fantastic product. 28:04 All their tutorials are about 17 pages. 28:07 Just a whole list of how to do things. 28:11 It's exhausting. 28:14 And the problem that I have had is that I can get through about maybe a third of it. 28:17 And then, something that I, in my real life comes and I have to deal with it. 28:24 And then I go back and I don't know where I was. 28:28 So break it up into chunks. 28:30 Have tasks. 28:33 And at the end of the task, it may seem 28:35 really stupid, but be like woo-hoo, you did a thing. 28:36 Now you can go on to the next thing. 28:39 Make a choose your own adventure. 28:41 Make it feel like they're advancing down a path. 28:42 When you look at the 17-page tutorial, you don't feel like you've 28:48 accomplished anything until you get to the bottom of the 17th page. 28:50 That's a little demoralizing, and it sure doesn't feel fun. 28:54 Tools. 29:00 There's some great tools out there for API exploration, 29:02 IOdocs, swagger if you have your database schema modeled, 29:06 effigy has a console. 29:13 It doesn't really matter how, but you need to make 29:15 it easy for people to see what a call looks like. 29:17 there's, there's also Runscope, which allows you to 29:23 sorta watch how traffic works on arbitrary APIs. 29:26 And API tools from 3scale [UNKNOWN] can do the same thing. 29:30 So, figure out how tools can be used. 29:35 Give people little, little how to do it guides. 29:38 So that they can explore and see what they 29:43 can do with your API without having to write code. 29:46 Asking questions. 29:51 So this is not your problem as a producer, except you're supporting the developer. 29:53 So one of the things software overflow actually has 29:59 a page that tells you how to ask good questions. 30:03 And it's not quite clear enough. 30:06 So I try to communicate to anyone I'm 30:08 trying to support what a good question looks like. 30:12 And a good question looks like a good bug report. 30:15 And it is. 30:18 I did x. 30:20 I expected y to happen. 30:21 To my dismay, z happened instead. 30:24 A good question always has all three of those things. 30:27 And the reason, you'd think, well, okay, I, I get the, I get the A and C thing. 30:30 Like I did this and that happened. 30:36 A lot of times your users will be 30:38 really frustrated, and they'll be like, it crashed. 30:40 Okay, well, well, what were you doing at the time? 30:44 And then they'll tell you, well, I did this and it crashed. 30:49 And you're like yeah, that's, that's actually. 30:52 That's what I would expect that to happen. 30:55 So you want to know what they did, 30:57 what their expectation was, and what the result was. 31:00 Maybe there's a bug. 31:04 Maybe they're using a different resource than they should be using. 31:05 The example I give so you can understand the 31:09 importance of this is, I jumped off a cliff. 31:12 I expected to sprout wings and fly. 31:15 To my dismay, I plunged to my death instead. 31:18 Okay, not a bug in gravity. 31:21 A problem with my expectations. 31:23 But when you communicate with your developers about asking questions, 31:26 you want to tell them, if they have an incorrect expectation. 31:29 That's a problem. 31:33 It's a, probably a documentation problem. 31:35 A communication problem. 31:36 You should have made sure that they understood what was going to happen. 31:38 So encourage them to understand that they're not 31:41 stupid because they're expecting the wrong thing to happen. 31:45 You just didn't tell them what was gonna happen. 31:49 So you'll fix 31:51 that. 31:54 SDKS. 31:55 All right, John Chian is gonna talk later, he's probably gonna talk about them. 31:55 I do not like SDKS. 32:00 For API's. 32:03 And the reason is if your API needs an SDK, you're doing it wrong. 32:05 You're API is not well formatted. 32:11 It is not created well. 32:13 It's not easy to use. 32:14 The more levels of abstraction you put between the user and 32:16 your API, the more places a, a of potential failure there are. 32:19 And, and it's, if you created a good API you don't need an SDK. 32:23 And also once you start making SDKs you 32:32 have incurred a huge amount of technical debt. 32:36 Because every time you change your API you have to change all 32:38 12 of the SDKs you have for all of the different languages. 32:43 Make is so that someone can write code in a, in any language HTTP 32:46 is well supported in, in all modern programing languages. 32:52 Make your example show them how to use just a basic call. 32:58 You may have to give them some help with 33:02 authentication, that is a hard thing to deal with. 33:03 But don't, don't try to wrap the whole API in 33:08 an SDK so that they aren't actually touching your, your API. 33:12 Because you're gonna end up supporting two sets 33:17 of things, and, and it's gonna slow you down. 33:19 And it's basically just evidence that you didn't 33:24 do a fantastic job of creating your idea. 33:28 Okay, so just like anywhere in the on the 33:33 internet intelligent conversation ends when a cat picture is posted. 33:38 So this is my cat picture. 33:44 And I will open up the floor to questions. 33:46 Again you guys can tweet me or you can ask me pretty much anything about API's. 33:50 When I say I worked with them for 33:56 ten years, I've worked with them for ten years. 33:57 I have seen everything on the consumer side and the producer side. 33:59 And I probably have an opinion. 34:04 [LAUGH] But I'll share it with you. 34:05 So, are there any questions? 34:07 Yes. 34:11 >> Do you have any wisdom versioning 34:12 an API or rereleasing versions with recent changes,. 34:14 How do you, kinda deal with that from a, from [INAUDIBLE] aspect. 34:18 >> So there's a few different ways to deal with versioning. 34:21 So people put a version in the URL. 34:24 Some people put it as a header. 34:27 Some people put it as a parameter. 34:30 How you do it is not important. 34:33 That you communicate it clearly to your users is important. 34:36 I caution against putting things in headers when you have a large group 34:40 of people who are not fantastic developers because it is hard. 34:45 In a lot of languages. 34:51 One of the problems that I had at at Netflix was that 34:53 someone wanted to use the Zend framework, which is a PHP framework. 34:56 And it made it pretty much impossible to add headers. 35:00 So that's how you can set versions and what I tend to think the best 35:03 strategy is, is to have your default, like have a, not use the URL. 35:09 But have a default. 35:16 And tell people when you're going to change the default, and 35:17 tell them how to go, how to keep using the older version. 35:20 Move the default forward to the new version. 35:24 So that new people get the new version, and 35:28 the old people can keep using the old version. 35:30 I'm frequently asked how to get people to move from 35:33 the old versions so they can get rid of it. 35:36 That's pretty much impossible. 35:39 Somebody had a task six months ago, they fixed, they, they, they met that task. 35:42 By using the first version of your API. 35:49 They have no interest in going back and writing more code. 35:51 They, they probably have forgotten how the code works at all. 35:55 And you can't push them. 35:59 But what you can do, is you can try to pull them. 36:01 Maybe version three of your API has a subscription 36:05 service for the stream of activity, and that's super awesome. 36:08 And maybe that's so awesome that you'll get 36:12 people to move from version one to version three. 36:14 But you can't count on it. 36:16 You can get deprecate APIs, Google does it. 36:19 You can deprecate old versions of APIs, but you will get pushed back. 36:22 So you, you need to, this is one of 36:28 the reasons of measuring APIs, this is really important. 36:30 You need to see which of your customers is is, is still on the first version. 36:33 So Ken Lang, the API evangelist, worked with a company who had different versions. 36:39 They had like four versions. 36:46 And only one customer was using the first version. 36:47 And he's like well, We can shut down the first version, right? 36:50 And they were like, Why don't you see who that customer is. 36:52 And that customer was bringing in $600,000 a month. 36:55 Okay? 37:00 That, that makes it worthwhile to keep that API around. 37:00 So it's not an easy thing you wanna try to prevent backwards incompatible changes. 37:05 If you introduce those, you're gonna need 37:14 to, to default, change the default more carefully. 37:16 Adding things is usually fine. 37:22 Removing or changing existing things is difficult. 37:25 So that's kinda the versioning thing. 37:28 You had a question? 37:31 >> When would you classify an API as failed on. 37:33 [INAUDIBLE]. 37:37 >> It depends on the API. 37:43 If you give a very complex search query, that can take a while. 37:45 You do want to communicate in SLA to your developer. 37:51 The developer partners that you have. 37:55 And tell them what they can expect. 37:57 you, it is your job to try to make it as efficient as possible, 38:01 but you have, there's a lot of factors that you can't control. 38:06 You can't control the mobile device, its, how big its connection is to the Internet. 38:09 You can't control. 38:16 You can't always control the back end resource sometimes they get bogged down. 38:18 As an API developer you're kinda working with some back guys 38:23 and sometimes that search is going to take a really long time. 38:27 You can cash what you can cash and that's useful, 38:32 but there always gonna be times where things take longer. 38:36 So communicate with your developers what you know. 38:40 And if they tell you something's a problem, try to make it better. 38:43 [LAUGH] That's, I mean, that's, that's really. 38:48 Or just tell them that you can't. 38:50 Be honest with your developers. 38:52 Tell them the truth. 38:54 That's one of the problems I've had in the past, was when I wasn't 38:57 able to give developers honest answers about why things were the way they were. 39:00 And I think developers are grownups. 39:05 And we should tell them, hey that, that's there's a business 39:07 reason for that, and we have to do it this way, sorry. 39:12 Any other questions? 39:15 No, yes, Adam. 39:16 >> So you're anti-SDK, but what if your develops are pro-SDK? 39:22 >> Then they can write one. 39:28 [LAUGH]. 39:30 >> Okay. 39:32 >> I mean, I, I, I think their parties at the libraries are great. 39:33 But I don't want to own it. 39:37 I, if someone makes a great API, a, a great SDK for my API. 39:40 And they support it consistently then I'll point to it from my developer portal. 39:43 If they make an A, an SDK for the API and they don't 39:49 keep it updated and they don't support people who ask questions, I won't. 39:52 I'll just tell them to use the API directly. 39:57 I always encourage contributions from community members. 40:02 I love it when people make great third party libraries and 40:05 they usually will, but you have to have a standard, a bar. 40:08 For, for something's that it, it, if something is causing you more support 40:15 problems, then cuz the user doesn't think about it as a third party thing. 40:19 So if it's causing you more support problems than, than 40:24 helping people, let people find it on their own [LAUGH]. 40:27 And, and just help the, you know, have them sniff the HTTP traffic 40:32 and see what's actually happening, so that you can help them debug the problem. 40:36 Yes? 40:41 >> For someone just diving into API development for the first time. 40:42 Do you have any specific resources that 40:46 you recommend for somebody just getting started? 40:48 >> Oh, that's great. 40:51 I didn't even throw her, she like, threw me a soft ball. 40:51 Okay there is a site, apicodex.3scale.net. 40:55 It is a site that I put together when I worked at 3scale. 41:00 The goal of that site is to actually give you answers to questions about APIs. 41:04 High level design they are written by some of the, 41:11 the smartest people I know who think a lot about APIs. 41:16 Mike Emson has a lot to say about hypermedia. 41:19 he, he is very eloquent. 41:22 Kim Lane, API Evangelists, thinks about a lot of things. 41:24 So that's a good place to go. 41:28 and, and if you don't find what you're looking for 41:32 there, pay attention to the people who are doing the writing. 41:35 That I thought were good enough to put in the API 41:38 codecs cuz it might have written something about what you're looking for. 41:40 Understanding who those au, authors are that are leading the 41:44 API maturity, will help you to, to find what you need. 41:50 And you can also tweet me, or send me an email. 41:56 Oh, so contact information for me. 41:59 As I said, I will post this on Slide Share with, with speaker notes. 42:02 Links to the things that I talked about that I remember. 42:06 You can tweet me. 42:10 @senedra. 42:11 You can send me email at senedra@gmail.com. 42:13 And I am princesspolymath.com. 42:16 So, you can go there. 42:20 I'm actually gonna put up a worksheet. 42:22 A cheat sheet of the things I talked about at 42:26 my workshop yesterday and the things I've talked about today. 42:28 So you could just download it, or click on the links and go visit the places. 42:31 I will be at the meet the speakers event, 42:37 with my drone that I used for my workshop yesterday. 42:41 So you can come play with the drone. 42:43 Trying to suck away all the users from the other speakers cuz I like to be cool. 42:45 Plus, it's my drone, [LAUGH] so. 42:50 anyways, so that's all the questions I'll take. 42:53 But please do find me. 42:57 Contact me, over the internet. 42:59 Find me here. 43:01 And have a great rest of the conference. 43:03 Thank you. 43:05 >> [SOUND] 43:05