 So, everybody, we're coming to learn all about consuming third party APIs. My name is Ceci Korea, and I work for a company called Return Path, where I work exclusively on an API called Context.io. And Context.io is an API that sort of abstracts the whole layer of integrating with a user's email inbox. So essentially, it's an API for email. So that's pretty much what I do day in and day out. And a large part of my work at Context.io is helping developers integrate our API. Sometimes that means that I get all sorts of questions, all sorts of issues happening with the API, and I've experienced some things, some weird questions, and that's kind of where this talk is coming from, because I feel like if we all kind of have a baseline of what it's like to work with a third party API, maybe we can move forward and rock this moving forward. So I think that the problem is that sometimes people come in from all walks of life, maybe they're self-taught, or maybe they just never really got to work with a third party API, and just to clarify, to me, a third party API is sort of like a public API that's accessible out there for consumption, like say an API like Twitter or something like that. So that's what I mean when I say a third party API. So we have a lot of people coming in from all walks of life. Maybe they've never really integrated with an API before, and you get some weird questions and weird issues happening. So there was a great blog post from Richard Schneemann at Schneem's on Twitter where he was talking about Rails magic, and it really struck me that, sure, we have resources, users, and that gives us all of these routes. So I think that, I'm not saying that there's too much magic going on, that this is a bad thing. Obviously, we all know how to do crud, I would assume, so who wants to be typing that all the time, right? But I think that maybe there's a little bit of a barrier, and sometimes people don't realize the difference between a get and a post and how that works when they translate that into a third party API. Maybe they know how to create crud and do that within your Rails app, but when it comes to figuring out what a get and a post means with someone else's API, some people are like, I don't know what's going on here. Story. I had a question from a developer saying, hey, my string, I'm trying to post something to your API, and my string is not working. Can you please take a look at it? And I was like, sure. And the string looked right, so I was like, okay, well, I'm going to look through my logs for this particular request, and see what's happening, and I saw that he was doing a get and not a post, and it looked like he was putting the string that he wanted to post, pasting it onto his browser, and then hitting enter. And that's a get, that's not a post. So I was like, how does that happen? There was another guy that was trying to also consume our third party API, and he was putting all his API requests on his route file, which I was like, no, that's not where that goes. So if you're face-palming right now, then pat yourself on the back, that means that you know stuff, and you are way ahead than a lot of people that I've come across. So what's in the agenda? I want to give you some tools that can help you consume third party APIs. Good, and do other good things, too. And if you understand that reference, you are awesome. So we're going to take a look at the anatomy of an API call. We're going to take a look at HTTP status codes and what they mean, because they actually have a meaning. Then we're going to talk about working with gems. And lastly, we're going to go over some tools for debugging and testing. And we're also going to do a demo. What, it's a lot of stuff. All right, so let's take a look at the anatomy of an API call. Hopefully, most of this is review. So this is essentially your components for an API call. You have your method, which is your verb, so that's going to be a get, a post, delete, update. Then you have your URL or endpoint. In this case, I just made something up called, where my slides go? There we go. I don't know why it's not working there. All right, you have your method, your URL endpoint, and your resource. So the thing that you're trying to access. So here's an example. This is the URL, aka the endpoint. And in this particular example, the resource is what you're trying to access. So that would be photos. Then you have the verb, so in this case it's a get, but it can also be post, delete, put, and that's called your method. That's the thing that you're wanting to do. Most people are familiar with this, so far so good. Then you also have headers. And headers is something that goes in your call and it has information about the call that you are requesting or receiving. Lastly, you have the actual body. So the body is the response that you get back. So in this case, if you make a call to get photos on some endpoint, then I would expect the response to be maybe a URL for that photo that I'm trying to get. And typically, that response is gonna be JSON. So far so good. I've made a few assumptions. I've made the assumption that you're using HTTP protocol. Made the assumption that this is a RESTful API. And also made the assumption that it's giving JSON back to you. Not all APIs work this way, but most do. At least, most are out there for public consumption will follow this pattern. So now let's talk about HTTP status codes. You're like, okay, well, why should I care about HTTP status codes? Because they're magical. They give you so much information and a lot of people ignore them and it's really beyond me why that happens. So let's take a look at the status codes in a nutshell. Status codes are not arbitrary. These have been established for a long time and they're sort of like agreed upon. A lot of people spend a lot of time and a lot of pain over trying to figure out what the correct status code is to give back to a developer. So they really are important and you should really pay attention to what they're trying to tell you. So I'm gonna focus on the status codes that you're probably gonna encounter the most when you're trying to consume a third party API. So in a nutshell, 100 range informational, 200 range, everything's cool, 300 range, go away. Mostly you're gonna be dealing with that when you're dealing with OAuth. 400, you messed up, 500, we messed up. A lot of people don't really realize that. So 200, all right, so we're getting something in there. Not really sure what's going on there with my slides, not showing up. But essentially, let's skip over the 200 range, because we're pretty much all good with 200, it means everything's good to go. There's 201 created, which means you're probably trying to create some resource on the API, and then it worked. 201 means, woohoo, created. Then there's also 202, which I love, because essentially when you read it on the spec, it says, I got it. It's not actually saying created, it's saying, I got your request. I'm not doing anything about it right now, but I got it. So I feel like those three are really important when it comes to working with APIs, because again, they have meaning. 202 means I got the request, haven't done anything with it. So it's not saying that yes, it was done, it's just saying I got it. Whereas 201 is saying yes, definitely I created it. So there's definitely a difference there that you gotta pay attention to. Another thing that I feel is really important, especially if you're working with something like web hooks, how many of you know what web hooks are? So essentially a web hook means it's sort of like an event listener that looks for some sort of thing to happen, and then the API will notify you when that thing happens by giving you a post back on a callback URL that you designate. So you can say, hey, API, I want you to let me know when this happens, and this is a URL where I want you to alert me. So what happens is that developers need to reply with a 200 so that we know that everything is working correctly and that we can post back. And sometimes I see that developers reply with a 201. And I mean, that's still fine, we still post back. But I'm like, 201 is not the right one, should be 200. So anyway, so 400 is one that I see a lot that people have questions about. Which again, your request is bad and you should feel bad. And a lot of people don't pay attention to what that means. When you go and you look at the spec, it literally means there's something wrong with your params, the request was not formed correctly and you should not repeat the request as is. And a lot of people don't take the time to go and be like, okay, well I guess I should go and look at my params. So I think that that's really important. There hasn't really been an instance when someone is like, hey, I'm getting a 400 and it wasn't their fault. So again, get a 400, check your params. This is probably gonna break it again. I had a really cool gift of Gandalf going, you shall not pass. To talk about 401 unauthorized. Because that's essentially what 401 means. 401 is one that you might come across a lot when you're working with APIs that expect some sort of authentication. Because what that means is, hey, the server is expecting you to pass in credentials and the credentials failed. So again, I get a lot of requests for help whenever there's a developer that's getting a 401. And they're like, no, but I know the credentials are right. And then we debug it and it's like, somebody changed, somebody created a new secret or something and that's why it's raking. So again, if you're getting a 401, check your credentials. The other one that's kind of related to the 401 is the 403, which I love. Because it reminds me of Lucille Bluth in that episode of Arrested Development when she's like, I don't understand the question and I won't respond to it. That's essentially what 403 is. 403 says, I understood the request. I'm just not gonna do anything about it. Because likely credentials are wrong or you don't have access to access whatever it is that you're trying to get to. So that one is also one of my favorites, 403 Forbidden. The other one that people are probably really familiar with, let's just go ahead and unplug and plug back in again, is 404. 404 means file not found. Most people know this. Most people that aren't even web developers know 404. And that's probably because if you've ever accessed a website and you went to a web page that doesn't exist anymore, you get a 404. And a lot of people, again, sometimes contact us and they say, hey, I'm having trouble with the API, I'm getting a 404 on this. Can you check it out? And I go check it out and I look through our logs and I'm like, I see a delete request for this resource that you're trying to access. And that's why you're getting a 404. So if you're getting a 404 on some resource, go back and see if maybe there's some request that deleted that resource. Maybe. Again, status codes don't lie. The next one that I want to talk about is, nope. It is 418, I am a teapot. And a lot of people don't know about this status code. And I like it because it shows that people are funny. It shows that we can have fun with HTTP status codes. So essentially, in April of 1998, somebody released a April Fool's joke for Hypertext Coffee Pod Control Protocol. And it was essentially a protocol for controlling, monitoring, and diagnosing coffee pots. So 418 means I am a teapot. So that's why it's a 400 because it's an error, right? You're trying to inspect a coffee pot and you're actually inspecting a teapot. So I feel like that's so awesome that this exists. And you can actually find it out there in the wild. If you go to google.com slash teapot, you can see that they have a I am a teapot sort of landing page. If I open up the inspector, let's pull it up and let's go to network. I'm gonna try to find this or I can just just gonna do preserve log and refresh so that I do the request again. Now I can see the request here. It's in red and it's kinda tiny and unfortunately, I can't really make this part a little bit bigger. But you can see here that I did a get on teapot and the status code was 418 and it gave me I'm a teapot back. So that's how it works. It's awesome. So status codes, they're not so boring. The other one that you should take a look at is 429 status or API limit reached. And the reason why that one is really important and a lot of people ignore it is because when you're working with an API and you get a 429, that means that you're exceeding your API limit. This actually happened the other week to a developer that I was working with. He was like, hey, sometimes when I make this call and I pass in the exact same parameters, sometimes I get a response and sometimes I don't. And I was like, aha, that's a red flag. Whenever you're making a call and sometimes you get a response and sometimes you don't, that means there's something going on there. And it's likely, it could be throttling. In this case, it was that they were reaching their API limit. So whenever they were making that call, they were getting a 429 and they weren't logging it because they were expecting probably a 200 and they were expecting a response. So they were essentially ignoring it and that's why sometimes it was giving them nothing. So then I went back and I looked at our logs and I was like, wow, you have like thousands of 429s in the last month. So may wanna check for that? So I think that that's definitely one to look out for. And another thing to look out for is, I think a lot of developers always look for 200s and they don't try to look for or log anything other than that. And sometimes you might in this case get something like a 429 and you're completely ignoring it because you were expecting something else and then you don't know what's going on. So you got to pay attention to that. And then you get into the 500 range. 500 is just literally like, it's just kind of like the most basic response. So usually if I get a 500, I don't freak out. I just try again, try to figure out what's going on. If I start getting 503s, that means unavailable. That means API is down, okay? And you gotta go check it out. It could also mean that you're being throttled. So I would say, if you start getting 503s, that would for me be cost for alarm and I'd be like, okay, what is going on? So for real, pay attention to the status codes. They're there for a reason. They have a meaning. They're not arbitrary. They don't lie, okay? Status codes don't lie. So pay attention to them. No one expects you to memorize them, okay? This is the spec. This is the HTTP protocol spec and I can go in, I can look for 403 forbidden. I can go click on it. I can go read what it means. Nobody expects you to memorize all of that, right? There are other resources out there, like for example, HTTPstatuses.com that's out there and it's a lot more friendly and essentially all you have to do is just like, if you remember the URL, you just do HTTPstatuses.com slash 201 and then you can go see what that is. So when I started working with APIs, I would essentially have this open all the time so that I could see like, okay, what error are people getting? Let me go see what that means. And then after you do that, after a while you start being like, okay, 429. Yeah, I know what that means. So again, tons of resources out there to help you. So next, let's talk about authentication. So some APIs require authentication, some require no authentication and then some others require users to authenticate. So there's like three layers that you could be dealing with. For no authentication, that literally means that you don't have to get an API key. You don't have to pass in any credentials to the API. So a couple of those, there are examples of an API that don't require authentication is OMDB, the open movie database and the open weather map. I think that that one has some calls that requires authentication and some that don't. And then data.gov, I think also has a lot of resources out there where you don't need to authenticate. Then you have developer authentication and that essentially means that the API wants you to prove who you are. They want you to get an API key so that they know who you are when you're trying to develop. So that means you need to get an API key and a secret. And then how you authenticate with that API depends on the API itself. Some APIs will want you to pass in your credentials as a param. Some other APIs will want you to put that in the headers. There's really no like baseline, a lot of different API supplement this differently. So you're gonna wanna go to the API documentation and see how they expect you to sign your requests. So for an example, I've been doing some work on a personal project with the Meetup API and I found exactly how they want me to do their signatures and then they also provide an example. So then I can follow this and I know exactly how I need to authenticate for that API call to work. So let's make some test calls. What? All right, yes, I was making some test calls earlier. Hopefully that's somewhat big enough I can make it bigger. Okay, so I'm gonna use curl. A lot of people don't use curl and this is something that you have already in your terminal if you're a Unix-based terminal, if you're on Windows, I think you have to download something. I don't know, I'm not a Windows user, I'm sorry. But if you have a Unix-based terminal, you should be able to just start curling all day long. So I'm gonna just do a call to OMDB. I think it's OMDBAPI.com and then they want you to use S equals and then your search. So I'm gonna search for frozen and then hit enter. And then that gives me JSON back. So I can see that the first title was frozen 2013. We probably all know that movie. But then you can also see that it returned to me some other titles that have frozen in the title like frozen land, never even heard of that movie. Workcraft 3, the frozen throne. What? Didn't even know that existed. So that's an API call that doesn't require authentication. And as you can see, it's HTTP, it's not HTTPS. So let's make a call that actually requires authentication. So I'm gonna try a call to the Meetup API, HTTPS. And it's api.meetup.com slash two slash events. I kind of memorized this already, key equals. And I'm gonna go look up my key because that is the one thing that I did not memorize. And then ampersand, group, URL name, equals, I'm gonna search for girl develop it. Guess I was doing some work for them. So girl develop it awesome. And sign equals true response. And this one was basic authentication. Essentially all I did was just put in my key and then say sign equals true. That's it, super basic authentication. So there are other ways that you can authenticate. You can do authentication for the user. So not just for the developer itself, but for the user. Sometimes if you need to get a user to give you permission to access their email inbox, their Facebook profile, their Instagram photos, they need to authorize. So for that you would have to deal with user authentication, most likely with OAuth 1.0 or 2.0. And this is called the OAuth dams. And this is where you come up with a lot of 302s which essentially redirect you to another place. So in these instances, you're gonna have a user and the user's gonna be redirected probably to like Facebook or Gmail or something and they're gonna have to click authorize and then they're gonna be redirected back to your app. And all of this is actually pretty complex and there are a lot of rules and there are a lot of things I need to pass. So luckily there are some libraries that will help you do this. And then also some APIs will just go ahead and facilitate this process for you. So for example, the API that I work on called Context.io, we have a call that you can make that essentially fires off the OAuth process. And all you have to do is just pass in the email of the user that you wanna add. So pretty neat and handy. So let's go ahead and test that out. But before that I did wanna give a quick word on authentication versus authorization. So authentication, prove you are who you say you are, authorization, make sure that you are authorized to access what it is that you want. This is also within the realm of OAuth, this is known as scope. So whenever you go to a website and you try to authenticate and grant access, you see this little pop-up guy and it says, would you like to give this app access to your email inbox or whatever? That's called the scope. It's the permissions that you're requesting, the actions that you want to do on behalf of the user. So that falls on something that you would do through OAuth. So let me show you something real quick with that. I have a sample app that I think is running. And essentially I created this app specifically to test OAuth with the API that I work on. And this is like super simple, terrible using Bootstrap, and I'm also using device just to handle registration. And all I did, this is like a throwaway app that I'm just using whenever I need to test OAuth. So I'm just gonna create a user, we're gonna call it API all of that. And this is gonna fire off, signing in. So one thing that I like to do is just go ahead and open up my network tab and click on preserve log so that I can start seeing what's happening. So now if I authenticate, I can actually see okay, now it's redirected here. And this is where I say yes, you can have access to my app and it's gonna keep on going and it's eventually gonna redirect me back to my app. And what I find that is really helpful is just looking at all of the requests. This can be a little bit like involved to read, but you can essentially find exactly where the redirects are happening so that you can kind of see what's happening and what's going on. So here I can see like oh, I missed like callback 302. Okay, this is where I sent the user over to Microsoft. And then after that, I can see other requests. Like for example, this is where the user logged in. You can see it was again, it was a 302. You can see everything that's happening there. And one thing that I also find useful when I was trying to learn OAuth and how OAuth worked was to just do a right click on this log and then just say, copy all as hard or HTTP archive. And then that's gonna create a text file. Save as hard with content? Yeah, that's the one I want. Okay, so I'm just gonna call this test. It's gonna open on my desktop. So now if I open this in the text editor of my choice, I can see a whole log of all of those calls. And I found this really useful to see exactly what was happening in each step of the OAuth process. It's kind of involves to read, but you can just do a quick search. Like if I wanted to go and find one of the redirects, just type 302. Hopefully it's actually gonna take me to a place where there's an actual 302 happening. You get the idea. So I found that really useful to just click preserve log, download that log, read it, see what's happening with that OAuth process. Cool. So now that we did that, let's take a look at some tools for productivity. So Postman is a tool that I absolutely love whenever you're working with APIs. Here I'm gonna try to do a test call to Twitter. And in this case, I'm gonna be using OAuth 1.0 to authenticate. So the first thing that you wanna do, for example, is take a look to the Twitter API actually. Here I had to go and get an API key. One thing about this is that I'm showing you all this for example purposes, but typically you don't wanna ever share your API key or secret with anybody. So if that ever happens, just generate a new secret. So be careful with your API credentials. So here I have my consumer key and all of that stuff. And when I go look up the docs for Twitter, a lot of APIs are super helpful in this way. So say that I wanted to do this call, which is a call that I'm about to do, which is users.show. It's gonna give me information on my user. So if I take a look at here, I can go to OAuth signature generator, select the app that I'm trying to work on, and then it's gonna generate this for me. So you can see my consumer key, it filled out my secret. I can say what it is and then do get OAuth signature and then it generates all of those parts for me as an example of how to properly do a signature to authenticate with Twitter. So I know that's really involved and that's a lot to do. So postman really simplifies all of this process. So here, and just to clarify postman is like a Chrome extension on steroids that you can download is essentially sort of like a browser and it does a lot of these things. So when you're in the builder part of the app, you can put in all of those things and it'll actually generate everything that you need to sign the request. So in this example, I select OAuth 1.0, which is what Twitter told me I wanted. I put in my consumer key, my secret, and then postman automatically is gonna generate a timestamp for me and it's gonna generate a nonce. A nonce essentially means it's a number used once and it's sort of like a unique identifier for that call that can only be used once. And you can't just like put in a random string of numbers, like you actually have to generate the nonce. So I find postman really helpful in this whole like process to try to get a quick call out there. So I'm just gonna go ahead and click update request and if you keep your eyes on the timestamp, you'll be able to see that and the nonce, you'll see that it generates a new one. So now when I hit send, it's actually gonna give me the response. So you can see here everything that I would get back and the great thing about postman is that it also keeps your history. So if I ever want to go back and see how did I make this call, I can go to postman and if you're saving your history and not deleting it, you can go and click on that and see exactly everything that you passed in and how you made that call. So that is super helpful when you're still trying to learn an API and how to work with that. So I love postman. Some of the things that it has on the paid feature, you can have teams and you can have environment variables so that you don't have to like put in the same things over and over again. So that's a paid tier, but I think that you don't, even with the free tier, there's a lot of stuff that you can get from postman. It's an amazing app. Highly recommend that you use that. So now, okay, we made a call. Let's talk about gems. So I think that a lot of developers start off by saying, hey, I wanna work with this API. Let me go see if there's a gem for that. And they miss out on this whole idea of like actually making calls to the API themselves. So they kind of like skip a step and they go straight to the abstraction. And I feel like, ah, you should spend some time making some calls to the API, curl or postman and just do that. It's like a game of ping pong. Just get started there, see what you get. Get familiar with the API before you start working on a gem. It's gonna be so much easier once you get to that point where you're ready to start developing with the gem itself if you spend some time making some test calls. So how would you choose an official API wrapper for whatever API you want? Pretty easy, you probably already know this. You wanna look for official libraries. You wanna look for things that have a lot of maintainers that's been updated recently, blah, blah, blah. We all know this. But what happens if there are no libraries available? What happens if the library that's out there kinda sucks? So as an example, hate to throw anybody under the bus but let's take a look at Instagram. This is the official gem for Instagram API and you can see already it's Facebook archive and you can see the last time that this was worked on was eight months ago. And then you scroll back and you're like, oh, this project is not actively maintained. Crap, what am I gonna do? There's no gem. Here's another example of an API client that I was looking at and I was like, oh, this does not fit my needs because it's just poorly documented, also not very well maintained or maintained often. So I was like, yeah, no, let's do this myself. So you can create your own wrapper. If you already know how to make calls against the API, all you need is to just develop straight against the API and all you need for that is a HTTP client and there's a ton that you can choose from. There's HTTP Party, which is my favorite. There's Faraday and there's another one called HTTP the gem. Then there's also the native one that pretty much comes standard and that's net HTTP. There's a great presentation here that you can take a look at that's linked from my slides that goes into comparing all of those HTTP clients. If you wanna go down that rabbit hole, be my guest. And all HTTP clients are kind of built on top of these three libraries. So there's net HTTP, Xcon and HTTP client. And then there's also Patron, which uses libcurl and other libraries are essentially wrappers of all of this. So HTTP Party is a wrapper for net HTTP, Faraday is a wrapper for net HTTP, Xcon and Patron it actually lets you select and HTTP the gem is just a native implementation of HTTP. So it's not actually yet another wrapper. So you're gonna wanna do a little bit of research on the gem that you select because some of these gems that are wrapping another library on top of it do things like retry calls and you may not be expecting that. So you're gonna wanna go and do a little bit of research into which library uses which other library for your project. So I was gonna do a demo of using HTTP Party to create your own wrapper but unfortunately I'm almost out of time. So if any of you want to see that come find me later I'm happy to give you a tutorial on that or find me on Twitter again happy to guide you through that. So I know that it might sound a little bit crazy to say like okay well I'm gonna use say HTTP Party which is a wrapper of net HTTP to create my own wrapper. It's like inception over here. Oh and you can't see my GIF damn it. So that's just yeah okay it's one thing to keep in mind. So one thing that I wanted to show you with the two minutes that I have left is some tools to help you actually like work in debug APIs. So one tool that I use a lot is called Request Bin and essentially Request Bin is a sort of temporary bucket where you can throw HTTP responses. So whenever you need to test like an endpoint you can create a Request Bin which is essentially again a throw away bucket and this is the URL that it gives you and you can use this to try to capture other requests as they come in. So for example here I set up a Request Bin on my email address so that anytime that I get an email I would get a post back notification and here you can see the post back notification that this was. This was an email from Ruby Central about Rails Conf and I got a notification for that on my Request Bin. The other one that I wanted to show you is Mach Bin which essentially works very similarly to Request Bin so I want you, those of you who are on your computer go to Twitter and tweet at me. My username is C-E-C-Y-C-O-R-R-E-A. So I set up a web hook on my email that looks for emails from Twitter and anytime that I get an email from Twitter it's gonna trigger my web hook. So if any of you tweet at me or favorite something that I do on Twitter and I get an email notification I'm gonna see that right here on Mach Bin. So I'm just gonna, whoo, somebody, somebody like something on Twitter, woohoo. Okay, so I can see here essentially what Mach Bin is doing is that it's sort of like working as an endpoint that's grabbing those requests and I find this super helpful especially when I'm working with web hooks so that I can actually see the response that I get back from the server because a lot of APIs don't always document the actual reply that you get from the web hook. So if you ever need to know exactly what you're getting back from a server go to Mach Bin, create a bin, use that as your endpoint and then magic happens. Let me refresh one more time before we're done. See if I get any other, all right. So that's it and if you have any questions talk to me out in the hallway track.