00:00:10.610
Sweet! Alright, thanks everybody for coming to learn all about consuming third-party APIs. My name is Cecy Correa and I work for a company called Return Path, where I work exclusively on an API called Context IO.
00:00:20.700
Context IO is an API that abstracts the entire layer of integrating with a user's email inbox. Essentially, it's an API for email, so that’s pretty much what I do day in and day out.
00:00:38.820
A large part of my work at Context IO is helping developers integrate with our API. Sometimes, this means I receive all sorts of questions and issues related to the API. I've encountered some unusual inquiries, and that’s where this talk is coming from.
00:00:56.100
I believe that if we all have a baseline understanding of what it's like to work with a third-party API, we can move forward and tackle this together. The problem is that people come from various backgrounds—some are self-taught or have never really worked with a third-party API.
00:01:14.280
To clarify, a third-party API is similar to a public API, such as an API like Twitter. This applies to situations where many developers may not have integrated with an API before, which can lead to strange questions and issues.
00:01:33.090
There was a great blog post by Richard Schneeman on Twitter, where he discussed Rails magic. It struck me that while we have resources, users, and many routes available, sometimes people do not realize the difference between a GET and a POST request and how that translates to a third-party API.
00:01:51.600
They might understand how to create and manage CRUD operations in their Rails app, but when it comes to understanding what a GET or POST means with someone else’s API, they might be lost.
00:02:08.760
For instance, I once had a question from a developer who said, "Hey, my string is not working when I try to post something to your API. Can you please take a look?" I checked, and the string looked correct. However, upon reviewing my logs, I saw that he was doing a GET request instead of a POST.
00:02:27.520
He was pasting the string into his browser and hitting Enter, which is a GET request, not a POST. This highlighted a gap in understanding that can lead to confusion.
00:02:43.260
In another case, a developer was trying to consume a third-party API, but he was placing his API requests in the routes file, which was not the correct location. If you're facepalming right now, pat yourself on the back because you know better than many others.
00:02:59.710
What’s on the agenda today? I want to provide you with some tools that can help you consume third-party APIs more effectively and do other good things. If you understand that reference, you are awesome!
00:03:17.270
First, we'll look at the anatomy of an API call, followed by an exploration of HTTP status codes and their meanings. Then we will talk about working with gems, and lastly, we will discuss some tools for debugging and testing. Plus, we'll do a demo!
00:03:37.100
Let’s begin by examining the anatomy of an API call. Hopefully, most of this will feel familiar. Essentially, you have your method, which is your verb. This could be POST, DELETE, or UPDATE.
00:03:51.430
Next, you have your URL or endpoint. In this case, I just made something up called 'where my sites go.' You have your method, your URL endpoint, and the resource you are trying to access.
00:04:07.150
For example, in one case, the URL (endpoint) is the resource such as ‘photos’. The verb here is a GET request, but it can also be POST or DELETE and is referred to as the method, which describes the action you wish to take.
00:04:27.040
Typically, the body of the API request contains the actual response you receive back. If you make a call to get photos on an endpoint, you would expect the response to include a URL for the photo you're trying to access, and this is usually in JSON format.
00:04:46.240
I've made a couple of assumptions: first, that you are using the HTTP protocol; second, that this is a RESTful API; and lastly, that it returns a JSON response. Not all APIs work this way, but most public APIs do adhere to this pattern.
00:05:02.680
Now, let’s discuss HTTP status codes. You might wonder, why should you care about HTTP status codes? They're crucial because they provide a myriad of information, yet many people ignore them.
00:05:19.690
Status codes have not been established arbitrarily; they're standardized and widely accepted. Many developers spend considerable time determining the correct status code to return, so they’re certainly important.
00:05:39.200
Let’s look at the most common status codes you are likely to encounter while consuming a third-party API. In a nutshell: 100 range indicates informational responses, 200 range means everything is good, 300 range means redirection (go away), 400 indicates a client error (you messed up), and 500 indicates a server error (we messed up).
00:06:00.870
Most of us are pretty familiar with the 200 series. For example, a status of 200 means everything is OK. There's also 201 (Created), which means you have successfully created a resource, and 202 (Accepted), which essentially means, 'I got your request, but I’m not doing anything with it right now.'
