Bummer! This is just a preview. You need to be signed in with a Pro account to view the entire video.
How to Evaluate an API Before Writing Any Code34:12 with Adam Duvander
We all know there are thousands of APIs we could use, so how do you decide whether to take the time to integrate with one? API veteran Adam DuVander takes you through the areas you should consider, questions you should ask, and some tests you could run. All before writing a single line of code for your application.
I live in the other Portlands, Portland Oregon. 0:00 so, show of hands if you're a developer? 0:04 That's like the easy question here at the Ultimate Developer Event, right? 0:09 So, so, we're all familiar with integrating with APIs. 0:12 And so today, I'm gonna talk about how you 0:18 might evaluate one of those APIs without actually having to write any code. 0:21 So, this is your typical developer. 0:27 I think we can see ourselves in there. 0:30 This might be a, this might be a junior developer here. 0:33 But so, when this developer wants to, wants to build apps, 0:35 they're going to be integrating with APIs probably to build that. 0:42 Hopefully, using Orchestrate as a database. 0:45 Certainly, in the cloud, maybe Facebook and Twitter for social login. 0:48 Even the, the internal services, the things within this developer's company, 0:53 are probably going to be built the same way that they consume other APIs. 0:59 And, this is a great, a great world that we live in where all of this is possible. 1:07 And, we can take these little bits from someone else's business and build it into 1:13 this beautiful beautiful world here where anything is possible, right? 1:19 But, as developers, we probably know that sometimes, 1:24 even though you want the, the API to look like this, it looks more like this. 1:32 And sometimes, it's easy to tell which ones those are, and 1:38 other times it's not so hard. 1:43 Not so, not so easy. 1:45 It's pretty difficult. 1:46 And so, this talk is gonna talk about what you do to be able to really rigorously, 1:48 determine whether an API is something that even worth your 1:53 time writing that line of code. 1:57 But, before you get to that, I think one of the things we all probably do 2:00 is do kind of the sniff test. 2:06 We might not all have as good of skin as this developer but, 2:07 but we're, we kind of look at an API and maybe give it the quick sniff test. 2:11 And so, I thought I'd go over the, the four pieces that I look at, 2:15 that maybe you do to, and then we'll dive deeper into that. 2:20 So, the first part of the Sniff Test is the documentation. 2:24 Who, who thinks documentation is really really important? 2:28 Right, yeah. So, not only this room tells me that, but 2:32 a survey a couple of, a couple of years ago, developers showed that complete and 2:38 accurate documentation was the absolute most important thing. 2:43 And, the thing that's funny to me about this is that 2:46 it's more important than whether the API actually stays up. 2:50 Like, developers would rather that an API be 2:53 well documented than actually available. 2:56 So, documentation, a big part of the sniff test. 3:00 Figuring out whether you can, 3:03 figure out, figuring out whether you'll be able to determine how you will use it. 3:04 Then, the next one that I look at is, is client libraries. 3:08 And, you'll see different opinions as to whether client libraries are something you 3:16 should be using. 3:21 But, it's an important aspect to be able to see how much they, how much 3:23 thought they put in and whether there are specific audiences they're catering to. 3:29 So, if you see client libraries you know, all for Java and .NET, you might make 3:34 certain assumptions about the market that they're going for versus node and go. 3:41 Something, perhaps. 3:47 But, just having client libraries shows that they've put thought into how 3:50 someone will use their API. 3:53 The next thing I look at, maybe because I'm, I'm a content guy. 3:55 So, I, I was at Programa Web for several years, and so 4:02 I read every API blog every day. 4:06 And, I can tell you that looking at the latest blog posts is a good way to 4:09 see where they're directed, or if, if they're directed. 4:14 A lot of times, you'll see nothing for months. 4:17 That doesn't necessarily mean anything, but 4:22 that, I think kinda comes up on the sniff test. 4:24 You wonder wonder if they haven't been posting there. 4:27 How, how dedicated are they to this API? 4:32 And then lastly, just so 4:36 I can fill out the ABCD, but it is an area that I look at, is the about page. 4:37 Try to figure out who are the people behind this, right? 4:43 Is this just sort of side project thing or is this something real. 4:46 And, a lot of times in the sniff test, 4:52 you can you can sniff out at least the ones that look a lot like this. 4:54 But other times, the things are things are really well polished, 5:00 and the sniff test doesn't find them. 5:06 And so, for that we have the bulk of this talk, which is going to be about the four 5:08 areas to provide a full evaluation of an API before writing the code. 5:15 The first is looking at control, 5:19 how much control are, is the API willing to give you? 5:23 Reliability, that second piece of that that survey, there, right? 5:31 That's, that's a pretty, pretty key piece, 5:36 even if it doesn't get props in the developers survey. 5:38 Security and whether their systems are, but also whether their practices are, 5:43 and how well, how well they help you and other developers to be secure. 5:50 And lastly, longevity. 5:54 Will this company even be around? 5:55 If you write some code, will it, will it still be able to, will it, 5:58 will it be able to get a response, you know, six months from now? 6:04 So, I think these, these areas help you to evaluate infrastructure APIs, for sure. 6:08 I like Orchestrate, which is a database SendGrid where I was previously, email, 6:15 certainly infrastructure and, and of course, anything cloudy. 6:20 Also Content APIs. 6:27 So, maybe some of these four things will be more important than others in 6:32 infrastructure and in content. 6:36 Whether it's you know content in the form like Pearson has where they, 6:39 where they take pieces of their books and slice and dice it and make that available. 6:45 Or, something more real time like stocks or, businesses, 6:50 that's factual on the right. 6:55 Or, application APIs where where it's an extension of an application. 6:59 These are two of the earliest API examples. 7:05 [BLANK_AUDIO] 7:07 Anyone familiar with this guy? 7:13 Anyone young enough to have watched? 7:15 Oh there's one who admitted it. 7:22 Okay. So I watched with my nephews. 7:24 So, this is Bob The Builder. 7:27 His name is Bob. 7:30 He is a builder, a construction guy. 7:32 And so, he he says, one of the recurring refrains in, in this show. 7:35 He says, can we build it? 7:45 And then, everyone shouts back at him, yes we can. 7:47 So, for example, if I were Bob, I might say, can we build it? 7:51 And then, you would say,. 7:55 >> Yes we can! 7:56 >> That was pretty good. 7:57 I wasn't, I wasn't sure about that. 7:58 All right. 8:00 So, as easy at that just was for me to get a room full of developers to say yes 8:01 we can, that's I think, also, our instinct, right? 8:06 Is, when we see a problem, that's what we do, we solve problems. 8:14 And so, when we see a problem, we want to try to solve it ourselves. 8:19 I think to get to this Utopian world that we talked about it's, 8:26 you know, that it's good to, to try to not always follow that instinct, 8:31 because there are many times when we don't need to. 8:36 But, if we can't build it, a lot of times, we'd wanna touch it, right? 8:40 Open source, running it on your own servers, 8:45 that's, that's the ultimate control, right? 8:47 Because, you know the code is there, and you can do something with it, and that's,. 8:50 That's good in, in some cases, but 8:57 in some cases it might not be the best first instinct, either. 8:59 However, I think that this sort of control, this sort of control that 9:04 you want, is something that you can ask for in other ways from API providers. 9:09 So, consider an API that you're that you're evaluating. 9:16 That API probably has some big competitors here, right? 9:21 And, they're all vying for the attention of the typical developer, or, or yourself. 9:24 And, there's actually a, 9:33 a key thing that some of these API providers will acknowledge, and 9:36 I think you can use, to be able to get that control, that you want. 9:40 And that is, that actually, their biggest competitor is probably you. 9:45 Their biggest competitor is not another API 9:47 that does the same thing, but rather you... 9:52 Saying, yes we can to building it. 9:56 You wanting, wanting to touch it. 9:59 So, I think you can use that to your advantage as you work with API providers, 10:00 and as you evaluate an API, to really, get the control in other ways. 10:06 One of the ways is to look for standards and conventions. 10:12 These, these are. 10:16 It always feels wrong to say multiple standards. 10:19 These are the multiple standards of distance between rails for for trains. 10:21 And that's the most common one. 10:30 And certainly, if I were to be building a train, I would maybe choose that one. 10:33 Definitely, I wouldn't choose one that isn't on this list. 10:37 Right. So, look for these standards or 10:41 these conventions and because that gives you the ability to, 10:43 if you choose a particular api provider, to then go to a competitor or 10:48 go to using your own, rolling your own. 10:53 One of the ways that orchestrate that, that we handle that is so 10:55 that we have a search api. 10:59 And, rather than creating our own way to query that API 11:02 we fall back on the Lucene Query Syntax. 11:08 So, if someone integrates with Orchestrate, 11:12 one of the ways that we provide control is to say, 11:16 you're not going to have to re-write all of your queries. 11:19 If you choose to leave us and go elsewhere. 11:22 Anything that uses Lucene query syntax, you'll be able to have the same queries. 11:25 You can get that with 11:30 client a similar kind of kind of reuse with client libraries too. 11:34 So, this is an example of retrieving, or, or 11:40 adding data and this is in our our node js client. 11:45 But, it pretty, pretty simple interface, right. 11:51 You can imagine that someone could take this and. 11:53 Right. 11:59 An, another library that uses this interface that then 12:01 stores data somewhere else could have this as a, 12:03 I mean, we could create it to store data in a competitor, right? 12:08 To, to really be able to say. 12:13 You want control over, over the you know, the way you use the service? 12:16 Well here's, here's a way that you can move somewhere else. 12:23 And, this actually has a, has some precedence, certainly. 12:26 I wrote a book on mapping APIs and. 12:30 I use this open-source wrapper library entirely, so 12:35 map-straction, which sits on top of about a dozen mapping APIs. 12:39 So that you could, I used to say to people, if Google ever 12:44 puts ads on their maps, or charges for them, you could quickly switch away. 12:48 Of course, they've done both of those now. 12:53 So, you can start on Google and if you get to the point where you have to 12:55 pay them and you don't want to, in one line you could switch to someone else. 12:59 So look for those sorts of easy switches, 13:05 whether it's from the community or from the API provider themselves. 13:09 [SOUND] I showed this slide at a conference last week and, 13:15 and got credit for showing shipping containers without 13:21 talking about Docker, so so I, I thought I would just. 13:27 Get credit automatically in this, in this group for that. 13:34 So, I'm talking here about data export. 13:37 And so, you want, if you have a, if the API has a way to put your data in, 13:40 then there should be a way to get your data out, and not just by. 13:45 API calls, but as in a full data export. 13:50 If you're adding your data, you should be able to get it 13:54 back in a format that you can then use elsewhere easily. 13:57 And that should be something that they provide because they 14:02 wanna make it easy for you to be able to have that control. 14:06 And so, you know, you're the biggest competitor. 14:11 If they don't have that then you can go and do it yourself. 14:14 And similarly, maybe you don't want to use their API at all, 14:21 if it is if it's say one of those. 14:26 Content APIs that I showed where it's maybe not the real time data but 14:30 updated periodically,uh, then why not give you all of the data? 14:35 Assuming that you still have some sort of business relationship with them. 14:44 In fact, Factual does just that. 14:48 So, I showed them on that slide and 14:51 they have data on millions of, of millions of business listings worldwide. 14:53 And, Factual has an API to access this, but 14:59 also provides bulk downloads to be able to take. 15:04 The, take the latest set of data and be able to use it and have that control. 15:10 And, one of the companies that uses Factual and has that control is Facebook. 15:15 Facebook uses Factual data for any time you put a place with a, 15:22 with a status update. 15:25 And, you can imagine that, 15:27 at Facebook scale, they don't want to be making API calls factual all the time. 15:29 Right? 15:32 And so, their able to get that control with the Bulk Downloads. 15:34 So, those, those are some ways that you can request control, I'm sure there, 15:42 there are more and that you know, don't be afraid to. 15:45 In your evaluation process to ask an API provider, 15:50 say, ask them point-blank what happens if I wanna leave you? 15:52 What does it take? 15:57 See how ready they are for that. 15:58 While you're talking to them, 16:01 you might also ask about their reliability, and certainly. 16:01 Can check on your own, but 16:10 the best API providers will actually be really open with that. 16:11 Anyone remember the the “Fail Whale?" 16:19 Good time. 16:22 Especially, maybe big conferences or Apple events. 16:24 Well, the Fail Whale itself I think is gone, 16:28 but Twitter downtime is not necessarily gone. 16:31 In fact, at South By Southwest, this last March, 16:35 I was giving a workshop on using APIs without, without writing code. 16:41 And so, it was kind of a if this then that, and happier kind of workshop. 16:46 And, a lot of it leaned on Twitter, of course, the Twitter API. 16:51 And, people in the audience started saying, you know, 16:55 this thing isn't working for me. 16:58 And, we finally figured out that it was because Twitter was having downtime. 17:02 Which made it difficult to give a Twitter workshop. 17:07 but, I actually wasn't the most difficult for me. 17:11 There was someone on the other side of the hall that it was more difficult for. 17:15 Biz Stone, one of the founders of Twitter was giving a panel, and 17:19 and taking questions about Twitter via Twitter. 17:26 On the panel when, when when Twitter went down. 17:33 So, a much worse experience for Biv's than for me, during that Twitter down time. 17:37 So, earlier I mentioned documentation as 17:44 the absolute most important for developers. 17:47 And, I joked about it being more important than uptime, but you can see there that 17:51 there's a pixel's worth of difference between documentation being first and 17:54 service availability and uptime being second. 17:59 And of course, service responsiveness and 18:02 performance, which is related to that second one is also pretty high there. 18:04 So, one of the common ways to be able to show this is a status page. 18:11 And, I think any API provider that wants to really show that 18:17 reliability is important has a great status page. 18:21 Twitter has one of those. 18:26 It's broken down by by areas of, you know, endpoints, sort of, 18:27 that you would, that you would call. 18:32 March 11 was that downtime that I talked about there before. 18:37 Strangely, absent from that is any actual data about. 18:42 Er, about how accessible twitter was during that time. 18:48 So, in this case, as, as great as it is, it actually breaks, 18:51 perhaps all three of what I think, are, should be the goals of a status page. 18:59 And, this is what you should look for when you're looking at an API provider. 19:04 And except, and evaluating their reliability. 19:10 So, transparent, helpful and proactive. 19:13 So, with those in mind, I thought I'd show a few examples of some of the areas 19:18 that good status, pages have. 19:24 So, one is to just provide status updates even. 19:29 Something textual and descriptive. 19:33 This is stripes. 19:36 This also goes out on their, on their, 19:38 they have a Twitter account specifically for, for status updates. 19:39 But, it just helps to, to show the, the issues, 19:44 if there are any, and the status of those issues. 19:48 And certainly, having a way to see the health, is also important. 19:54 And this is along the lines of what twitter was trying to 20:00 do with that example, right. 20:03 So, in these cases a couple of very simple. 20:06 You know, yes it's it's good. 20:10 And maybe, a little bit of information as of two seconds ago. 20:12 Right? The last push Facebook puts on there. 20:15 Twillio, similar to to the Twitter example, 20:21 breaks it down by endpoints there and, and then also shows a history. 20:25 And, the history is good too, cuz it's, you know, 20:30 great that you're healthy right now, what were you like for the last week? 20:32 And, maybe even showing that right down to response time, as Facebook does. 20:37 This over a day's period, but you break that down, show even more time. 20:44 Stripe does that in a way that I think's pretty cool, to show, 20:51 to color code by minutes of down time. 20:53 And so, you can see over I think, the last 90 days this is 20:55 the issues they've had in those three areas. 21:02 And then, anyone wanna guess. 21:07 Who I'll use as sort of the ultimate, status page for developer focused company. 21:09 No guesses? 21:19 Okay. GitHub. 21:20 GitHub, right, makes sense. 21:22 Very developer focused, and so breaks it down in detail. 21:25 Across many different areas. 21:30 And then, of course, you see there, you can say just today, 21:32 the past week, the past month. 21:35 So, GitHub and many of these examples are transparent, helpful, and proactive. 21:39 The three things you wanna look for in a status page. 21:46 [BLANK_AUDIO] 21:51 So, for, for people where security is a really important piece, 21:55 I won't be talking enough about it. 22:03 But I wanna make sure and cover it because. 22:09 It is something you wanna think about. 22:12 Ima, Ima gonna talk about some of the areas that 22:14 are a little less about the systems. 22:16 Certainly, you want their systems to be secure, but you know that's kinda like, 22:18 like asking a brick layer if they're going to use mortar, right? 22:27 Like. 22:32 It's sort of a necessary piece, of course their systems need to be secure and 22:33 a wall would not work very well. 22:38 If there wasn't something to hold it together, so the, 22:40 the security of systems is kind of that mortar that you would expect in a wall. 22:44 But, some other things that you can look for. 22:51 And, and see without writing any code are whether they're using, using standard, 22:53 using O Ot, that there's any sort of, end user data that, 23:01 that you're getting, you as a developer would be getting any access too. 23:08 And and certainly, that they're not using basic op, 23:14 that there's, that you never have to ask a user for their password, right? 23:19 So looking for those within social, sites. 23:26 Another, another one for social sites is privacy. 23:29 Figuring out, well what. 23:33 Do they have a, do they have a way to let 23:35 the user determine what I'm actually getting. 23:38 And, are there, are there, you know, 23:44 best practices set out for for that, the usage of that data. 23:46 And then, one of them that, 23:53 that I think is, is, something people think less about is, 23:58 if you're giving your data, or your users are giving your data to this API, 24:04 well, is there a process for who has access to that data? 24:10 Not just via API, but even on that company's side. 24:15 And, is there a way that's that 24:19 the company has to go through a certain steps before data can be accessed. 24:22 Hopefully, it's not as, as advanced as this as this flowchart, 24:27 which I believe is, this is a flowchart, for asking your boss for a raise. 24:32 And everything ends with no. 24:39 Look at [LAUGH] so, hopefully not as as 24:41 complex as that, but there should be a process for how data is accessed. 24:48 And and speaking of, of processes, sharing the best practices. 24:54 For those, on the developer's side. 25:00 Things like not sharing your API keys and 25:02 making sure that they don't end up in, in Github reposts. 25:08 Maybe, even proactively contacting, or, 25:11 or shutting down, services the way I know Amazon does when, ,. 25:16 He used to use to, easy to get, show up in GitHub re hubs. 25:22 So making it really easy for the, so why does this, why is this important to you 25:28 and to the developer who are clearly going to approach this in an intelligent way? 25:32 Well, it's a sign of other pieces of good security practice, 25:36 it's things you can pull out without auditing their systems. 25:41 And finally, data ownership. 25:44 You wanna, you wanna find someone that is open with, 25:51 if you're putting data in there, who, who owns that? 25:56 Yes, what can be done with it? 26:01 You know, your users that, and you want, you know, who, who owns 26:03 the data that your users puts in, put in also, and be up front and clear about it. 26:09 This is, terms of service didn't read, because we don't read terms of service. 26:13 So now, there's a website for, 26:16 if someone reads them [LAUGH] they can summarize them and put them up here. 26:18 And so, even if you hide something in your, or 26:23 if the API hides something in their terms of service, it's going to be discovered. 26:27 So, you want to hope that they're just up front about it and put that out there. 26:32 And, I think that's a sign of a secure API. 26:38 [BLANK_AUDIO] 26:43 So, this last point is is kind of a big one. 26:45 I think it's the one that people probably, 26:51 maybe after reliability think about the most after thinking about API. 26:55 So, this is face.com, who was a a facial facial recognition API. 27:02 It did some fun things like pull out mood and whether someone's smiling. 27:11 This is actually an example that shows that it 27:18 wasn't always particularly accurate. 27:22 But, it was fun, and I went to a lot of hack-a-thons, and 27:25 by the way, there's a hack-a-thon tonight that you should you should join in on, 27:31 Orchestrate will be there. 27:36 But, I went to a lot of hack-a-thons where, face.com wasn't there, and yet. 27:38 A lot of, a lot of people would use the face.com API because it was so fun. 27:43 But they were acquired by Facebook and 27:48 pretty much immediately shut down as an API. 27:55 And, t,hat got a lot of developers mad, 27:59 some of them may have cried, like James Van Der Beek. 28:05 and, for me it, it also hit me personally, 28:09 because I used a site that was built on top of face.com, a lot. 28:14 it, it let you, try to get, 28:22 they give you a score for the most surprised face that you could make. 28:24 And, you can see that I was on my way up to, to the, to the top. 28:29 You know, I never got a chance to get the, the, I don't know if there was a 100. 28:34 I didn't get to figure that out. 28:37 But, I was well on my way, and then Face.com shut down. 28:39 So, so these API shutdown's certainly hurt developers, also end-users. 28:43 So, we wanna try our best to be able to foresee these, 28:49 and this is, this is a difficult problem. 28:54 There's a great there's a great chart by John Musser who founded programmable web. 28:59 Where he details API business models that he sees. 29:06 And, this is one that, when I talk to API providers, 29:10 I really encourage them to, you have to know where you. 29:15 If you're an API provider, you have to know where you sit on here. 29:18 How does your API support your businesses model, your business revenue model. 29:23 And I think may be even more useful as a developer. 29:30 Sort of a you know, the reverse. 29:36 You're trying to figure out where an API exists, in this chart. 29:39 And then, if you, if you determine where they are, you try to figure out, 29:45 okay, does this makes sense for a company that, 29:50 will they stick around if they have chosen this business model? 29:54 And, hopefully an API, a provider is doing a good enough job in communicating. 29:58 Their value to you? 30:06 That, you can easily figure out where they sit here. 30:08 It used to be that when people would ask about which API to choose for 30:14 something I would say, I [INAUDIBLE]. 30:18 Going with the big company like Google or Yahoo is always a, a good choice. 30:22 You know? That company is 30:27 probably going to be around. 30:28 Right? 30:30 And, that's still true. 30:31 The companies are still around, but less true that the APIs will still be around. 30:32 Google has released a hundred plus public APIs and 30:39 you can see, yea, about a third of them are no longer with us. 30:44 So, so no longer is it safe to 30:49 to be able to choose a big company and knowing that API will stick around. 30:54 There are certainly other examples. 30:59 So Twitter, famously, has back-pedaled on it's on it's API platform. 31:02 And then, Netflix over, over a couple of years went from 31:13 a fully public API to what now in August, I believe. 31:18 The, yeah, so we've got like a couple of weeks left. 31:24 They announced so in June they announced that it's gonna be gone November 14th. 31:27 So, I mean, we could go on and on with these sorts of examples and I think that. 31:36 When long, when longevity comes up short, that you have to look back to control. 31:43 And, I'll repeat that both for 31:50 emphasis, and cuz it's fun to quote myself ten seconds later. 31:51 If longevity comes up short, fall back on control. 31:56 So, you want to be able. 32:00 If a company goes away, you want to be able to pick up just the same as you would 32:02 if just chose to go with the competitor or go with an open source solution, right? 32:08 So, you want to be able to have that control. 32:12 And so, as much as you can figure out whether the company will be around by 32:15 looking at their business model. 32:19 Do that, but you want to make sure that you have that control switch. 32:21 So, those are the four areas I thought I'd a fifth one, 32:29 a bonus one in here.That is personality, 32:33 so as your evaluated in API before you write any code. 32:38 See if you can figure out the people behind the company. 32:45 In the sniff test, you might see a little bit of that on the about page, 32:48 but hopefully the API has people that go to conferences. 32:52 Or, people who answer support tickets, people who are tweeting on, 32:57 on Twitter and really interacting with people. 33:02 Orchestrate has a community chat room. 33:06 That's another example where you're able to have access to the people behind it. 33:08 So, as you're evaluating APIs, see if you can find the people. 33:13 And I think the more access to the people you have, 33:19 whether it's a small company or a big company. 33:24 That's the more likely that you'll stay away from APIs that look like this and 33:29 hopefully by evaluating them and sticking to these five areas, 33:36 we'll be able to all live in this wonderful world that we wanna live in. 33:43 And, build great apps and be able to take advantage of 33:47 the bits of technology that we're able to get from other companies. 33:54 So, control, reliability, security, longevity, and yeah. 34:01 I'd love to show you my personality, and 34:04 it looks like we're well-timed with the class in the other room. 34:06 So, thank you. 34:11 [APPLAUSE] 34:11
You need to sign up for Treehouse in order to download course files.Sign up