An understanding of APIs is key to modern web development. The reason this tutorial is in the "Process" section is because building your application from an API perspective leads to long-lasting code that all the developers in your team can use and less throw-away code. In this tutorial, we'll cover the use of 3rd party APIs to give you an idea of how you can incorporate your own to isolate separate layers of your codebase into clear interfaces.
Prolific East Coast investor (from Union Square Ventures), Fred Wilson, I remember once mentioned in a video that he forecasts the future of the web being all about mashups of APIs. What that basically means it that apps will be getting data from tons of places (currently Facebook, Twitter, etc) and sending data back. These days you can build tools using other tools that are mashups. For example Twitter Feed helps you post to Facebook and Twitter from your RSS feeds. So basically you’re going indirectly through another mashup to accomplish your automated posting to the said social networks. That’s a basic example, but the basic idea is still the same: everyone’s building stuff on top of other applications, and people are building on top of that and so on.
So what is an API? An API is a programmatic way to send input to another web application and get output back over the internet. So rather than visiting a web page in a URL, your application can visit special URLs that return data in consistent formats that your app can then interpret and use to go about its business. It’s a way for one app to communicate to another. This is so powerful that large soon to be public companies like Zynga have made billion dollar businesses using APIs of other companies, i.e. specifically Facebook. Zynga’s going to go public before Facebook! Isn’t that crazy.
Back to what Fred Wilson was saying. He’s basically saying that an internet behind the scenes is emerging. It still uses the HTTP protocol like your web browser does, but its your app code that’s doing the communication to accomplish its own unique goals. As a result we have entire companies, like the new Ness (http://www.likeness.com), which do nothing but mine data from other sites and build an intelligence based on that information. Ness, for example, plans to harvest data from tons of places to build a minor form of artificial intelligence that will help you search and get results based on your tastes. A lot of guys have tried to do this to a degree, but it’s about time for this to get really real--because of the shear amount of data you’re putting out on Twitter, Facebook, iTunes, etc, about what you like.
So how does this actually work in an actual application? Basically you write code to ping a URL, and in the URL you specify for example a user ID of a Facebook user, and you can get their information in a consistent structured format that your code can then parse. For example here is the basic information about one of the most famous Facebook engineers, Bret Taylor:
That data happens to be public. For private data you would specify basically a password in the URL (that you usually have stored in your database) to get access to that facebook info. We’ll cover in another article Facebook authentication, but basically Facebook, Twitter, etc, all provide ways for end users in their browser to pass you a special password (“access tokens”) to gain access to their data and post updates/tweets on their behalf.
Back to the structured data above. As you can see the data is presented in a consistent format. All users will have a gender, first_name, etc. It will all be presented in a similar format. Therefore you can write code to iterate over that list of data and grab each value by its key, i.e. you can expect to get all first names by the key, “first_name” and so on. That’s the idea.
When you submit data, you also get a response, e.g. that what you posted was successful. For example, if you’re using the Twilio API to send SMS text messages you will get a response like this:
<DateCreated>Wed, 18 Aug 2010 20:01:40 +0000</DateCreated>
<DateUpdated>Wed, 18 Aug 2010 20:01:40 +0000</DateUpdated>
And as you can see the <status> node says it was successful, and your code can now continue as normal because it knows it executed its job of sending an SMS text message successfully. in the <Uri> node you receive an ID # for that SMS text message so you can refer to it later. You could store that in your database and request another API endpoint url and get back the contents of this text message, i.e. similar information to what you see above. Maybe you want to produce a history of all text messages sent through your app--so that’s why you would do that.
That’s a quick runthrough of what APIs are about. If you plan to post tweets to twitter and updates to Facebook with your App, you’re going to want to understand how APIs work even if you’re not going to be a coder. More specifically, you need to be able to read API documentation, e.g. like the one Facebook provides for their “graph API”:
If you can read the documentation you will know specifically what you can’t and can do, and can therefore better instruct your developers of what to develop. You’ll avoid sending them on a wild goose chase to code something Facebook won’t even allow you to do. I’ve seen so many failed companies spend ages thinking they can do something they can’t, and waste money forcing developers to figure it out on your dime.
To read API documentation you need to understand 3 things:
1) PARAMETERS - the data you provide to the URL endpoints, and what parameters are available and what types of values are accepted. These parameters basically configure what sort of output you should expect. They are the input, just like parameters to functions in PHP.
2) RESPONSE FORMATS - above you saw 2 types of response formats: JSON and XML. That’s basically all you’ll need to know. It’s how the response is formatted. If you can examine these tree structures, you can see what sort of data you can get out of the APIs you’re using.
3) POST vs GET - i’ve been referring to these URL endpoints as the only way to supply input parameters, but the reality is you can pass more parameters outside of the URL via “POST fields.” I won’t go into it at a deep level here, but I’ll give you the gotcha you need to know: basically you can attach more values and send them along with the URL you request. That’s it. So instead of having parameters at the end of the URL like this ?key=value&key2=value, you’ll send them in similar pairs but as POST fields. In PHP you’ll use a tool called cUrl to aid you in attaching these key/value pairs.
After you understand that, you’ll be able to read the documentation of very many APIs very quickly. They’re all quite similar. Study Facebook’s and Twitter’s until you get the hang of it.