REST API concepts and examples

welcome today I want to talk about what an API is and why it's important in web
development API stands for application programming interface and basically it's
something that allows one piece of software to talk to another
there's lots of different kinds of AP is but when you hear people talk about
twitter's api or Google's API but they're talking about is a rest api and
rest api stands for representational State transfer now it doesn't have to be
the case but usually a REST API works pretty much the same way website does
you make a call from a client to server and you get data back over the HTTP
protocol
now i think one of the best ways to show the many similarities between a rest api
call and loading a normal web page can be found with Facebook's graph api for
example let's pull up youtube face bwwm facebook.com slash youtube
we're all familiar with what facebook page looks like shows how many likes the
YouTube page has things like that but now let's change the www part to graph .
facebook.com slash youtube and what we get back is a response to our API
requests we've made an API requests in our browser to Facebook Graph API
now what we get back might appear to be gibberish to the human eye but it's
actually javascript object notation or Jason formatted data
it's structured data organized according to key value pairs the same way an Excel
spreadsheet is structured with key value pairs and you might ask for the data
that's in cell a 16
you can ask a JSON array for the data if you want to know how many likes this
facebook page had for the data contained under the key likes and all modern
programming languages will be able to interpret this jason response
one more concept i want to introduce the idea of parameters
let's reload that same Facebook API request but this time let's add fields
equal ID name and likes
now when we refresh the page you see that only ID name and likes have been
returned that's because these parameters have filtered the data that we get out
of this response
now let's take a look at another API example one that I think is really cool
is provided by google
maps and it allows you to take a city name or even an address and turn it into
a set of GPS coordinates as calm / maps / AP I / do codes last Jason
so remember what we just talked about the server that we're calling his maps
google api calm and then the particular resource we've drilled down its the maps
resource and then the API resource and then the geocode resource and we've even
added jason is a resource and that's because the google maps api can return
data in a number of different formats and then we'll add the following
parameters will address equal chicago and sensor equals false and as you can
see we've got another Jason response and if we look in the JSON array and we go
to the key results and then the key geometry and then the key location we
see the latitude and longitude coordinates for the city of Chicago
now that's great and all we got the geo location coordinates for Chicago but
would we do with them
well let's match to aps together and take those geo coordinates over to
Instagram and plug them into instagrams media search in . so in order to access
the Instagram media search in . without having to write any code
we're going to head over to instagram.com / developers and then on
the left hand side click on API console and we'll be able to use this API
console that's provided by AP i-- g or a piggy in order to make requests to the
instagram api without needing to write any code and you can see if you click on
the drop down on the Left there's a whole bunch of API is that this thing is
set up to allow you to play with
but for now we're going to use Instagram we're going to be using the Instagram
media search in . but you can see is that api . instagram.com / version 1 V 1
/ media / search then we're going to set the following parameters and you can see
that they're added to our URL request up at the top of the screen we're going to
set that equal to 40 1.87 and longitude equal to negative 80 7.62 and we'll set
a distance of twenty meters we click send and we get back this information
about a request we seem to get request and it shows where it was sent and what
parameters we passed in one of the parameters that we didn't say it was the
access token because that was automatically set by the a piggy
interface and then below that in sort of the blue and purple you have key value
pairs of headers that we sent as part of our request and then if you look over at
the response you can see we got a HTTP status code of 200 which means success
that everything went ok
and then there's some header information as well we've got x-ray limit limit
which is five thousand which is the total number of requests you can make to
the instagram api using one access token during one rate limit . and then down
below you can see x-ray limit remaining which is a 4994 which is how many
requests we have remaining in this rate limit window and then there's some
information about cookies and the content type application Jason things
like that and if we scroll down we'll see the body of the response which is
adjacent encoded array of all the images that matched the geo-coordinates that we
passed in and there's information such as you know what filter was used in
order to take the Instagram picture how many likes received how many comments
information about the user who posted it how many followers they have things like
that and then of course there's also the images themselves and if we copy that
image link and we take it up into are you all browser and paste it in and you
can see there is a picture from that location in Chicago you can even see the
Chicago skyline in the background
pretty cool right there's literally thousands of API is out there that you
can tap into and take their data and mash it up
pass it to another API chances are whatever website you want to work with
they have some kind of API that you can use in order to consume their data API
is that are available
check out ProgrammableWeb com up until now we've only been consuming data from
AP is but you can also write data to api's but before we go down that road
we need to talk a little bit about the concept of HTTP request methods
I think the documentation and description below but the big to that
you really need to know our get and post now a get request is what you used to
consume it and that's what you've seen us do so far by passing these URL
parameters in order to get data back from the API but a post request for
writing data to the API in the best practice is to actually put the data in
the body of the request now normal web browser doesn't allow you to put data in
the body of a request but you can do is you can install this handy extension
called postman rest client
the nice thing about working with postman
if you can make more complex API requests for example you can choose any
one of the available HTTP request methods and you can see a list of them
here
second you can add a body to your HTTP requests and finally you can add headers
so let's use the postman client in order to send a tweet out over the twitter api
before we do that though let's talk briefly about the concept of
authentication
obviously you need to give some kind of identification if you're going to be
saying tweets out because otherwise you could send tweets from my Twitter
account and I could send tweets from yours
and what a lot of these big online websites are using for their
authentication is so what's known as cloth or a loft to let me just say
briefly
basically what you're doing is you're getting credentials kind of like a
username and password although they're called a client ID and client secret and
then you're exchanging those for what's known as an access token and then you
pass that access token to Twitter and Twitter knows that the request to make
the queen is coming from you so it sends out the tweet from your twitter account
ok so let's go ahead and send out a text tweet using the postman rest client will
select post as our HTTP request method and then you'll see that the server
accessing is that api . twitter com
and then as we drill down to our tweet sending resource we got our at version
1.1 of the twitter api and then / statuses / update . Jason and again that
tells the twitter api that we want Jason formatted data as a response and we've
set the authorization header to are a lot of one . no credentials and then
down in the body of our post requests we've set the key status to test tweet
from postman and when we click send
you'll see that there's information about what time the tweet was created
the tweet ID that it was assigned information about my twitter account
with a twitter account that the tweet was sent from and then if we click over
on my timeline and we refresh the page you'll see sure enough that the test we
sent out shows up
yeah
yeah
yeah