Bummer! This is just a preview. You need to be signed in with a Pro account to view the entire video.
12 Reasons Your API Sucks38:45 with Keith Casey
Those first moments of using an API are pivotal. There’s nothing like downloading this week’s PDF of the documentation, setting up a SOAP client, reconfiguring all your URLs, and decoding the latest binary payloads. It makes your heart sing and your blood pressure rise. Just like there are code smells through the rest of your project, there are API smells that make them hard to design, hard to launch, and hard to maintain. We’ll use this time to explore a few common APIs to highlight those issues and demonstrate strategies to fix the issues before they become problems.
Hi everybody I'm Keith Casey as he said I'm here to tell you twelve reason why 0:00 your API sucks. 0:03 Now if you're going to go back to your boss and tell him what, or tell him or 0:05 her what presentation you went to, you might not wanna use that title, 0:08 you might wanna use a different title. 0:10 So if you have to report back what presentations you went to, 12 Steps to 0:12 Successfully Launching Your API, might be a little bit better title to use. 0:15 I gave this presentation at a bank last Spring and 0:19 it was great because I pitched them using this title, but 0:21 then when I got up I used this title, and that went over really well it's amazing. 0:23 Anyway, so let's see we already did that I'm from the great state of Texas. 0:28 Do we have anyone else from Texas? 0:33 No, you guys are all missing out let me just tell you that. 0:35 All right just for 0:38 the record, if you wanna come to South by Southwest you're welcome. 0:39 We'll def, get together, have drinks, you cannot sleep on my couch. 0:43 And I mentioned earlier, I'm from Clarify we're an API that makes audio and 0:46 video searchable. 0:50 This sort of gone into how I put together this presentation, 0:51 I've been working with API's since about 2001. 0:55 It was a federal contractor in DC, and we were working on what 0:58 is the ultimate geek question at the Library of Congress Is, 1:02 how much data is at the Library of Congress? 1:04 And we were digitizing everything they owned. 1:06 So, we ran into this problem of trying to digitize and 1:08 trying to share this information between agencies. 1:11 So, we came up with what believed to be the first soap web service in 1:14 the federal government back in 2001 and we launched it then. 1:17 So I've been working with APIs, for about 13 years at this point. 1:20 I found out I've been presenting on APIs since 2006, at clarify I sort of 1:24 had to put my money where my mouth was and design an API from the ground up. 1:28 So this is these are all har, hard fought battles. 1:32 And, I decided to put my money where my mouth was a little bit more and 1:36 write a book on it. 1:39 So, I tell people this is the book on API design and the URL says so. 1:40 So of course that's the truth. 1:44 And just as a little bit more background I came from Twilio, I spent two and 1:47 a half years there has everyone heard about Twilio today? 1:51 Like six times, seven times, yeah, it's kinda ridiculous but, 1:53 one of the things that they did really well was API Design. 1:56 Now, they weren't perfect, there's a couple of places in here where, 1:58 we'll go over some places where they can make some improvements and 2:01 places where we as clarify, made improvements directly. 2:04 But there's a lot of places where we can take an API, 2:07 and we could do some very cool things with it with just a little bit of thought. 2:09 So, without further ado, lets dive in. 2:13 So, we're gonna talk about what is DevX. 2:16 Has everyone heard of the term developer experience before? 2:17 One. 2:22 Oh, two. 2:22 Oh, both were from Best Buy, that's a good sign. 2:23 [LAUGH] Okay, a couple others. 2:26 So we're gonna talk about love at first byte, 2:28 like what it takes to first use an API. 2:30 We're gonna talk about the day to day usage, adopting an API, 2:31 and we're gonna pull it all together at the end. 2:34 So, first of all, what's developer experience? 2:38 Best Buy guys do you have, you guys got an answer? 2:40 >> It's your talk. 2:42 >> It's my talk. 2:44 >> [LAUGH]. 2:45 >> Okay. 2:45 So developer experience is the idea that users are, or developers are users too. 2:47 Just like we do all these different things to make a user experience good, 2:53 we should do similar things to make a developer experience good. 2:55 What are some of the things we do for a user, to make their lives better? 2:58 We do things like wire frames. 3:01 We try and simplify interfaces. 3:03 We try and clarify interfaces. 3:05 We try and make things as clear and straight-forward as possible. 3:06 We model things. 3:10 We do interaction diagrams. 3:11 We do all these things to make somebody's life easier. 3:13 And there's a great book called "Don't make me think," has anyone read it? 3:15 Awesome, there's always a couple. 3:19 Don't Make Me Think is a great book on web usability. 3:21 It was written probably 12, 3:25 13, 14 years ago at this point it's pretty dated, but the stuff in it is fantastic. 3:26 And the, his whole, 3:31 Steve Krug's whole premise is every second that you make somebody think about how to 3:32 use your system, is one less second that they can use to solve their problem. 3:37 So when we talk about user experience and 3:42 developer experience, we need to think along the same lines. 3:43 We need to remember, every time we have an incompatibility, or a disconnect, or 3:46 any kind of weird thing in, in play, we're making the user stop and 3:51 stop thinking about their problem, and 3:55 start thinking about us as the problem, we absolutely don't want that. 3:56 So I say developers are users too believe it or not, developers are humans. 4:00 Sometimes that's up for debate, but absolutely it is the truth. 4:05 And I sort of come at this for a simple reason of, at Twilio we have the, 4:10 the, the unique pers, unique situation where everyone that's using the API 4:14 needs to get started as quickly as possible because Twilio only makes money, 4:19 when somebody successfully used the API, I clarify we're the exact same way. 4:23 We only make money if someone successfully uses the API. 4:26 So our goal is to get people started as quickly and easily as possible. 4:30 And the reason is because what happens when you find a new tool? 4:34 You bookmark and you say I'm gonna come back and look at it later. 4:38 When does later come? 4:40 I here never. 4:43 Is that, that's pretty much it. 4:43 Right? 4:46 Never never comes, it just goes on and on and 4:47 on, we don't know when it's gonna happen. 4:49 But once in a while we do get that like brief hour, where we're, we had a, 4:51 we have an opportunity to play with that new tool we found. 4:56 You know, it's in between meetings, we sets, we sit down, 4:59 we open the bookmark, we say, Okay, what does this thing do. 5:02 So we set aside that hour. 5:05 Well what happens during that hour? 5:07 The phone rings, we get e-mail, somebody knocks on your door, 5:08 there's all these constant interruptions. 5:11 So what started as an hour of focused time, quickly turns into like three, 5:13 10 minute segments. 5:18 Now when you think back about that time, 5:20 you don't remember oh yeah I got interrupted 12 times during that hour. 5:21 you think oh I set aside an hour to play with this tool and 5:25 I didn't get anywhere ,and that's the experience you remember. 5:27 Developer experience is the idea that we can simplify all this. 5:32 We can make this, make this entire experience that much better. 5:35 By making the experience better, we can give somebody an experience very, 5:38 to give them, get them productive very quickly and very easily. 5:42 At Tully our goal was five minutes, from the time you create an account to 5:45 the time you send a message or make a call five minutes. 5:48 At Clarify, since we do audio and 5:50 video indexing it takes a little bit more effort, we say 10 minutes. 5:52 From the time you create your account to the time you index and 5:55 search a, a call or video or something, should be about 10 minutes. 5:58 Because if we can get somebody productive in those 10 minutes, 6:02 that's what they remember. 6:05 Oh yeah, I set aside an hour they forget, I got interrupted 12 times and 6:06 they remember I got something done, I got something functional. 6:10 That's the experience we wanna leave people with. 6:13 So in that regard, let's talk about love at first byte. 6:16 What does it take when we start what are the first of the 12 reasons why API sucks. 6:19 FIrst off, right off the bat, documentation. 6:24 So when I Tweeted about when I was first writing this presentation I tweeted, Hey, 6:28 can somebody send me a link to bad documentation. 6:31 That was a bad idea. 6:33 >> [LAUGH]. 6:34 >> That was a really bad idea, for like six days, my Twitter is blowing up. 6:35 And just saying, hey, did you see this, did you see this, did you see this? 6:40 And there are five or 6:42 six companies that kept coming up over and over, and over again. 6:43 I'm not gonna name them cuz that would be mean. 6:46 But a lot of them sent me PDFs. 6:49 They said, here's the PDF to our documentation. 6:51 What's wrong with the PDF's documentation? 6:53 It is static, so it guarantees that it is always out of date. 6:57 If you download it on Monday and 7:00 you use the API on Tuesday, by definition it is out of date. 7:01 It is not necessarily wrong, but now it is not reflective of what is actually there. 7:04 And now when there is a change to the API it is not going to be up to date at all. 7:09 What else is wrong with the PDF's? 7:13 >> Hard to copy and paste. 7:17 >> Hard to copy and paste. 7:19 >> You need extra software. 7:21 >> You need extra software. 7:22 How about the fact that it's really hard to search them. 7:23 It's a pain to be able to find exactly what you're looking for. 7:26 Now we a good table of contents you can mitigate some of that. 7:29 Frankly, why do you have to? 7:31 We have this great thing called the internet, just put it on the internet, and 7:34 then the internet itself takes care of making it searchable, 7:37 takes care of copy and paste. 7:40 We've got all these components that are, that are great for solving these problems. 7:41 My favorite one though was I got a DM that said, 7:45 hey, if you sign this NDA, we'll send you our docs. 7:48 [LAUGH] What's wrong with that? 7:51 Who in this room, is authorized, to sign contracts on behalf of their company? 7:57 I see zero. 8:03 Oh one there's one, that's fantastic. 8:04 So you can go ahead and look at the documentation. 8:07 None of the other people can go, in this room, 8:09 can look at the documentation, short of involving your boss. 8:11 Who probably then involves a corporate attorney. 8:14 Who then gets charged $350 an hour at minimum, to review this document just so 8:17 you can get the documentation. 8:21 How many people wanna ask their boss for that time and that, that commitment? 8:23 It's ridiculous, it's absolutely ridiculous and 8:27 I can guarantee those docs are out of date anyway. 8:30 So you, you get broken documentation that you can't then complain about, 8:33 because you just signed an NDA. 8:37 So you're stuck with where you are. 8:39 That's a broken, fundamentally broken way of doing things. 8:41 HTML's a fantastic way of doing things do them with HTML. 8:44 But beyond that I would say don't stop with HTML make them interactive. 8:47 Has anybody played with Swagger? 8:51 Swagger is fantastic. 8:53 Swagger is a JSON standard that you can put your API documentation into, 8:55 and then instead of just getting back the static file their static page, you get 8:59 back a page that laid out with individual function calls that you can make. 9:03 And then if the, if the people have set it up correctly, 9:07 you can make live API requests against the API itself. 9:10 So this is what we use for Clarify so you can actually drop individual, 9:14 values into the field and make a live API request, and get back the actual data. 9:19 Its a fantastic thing because now you don't have to write code to 9:25 see what the API does. 9:28 You can immediately see it without any further effort. 9:29 There's also a competing scenario called iodocs, 9:32 that works essentially the same way. 9:34 That one is from Mashery, Swagger's open source, but 9:37 realistically, as long as you use one, you're in pretty good shape. 9:39 Number two is incomplete, wrong documentation. 9:43 Helper library's documentation is not the same as API documentation. 9:47 I was working with an API company earlier this year that I'm not going to name, 9:51 because one of the things they did was they decided not to document their 9:55 API itself. 9:58 Instead, they wrote a RUBY GEM and documented that. 10:00 What's wrong with that? 10:03 Anybody, who are the RUBY developers in the room? 10:03 Okay, everyone with your hand down, 10:07 you're excluded from using the API just by default. 10:09 Because when you don't provide documentation for 10:13 the API itself, you're excluding anyone who doesn't work in 10:16 the language that you've provided documentation in. 10:18 That's kinda messed up, if you wanna have an, an API that's used, 10:22 and we all want an API that's used. 10:25 Right? 10:27 We want our code and our projects being used in real life. 10:28 We want to be able to make things as easy to get to as possible, and 10:31 easily to use as possible. 10:34 Next up, getting started code, who has getting started code on their website? 10:37 Does it work? Oh, 10:41 fantastic all right, thumbs up from everybody. 10:42 Ok, so this is getting started code from Twilio, not big surprise there. 10:46 It takes fundamentally about two lines of code to get started. 10:49 So there's a line of code there that instantiates the object. 10:53 And the one that actually sends a message. 10:56 And that's it, that's a fantastic approach for doing things. 10:58 At Twilio we had a saying of copy, paste, execute. 11:02 Because what happens is, you put the sample code out there, it's guaranteed 11:05 that people are gonna copy, paste, and put it into their applications. 11:08 Now there's a downside to this. 11:12 That means people are going to copy, paste, and put it into their applications. 11:13 So if you have any errors, if you have any problems, 11:18 if you do anything weird in your code, that code's going to live on indefinitely. 11:21 And I really do say indefinitely I, I wrote a blog post three or 11:26 four years ago with a code sample that's completely legitimate but 11:29 kind of oddly structured, and I still get e-mails on it occasionally. 11:32 This is the sort of thing get really clear, simple succinct sample code and 11:36 put it on your website. 11:41 Give people as much hand holding as possible to get them started. 11:42 It doesn't take any effort to tweet the, or to copy and paste and 11:46 tweet this to be able to run it. 11:48 As opposed to this this, I couldn't even fit it on one slide, but 11:51 PayPal has this great example where just refunding 11:55 a transaction is 200 lines of boilerplate code. 12:00 So just, just hypothetically, hypothetically, let's say you're trying to 12:05 copy and paste the first chunk of code that's the Twilio example. 12:09 What's the likelihood of an error when you copy and paste three lines of code? 12:12 Pretty low? 12:15 Zero? 12:18 What's the li, likelihood of an error when you copy and paste 200 lines of code? 12:19 I can guarantee you're gonna screw that up. 12:23 This is the sort of thing that we don't wanna in, in our documentation. 12:28 If you have to provide sample code that's 200 lines, you're doing something wrong. 12:31 As much as possible, set things to default reasonable conditions. 12:37 Set things to the, so that people don't have to think about it. 12:40 If you don't have to take care of 100% of the scenarios. 12:43 But if you can take care of 80% of the scenarios you win. 12:46 You can get people started quickly and easily. 12:49 Next up SOAP, if you are doing SOAP you are doing it wrong. 12:52 [BLANK_AUDIO] 12:56 So, I, I said this earlier in my other presentation but, 12:59 the way I see it is SOAP is like getting a mortgage. 13:02 So, there's a lot of documentation up front. 13:05 There's a huge process throughout the entire thing. 13:07 There's documentation all the way along, 13:10 if things go wrong there's documentation for how to resolve things. 13:11 REST is like borrowing 10 bucks from your buddy for lunch. 13:15 So, there's a lot of flexibility in that, you can return the $10 to pay them back, 13:19 you can go ahead and you can buy them lunch tomorrow, 13:23 you might be able to buy them beer at the bar there's a lot of flexibility in that. 13:25 So, this is one of those places where if you're using SOAP, 13:29 you're probably doing it wrong you're introducing a lot of complexity, 13:32 where there doesn't necessarily have to be. 13:35 You're causing yourselves a lot of headache and 13:38 a lot of problems that you don't have to. 13:39 I was working with a bank earlier this year and 13:41 they did an inventory of their SOAP applications. 13:44 And they found that there were a couple of placeses, 13:46 where the customer data was coming back. 13:48 In one place it was coming back first name as one field, last name as another field. 13:51 In another place it was coming back last name, 13:55 as a field comma first name, those were two separate APIs. 13:57 But because the way they had things architected and everything had to 14:02 go through these weird SOAP interfaces, the two groups weren't communicating and 14:06 they ended up building almost identical APIs. 14:10 And when they finished their inventory of what APIs actually had functional, 14:13 they figured out there was about 20 to 25 percent duplication of 14:17 the 500 APIs they had launched. 14:20 It's ridiculous, when you're using SOAP you're guaran, or 14:22 you're almost guaranteed to have bad practices, just because the complexity and 14:25 the, the effort it takes to deploy these and, and use them on a day to day basis. 14:29 Next up, adoption. 14:35 So, one these things is or not one of these things 14:39 this is an API that I'm not going to name, because we're gonna make some fun of it. 14:42 So first off, 14:47 we've got an API we've got an Accounts object, and we've got /api/v1/accounts. 14:48 So we can look at this, we can say, okay, this works, you know, 14:53 when we've got a resource that we're interacting with, 14:56 it's probably API v1 and then the name of the resource. 14:58 So we look at a contacts, we've got the same thing API v1 contacts, so 15:01 it's what we'd expect. 15:05 When we get to a compound word though, compound word there, 15:06 we've got contact_histories. 15:11 Okay, so that's what we're working with. 15:13 An API should be consistent. 15:15 They should be predictable. 15:17 So, let's see what happens here. 15:18 Does anyone have a guess on what the URL for a user should be? 15:19 It's probably API, B1 users, it's probably that. 15:22 Right? 15:29 Nope. [BLANK_AUDIO] 15:31 It's that. 15:35 Okay, well don't worry. 15:36 We've got contact groupings. 15:37 We've got another compound word. 15:38 So what's the rule for compound words? 15:40 Anybody? 15:44 Underscore in between them, so it probably looks like that. 15:45 No, it actually looks like that. 15:48 When you introduce these inconsistencies, you're just causing problems for yourself. 15:52 You're causing problems in extra code in your helper libraries. 15:56 You're causing stress in the people who actually wanna use your code. 15:59 I was working with a user experience team recently, and 16:03 they were monitoring people as they were using the products. 16:05 You know they, this is they type of person, er the type of team that puts 16:08 a camera on the person while they're actually doing development, 16:10 while they're doing their, their coding and everything, and the number one 16:13 emotion that came out during the presentation was, anyone have a guess? 16:17 Rage, if people are using your products and 16:22 feel rage, I'd suggest you're doing it wrong. 16:26 Just hypothetically, you're probably doing it wrong. 16:29 And this is the sort of thing that, that causes that rage. 16:33 When we've got something where we establish a rule, 16:35 we establish a pattern and then we break that pattern for some reason. 16:37 And I actually, I talked to the guys that did this and said hey what's up. 16:41 You know, why do you have these inconsistencies? 16:44 And the response was oops, sorry about that, that was it. 16:46 That's, that's the sort of thing that they, 16:51 that they ran into because there was never really an effort to design the API. 16:53 They sort of just came at it haphazardly and 16:56 tried, just tried to put things online. 16:58 Here's another usage of the API one of these things is not like the other. 17:03 We've got a situation where we, we do a post when we create a new resource. 17:07 When we create accounts, we get back a two oh one. 17:10 Two oh one response code means created. 17:13 We get back a location header pointing at the resource we're about to interact with. 17:15 When we create a new user, we get back two oh one location header. 17:19 When we create a new contact, though, we get back a 200 resource. 17:23 We get back the actual resource we're interacting with. 17:27 Now from easy use, this might be a good, 17:30 useful thing to have, where you create something, you get it back. 17:31 The problem is, when we update something with this API, 17:34 we also get the resource back. 17:38 So now whether we create or 17:41 whether we update, we get the resource back and we don't know what happened. 17:42 We don't know if it was created, we don't know if it was updated. 17:47 When we're updating or we're, we're maintaining records in a database, 17:49 when we're maintaining these records, we wanna understand what's happening to them. 17:52 If they were getting updated you should probably know explicitly yes, 17:56 I'm updating this. 17:59 If we're just creating something new, 18:01 we should probably know we're creating something new, 18:02 it doesn't take that much to do this sort of thing. 18:05 Number seven, poor workflow and modeling. 18:09 Okay, so of the people who are designing or 18:12 building API's who did modeling exercises beforehand? 18:13 Anybody? 18:16 You, sir, are fantastic that's, that's great. 18:18 Most often, 18:21 the way an API gets designed is somebody takes all the database objects, 18:23 they put get put post delete around them, and then, wow, you've got an API. 18:27 They only worry about the verbs and 18:32 the nouns, they don't think about, hey, how can we actually design this? 18:33 And what we can, what can we design this to do? 18:36 So there's a thing that I call, or that we talk about in terms of coffee cups. 18:39 So, what's the point of a handle for a coffee cup? 18:44 Anybody. 18:48 >> You don't burn your hand. 18:49 >> You don't burn your hand. 18:50 It's real simple, right? 18:51 So, it's designed so that you don't burn your hand. 18:53 Did they succeed with that design? 18:55 >> Mostly yes. 18:57 >> Mostly yes, okay, I'll give you that. 18:58 Can you use the handle for other things? 19:00 >> I can hang it up. 19:02 >> You can hang it up. 19:03 So, here we've got a scenario where there's what they designed the interface 19:04 for, cuz the handles just an interface. 19:07 What they designed the interface for, what they made easy, and 19:10 what you wanna do are all in alignment" cuz you don't wanna burn your hand. 19:13 Right? 19:17 Can we agree that, that's probably what one of your goals? 19:18 So this is a situation where all three are in alignment, and 19:20 that's a great thing to have. 19:23 It's when the, any one of those things is misplaced, 19:25 that's when we run into problems. 19:29 And API can be beautifully designed. 19:30 They can make like what they want you to do very easy. 19:32 But if that's not what you wanna do, you have a problem. 19:35 You can also go the other way of what they want you to do, 19:37 is not what they made easy but that's still what you wanna do. 19:42 And you run into these scenarios of, the thing that you're trying to 19:44 accomplish is really hard to do, and that's fundamentally broken. 19:48 So there was this, as a sub-point to this I wanna go back to this one. 19:54 And this is who is the API for? 19:57 What's the purpose of the API? 19:59 Is this API actually product? 20:02 Is this something that they're driving revenue with? 20:03 If they're driving revenue with it that, 20:07 that changes your relationship with the API. 20:09 Facebook has a great example where at the end of 2013, they announced to 20:12 their API community they'd only break the API four times in 2014. 20:16 What's wrong with that statement? 20:19 Come on, anybody what's wrong with that statement? 20:24 >> They're gonna break the API. 20:26 >> They're gonna break the API, they're gonna do it four times. 20:27 And oh by the way, they said only four times in 2014, what does that imply? 20:31 >> [UNKNOWN]. 20:35 >> They previously done it far more than that. 20:37 That's kind of messed up, I guess when you have a billion and 20:41 a half users you can do what you want. 20:44 I mean there's kind of, 20:47 they are the defacto standard, you can't avoid them by any stretch of imagination. 20:48 So this is a scenario where they can do what they want, and 20:52 you're sort of at their whims. 20:55 What about a company like Clarify? 20:56 We derive revenue directly from your usage of the API. 20:59 So what are we gonna make easy? 21:02 Using the API. 21:05 What's in our best interest? 21:06 You using the API successfully. 21:08 That's it, Twilio's the exact same way. 21:10 If they, if they want to make money they need to make that process as smooth and 21:13 simple as possible. 21:16 Now here's another question. 21:18 Do you think Facebook might ever shut off the API? 21:19 Yeah. 21:23 Does Google shut off their APIs? 21:23 Constantly. 21:26 Do they do it with plenty of notice? 21:27 How about Netflix? 21:29 Does Netflix shut off their APIs? 21:30 Does Netflix even have any APIs anymore? 21:32 No public ones, yeah, they killed off all but like, seven API keys, I think. 21:36 They killed off that community, because that's not where they derive value. 21:40 Do you think Tullio will ever shut down their API? 21:43 No, what would happen if they did? 21:48 They'd go out of business. 21:51 Right? 21:52 It's real simple if they, 21:53 if they kill their API, it completely destroys their business. 21:55 When you're deciding which API to work with and how to build an API and 21:59 how to work with an API, you need to understand how this works together. 22:03 Usually here I also mention the Best Buy API, because the Best Buy API Q3 22:07 of the last year grew revenues 13% quarter over quarter. 22:10 Do you think they're gonna shut down that API? 22:13 [BLANK_AUDIO] 22:16 Growing 13% quarter every quarter means that, it doubles every five quarters. 22:19 They double the revenue that it generates that quickly. 22:23 In, in no, in no sane world would they shut that down, because it's growing so 22:26 fast it makes a lot of sense to keep it online and 22:30 to hopefully make a ton of money with it. 22:33 Number eight, numerous approaches. 22:37 So, I have to be honest with you guys I'm a PHP guy. 22:39 Do we have any haters? 22:41 No haters that's a first. 22:44 Oh, there's one okay, that's cool. 22:46 There's always one, that's fine haters gotta hate. 22:47 So, the running gag about PHP is it's a fractal of bad design. 22:50 It's the idea that there's 600 ways to accomplish any given thing. 22:55 And that's right, there are 600 ways of accomplishing a thing. 22:59 The plus side of that, is that, 23:02 no matter what background you come from, you'll find a solution. 23:04 The down side is, no matter what background you come from, 23:08 you'll find a solution and some of them are fundamentally broken. 23:10 But this gets to what I call, the stack overflow problem. 23:15 So everyone I assume has used stack overflow. 23:19 Right? 23:20 Okay, I did this presentation for 23:21 an audience a couple weeks ago and none of them had used stack overflow. 23:23 And I was like, what do you do? 23:25 Like, like, how do you, like, do anything. 23:27 So when we run into a bug, what do we do? 23:32 Copy, paste, Google. 23:35 Right? 23:36 And where does that almost inevitably lead. 23:37 Stack overflow so, 23:39 the stack overflow problem is what I describe as somebody runs into a problem. 23:43 They say I'm trying to accomplish, 23:46 I'm trying to do Z, I'm trying it with approach A. 23:48 Can somebody help me? 23:52 And what's the first answer almost always? 23:53 You're wrong, yeah, more specifically it's that the answer is almost always, 23:58 why are you trying to do it like A? 24:02 B is the right way to do it. 24:04 And the next answer is almost entirely A & B are wrong, 24:06 C is the right way of doing it. 24:09 And about half the time all of them are right. 24:11 So when you apply, when you have numerous approaches to solving the same problem, 24:16 you end up introducing problems in your own community. 24:20 because now that you have this sort of scenario where everyone is wrong, but 24:23 everyone's right at the same time. 24:26 So I actually saw, 24:28 there was an API company who I ran into one of their problems on stack overflow 24:29 when I was trying to debug something, and each person said no, you're wrong. 24:32 Here's the link to the documentation on their site, that say that I'm right. 24:37 And they had three separate links, 24:40 each describing how to do the same thing in completely different ways. 24:43 So you have the users themselves arguing amongst themselves, 24:47 using the company's documentation, 24:50 showing how everyone else was wrong that's messed up, that's really messed up. 24:52 What's the other problem with stack overflow? 24:58 Anybody? 25:01 Do you control it? 25:02 No you don't control stack overflow. 25:05 Anyone, anyone's answer, whether good or 25:08 bad, can be the answer that gets accepted on stack overflow. 25:11 So as your API changes, what happens? 25:15 Because people make there way to stack overflow to find their solution, 25:18 we run into a pretty big problem. 25:21 Because now we don't have control over that solution. 25:23 We don't have control over that piece of documentation. 25:26 So we have a pretty big problem, 25:29 because when our API changes, now we've got bad information out there. 25:31 By eliminating the additional approaches and only having one approach for 25:36 each individual thing, we can simplify our lives. 25:40 One we don't have to provide as much documentation. 25:43 Right? 25:45 We don't have to document every particular way, we document the one true way. 25:46 We don't have to worry about the stack over flow problem of people arguing using 25:51 our own documentation, because there is one way. 25:54 So everyone should be in the same, going in the same direction. 25:57 And we don't lose control over where our documentation shows up. 26:00 Because when there, when there's any doubt people reference the documentation 26:04 directly and you can lead them back to there. 26:07 That, those are all good things to have. 26:10 Number nine, Authentication. 26:14 Dear God, don't roll your own. 26:17 Please, has anyone here rolled their own document or their own authentication? 26:19 Why? >> Wanted to learn. 26:24 >> Wanted to learn. 26:27 Okay, that's a valid. 26:27 Did you deploy it? 26:28 >> No. >> You didn't deploy it good call. 26:30 Did you deploy it? 26:31 >> Yep. 26:32 >> Oh. 26:33 So unless you're a crypto expert and I, I talked to a crypto expert at 26:35 a bank a couple weeks ago even he doesn't roll his own authentication. 26:38 Because the, the thing is that a lot of people have been thinking about this for 26:42 a very long time, and they figured out solutions that work. 26:46 So whenever possible use a solution that already works, don't try and 26:49 come up with your own. 26:52 Cuz your crypto is not going to be as good. 26:54 Your process is not necessarily going to be as good, 26:56 and you can run into all kinds of problems that you didn't consider. 26:58 There are lots of standard out there OAuth 2.0 is a fantastic standard, use it. 27:02 Shared tokens, there's all kinds of things that will do it for you, please don't roll 27:06 your own authentication, there's absolutely no reason to at this point. 27:10 Next up, day to day so, 27:15 these are some day to day things that might help you with your API. 27:17 Number 10, most likely your stuff is broken. 27:23 Who has a broken API right now? 27:25 Come on! 27:27 There's always one. 27:28 One. All right thank you. 27:29 Thank you for being honest, I appreciate you. 27:31 So odds are your API is broken in some way. 27:34 It could be as simple as your up-time is pretty low. 27:37 I was working with the DISH TV API recently and they boasted 99% up time. 27:40 What's the problem with 99% up time? 27:45 That means they're down 1.68 hours a week. 27:51 Now, those hours might be at 2:00 in the morning on a Saturday, so 27:55 maybe it's not relevant to, you know, in the time zone I'm in. 27:58 But maybe that's, maybe that's in the middle of the day. 28:02 If you're time, if you're up time is only 99%, you need to stop and 28:05 think, what are we doing wrong? 28:08 How can we make this better? 28:09 How can we improve our monitoring? 28:10 How can we catch these problems, before they make it in production? 28:12 Before they take our systems down? 28:15 We already talked about the docs being up to date. 28:16 My favorite thing is, is your API deterministic? 28:19 Does anyone know what deterministic means? 28:22 It means when you put in a given set of information, 28:26 you get out the exact same information every time. 28:29 That, the output is predictable. 28:31 Now I clarify, we use machine learning. 28:34 So if you give us data on Monday, if you give us a file to index on Monday, 28:38 we do automatic speech recognition to find out what is actually said on 28:42 the file on Monday. 28:45 If you give us the exact same file two weeks later, we might come up 28:46 with a different set of words, because our machine learning has gotten better over 28:49 time, or at least changed over time hopefully, it's gotten better. 28:55 So we run into this really big problem of when somebody gives us data, 28:59 somebody gives us input the exact same way, over and over and 29:02 over again, they might get back different answers each time. 29:05 And that's just inherent in what we do, 29:09 hopefully your API doesn't have the same challenge. 29:11 If it does I'm sorry, because that's a pain to deal with. 29:15 We're sitting here we're trying to figure out "okay if they give us 29:18 this file multiple times, do we run it through the same engine multiple times or 29:21 do we run it through the latest version of the engine. 29:25 And to be honest, we haven't figured this out, we're not sure the best approach yet. 29:26 So, in some cases somebody can think our API is broken, which hopefully it's not, 29:33 hopefully it's working exactly as designed. 29:37 But it's entirely possible that it's, you know,that it's, it giving back different 29:38 input than they're expecting makes it broken from their point of view. 29:43 Number 11 is error messages, what's wrong with this? 29:48 [INAUDIBLE] >> What? 29:50 >> It's not helpful. 29:53 >> Not helpful. 29:54 So, 404 means what? 29:55 >> Not found. 29:56 >> Not found, and there was an error well, yes, there was an error. 29:58 If you're writing messages like this, stop it, you're being a jackass. 30:03 You're not, you're not giving somebody useful information to 30:07 sort of tell them what to do next. 30:11 So one of my friends has a saying that always imagine that your 30:13 code is being maintained by a psychotic axe murderer, with your home address. 30:16 I'd say that's pretty good motivation, it's a pretty good motivation to 30:22 understand exactly what your code is doing, and why it's doing it, and 30:25 hopefully make it easier for the next person that comes along. 30:28 So what about this one. 30:32 [BLANK_AUDIO] 30:32 And this was an actual error message I pulled from an application about six 30:36 months ago. 30:41 Everything good about it? 30:42 No what's wrong with it? 30:44 >> Got the wrong status code. 30:47 >> Got the wrong status code. 30:47 200 means A-okay. 30:50 Right? It means everything worked. 30:51 We get a response message though that says item not found, so 30:53 what should that status code be? 30:56 404 right? 30:57 What about this weird error code thing? 30:59 Any guesses what that is? 31:04 We, we don't know what something is what do we do? 31:07 We Google it. 31:10 So do you think the number 11007, has shown up anywhere in nature before. 31:11 Never. 31:15 >> Never. Okay, except in this one, 31:17 this one error message right. 31:19 So we drop this into Google and 31:22 we find out, we, we find some random in, statistic that's talking about, you know, 31:23 crop yields in midwest you know, midwest U.S. and something totally unrelated to 31:27 what we're actually talking about what we're trying to learn. 31:32 This is kind of messed up and 31:35 there, the content management systems like WordPress, Drupal, a lot of the big 31:37 guys were responding with this sort of thing until about three or four years ago. 31:40 You'd request a post that didn't exist it'd say 200 okay, 31:44 I didn't find what you're looking for. 31:47 Don't do that please, you're just making life stressful for the next person. 31:50 So hopefully we can all agree that this'll probably look closer like this,, but 31:55 we still have this weird error code in this, in place. 31:59 So this is an example, 32:04 these are actual, live examples that we pulled from, from these APIs a while back. 32:05 So Facebook example, what do you guys thing of that? 32:11 Status code 200, what does that mean? 32:16 It means it worked. 32:18 Okay, what's the error message say? 32:21 Or what's the message say? 32:23 Doesn't even say it's an error message, just says it's a message. 32:24 Some of the aliases you requested do not exist. 32:29 And we've got an oh off exception. 32:33 Okay so, did it work or not? 32:35 Probably not but 32:37 maybe, we don't know, the API itself says this worked. 32:42 We're getting back an error message and an exception saying that it didn't work, 32:48 Facebook is lying to us one way or another. 32:52 And there's a whole other presentation on that that I'm not gonna get into but 32:54 Facebook is kinda messed up here. 32:58 They're, they're introducing ambiguity and some problems that we don't know what to 32:59 do with, we don't know what the next step is. 33:03 Let's skip over Twilio and come down to SimpleGeo. 33:05 What about the status code? 33:08 Does that look good? 33:09 Yeah? 33:12 And the message is authentication required. 33:13 Does that check out? 33:16 401 is what? 33:19 Authenticating, authentication required. 33:22 So we've got a scenario where the status code and the message line up. 33:24 So that's good, that's not excellent, but that's good at least it's not lying to us. 33:28 It's telling us here's what the status of the system is. 33:33 What about the Twilio one? 33:36 And to be honest, Clarify, 33:37 we've copied Twilio entirely on this one because its like well thought out. 33:38 Status code 401. 33:43 401 means? 33:45 Unauthorized the, let's see the status is consistent. 33:46 The message is authenticate that's pretty clear. 33:51 We still have this weird code 20,0003. 33:53 So what do we do with that? 33:54 Click the link. 33:59 >> Click the link, the link helpfully named more info. 34:00 So, if you click this link this takes you directly to that error in 34:04 the documentation saying, here's what you from here. 34:06 This is a fantastic approach to take. 34:10 If you wanna give your users a fighting chance to use your API and 34:12 to recover from their own errors, this is the way to do it. 34:16 When we've got a situation like this, what happens here? 34:20 When somebody runs into this problem? 34:24 At some point they're either going to give up, and they're going to move on and 34:28 use some other API or they're going to e-mail saying, hey what does this mean? 34:32 What's the problem with e-mailing? 34:38 Now, we have to respond to the email. 34:40 Right? 34:41 And if you're trying to grow your customer base, the last thing you wanna have to 34:43 do is to respond to every email from every customer. 34:46 You want to figure out how can the customer help themselves to the point of, 34:48 we don't need to worry about them, they can take care of most things on their own, 34:53 we'll help them with this much smaller subset of things. 34:56 The more you can empower your users to solve their own problems, 35:00 the better off you're going to be. 35:03 So at Clarify right now we've got about 400 users on the system, and 35:06 we've implemented the Twilio style error messaging, so 35:10 we take people directly to the error documentation wherever possible. 35:13 Because we want people to solve their own problems, 35:17 we don't want them to be dependent on us. 35:19 And more than anything, we don't want them to have to stop and 35:21 think to figure things out. 35:23 We want to take them and lead them to the solution as quickly as possible. 35:25 Does that make sense? 35:28 And last up, logging and debugging. 35:33 So earlier you heard from, or 35:35 I guess later today, you'll hear from John Sheehan. 35:37 He wrote this great thing called Runscope, has anyone played with Runscope? 35:40 Oh, you should've okay, there's a couple people you should've. 35:44 Runscope is fantastic, it's this tool that it sits as a proxy between you and 35:46 the API, and it captures everything that goes on between you and the API. 35:50 So every portion of your request, the Headers and the body, 35:55 and every portion of the response, the headers and the body, get logged here. 35:57 And so you can go through and you can click and you can review any of the stuff. 36:01 Oh! And it alphabetizes it so it's nice and 36:05 easy to read. 36:06 you can review all of the request information. 36:07 You can view the response information. 36:09 You can go ahead and get a response play back URL. 36:11 So, if you're waiting for like a web hook to be called, you can capture the response 36:14 to that web hook, and replay it over and over and over again. 36:18 To be able to interact with your system to see what happens. 36:20 And my favorite thing here, is Start Comparison right there. 36:24 So when we launched our API from beta into production we opened up, Runscope. 36:29 We turned it on, we set the logging in place, we ran all of our test. 36:34 They're live test hitting the API, testing out functionality. 36:38 Then we turn it off, deploy the new system into our, our backup servers. 36:41 And then ran through the test again, capturing all the results and 36:46 did dif between them. 36:49 We are told pretty quickly that the only thing that changed between the two sets of 36:51 tests, were the date and the E tags, exactly what we were expecting to change. 36:55 So we had total confidence that our API was behaving exactly the same way, 37:01 regardless of what system we're using. 37:05 So that's what allowed us to go ahead and deploy interproduction for everything. 37:08 This is the sort of thing that you wanna give your users. 37:11 Give your users the ability, to plug into systems like this. 37:13 Give yourself the ability to plug into systems like this and you'll solve and 37:17 detect your problems that much faster. 37:20 So putting it all together, 37:24 hopefully you've got documentation that's consumable. 37:24 That's not PDF, it's hopefully HTML, even better Swagger Interactive. 37:27 Hopefully it's accurate and complete, the examples in there are succinct and 37:31 to the point, and hopefully not verbose in terms of providing a lot of 37:35 boiler plate code that needs to be reused and copied and paste all over the place. 37:39 Hopefully in the terms of adopting you've got logical and consistent API. 37:43 That it's predictable, that once you introduce a concept in one place, 37:47 that that concept applies consistently across the board. 37:51 It's when you change things and 37:54 you make people think, that things get broken, things get messed up. 37:55 Hopefully you've got one true way of doing things. 37:59 That there's not multiple ways of accomplishing the exact same task, 38:01 that there's one way, and 38:04 it's the way that you've documented, it's the way that you've engineered. 38:05 Hopefully the payloads are consistent and, oh God, 38:09 please don't roll your own authentication. 38:11 In terms of supporting, hopefully you've got error messaging and 38:14 handling that's consistent, that's accurate, 38:17 that's not lying to your users and even better, that's helpful to your users. 38:20 If you then guide somebody to the solution, 38:24 that's better than just leaving them and letting them try and 38:26 figure things out on their own, it's a fantastic way of going about things. 38:28 And hopefully you've got capabilities to do some logging and debugging. 38:32 So, that, that's 12 Reasons Your API Sucks any questions? 38:35 >> You guys know the drill first, let's give- 38:41 >> Okay. >> Keith a big round of [APPLAUSE] 38:42
You need to sign up for Treehouse in order to download course files.Sign up