More API fundamentals and terms

Most of this is directly taken from codecademy’s awesome twitter/api tutorial, with comments to help me remember/learn.

There are four http verbs aka methods, giving us four request types. They are:

GET – Retrieves information from the specified source. Like in my previous post when I requested info from placekttien.com

POST – Sends new information to the specified source – Like when I add a new blog post.

PUT – Updates existing information of the specified source – Like when I update a blog I’ve already posted.

DELETE – Removes existing information from the specified source – Like when I delete a tweet because it was a picture of my hangdaddy and the world wasn’t ready.


An HTTP request is made of three parts.

The request line, which tells the server what kind of request is being sent (GET, POST, etc), and what resource it’s looking for.

The header, which sends the server additional information (like which client is making the request).

The body, which can be empty (as in a GET request) or can contain data (like for PUTing and POSTing info).

They gave an example, but I found it kind of confusing in terms of which was was which part.

request


Endpoints are API-defined locations where particular data are stored, and affect what data you get back. The give two good examples:

  • I could GET a bag of nuts from the Nut House, or GET a pair of pants from Pants World. I use GET for both, but where I go determines what I receive.
  • More realistic example – if I’m using an API for a video hosting service, there may be endpoints for popular videos, more recent videos, or ones in a certain genre/category.

API keys grant you access to a particular API. They also identify you to that API, helping the API provider track how their service is used and prevent unauthorized and malicious activity. They’re often long alphanumeric strings like this:

api key

They mention that OAuth is a protocol often used to by API’s to request authentication (like when you get redirected to a page asking for permission to access your account).


A response is the message a server sends back to the client, and is the result of a successful request to that server. These contain a 3 digit status code. They start with 1, 2, 3, 4 or 5, each meaning a different thing. Here’s the gist of each, and the full list can be found here.

1xx – Informational – Apparently these are rare. They happen when the server is saying “Got it, I’m working on your request”.

2xx – Success – These mean “Okay!”, and the server sends them when successfully responding to a request. 200 is the normal response to HTTP requests, and the one you should be hoping for.

3xx – Redirection – Means “I can do what you want, but I need to do something else first”. The example they give is that if a website changed addresses and needs to reroute the request before it can get you the resource you asked for.

4xx – Client error – Usually means you (the client) made a mistake or don’t have access to it. The famous 404 error comes from this. 401 means that you don’t have access to that resource (I got this by messing up my api key in a request).

5xx – Server error – Means the server messed up and can’t respond to the valid client request.

They had me do an example. I started by requiring the uri, which gives me the tools to the requests. I then opened the kitten place website and set it to a variable kitten, and then made a second variable equal to the kitten variable with the status method called on it. Finally, I used the PUT HTTP verb to display the status of the site, which was 200, aka good.

200 response

Making dapper-ass cats through ruby requests

The code academy example has me using ruby, which I’m not really familiar with (I did their course like a year ago and vaguely remember some stiff), but the gist was the following:

First, you’ll want to require the ‘open-uri’ module, which is the ruby way of bringing in additional methods and constraints to make the HTTP request. A module is a bucket of extra Ruby tools.

require = ‘open-uri’

Next, you’ll want to declare a variable and have it open the url we’re grabbing from.

kittens = open(‘http://placekitten.com/’)

This prepares us for the GET request we do next, which is slightly confusing because it’s not written as GET but instead as ‘read’, which is another ruby term (I’m hesitant to call it a method, but that’s what I think it is. Apparently methods are words you use to execute other programmers’  code).

body = kittens.read[559, 441]

So, what happened above: I believe I set a variable called body, and set it equal to my other variable kittens, with the read method enacted on it for the specific character numbers listed. Although I’m not sure what they mean by character numbers, and I forget if the way it’s written implies just those two numbers, or everything in between.

Finally, I use the puts method on the body variable so I can see the data I got back on the line where I opened the placekitten url.

puts body

I included a screenshot to show what this looked like, and the result:

Screen Shot 2014-02-04 at 1.59.27 PM