The power of twitter, facebook, foursquare and many more web platforms stems from allowing access to their functionality and data through APIs

APIs are they’re backbone, but they’re also what makes them open and accessible. APIs allow you to access the information and actions underlying the service.

The people who build software for the web - like Foursquare and Twitter - know that a huge amount of value in the modern web isn’t just in the interfaces we provide the main users to interact with their product or service; it’s about how other products and services can plug into it and interact with it. They open up the features of the product so other developers can build other platforms on top of it or with it.

• Facebook Apps are a great example of this. Facebook has allowed developers to create all sorts of new applciations that extend the facebook experience.

• Twitter’s success is in part due to the openness of the platform from the beginning. This allowed a lot of developers to build their own custom clients and tools for Twitter like TweetDeck, HooteSuite(https://hootsuite.com), Buffer (https://buffer.com) and FutureTweets (http://futuretweets.com). It allowed Twitter to focus on the platform and then other developers could build cool add-ons and extra features that they didn’t need to support (like tweet scheduling).

What’s an API

Formally, API is an acroynm for ‘application programming interface’. Basically, it’s the way software talks to other software on the web.

To make an analogy, think of the API as the front-desk at a hotel. They manage your requests when there’s something you want to know or do. You’re in your room, you’re hungry and you pick up the phone. You make an order for room service (a request) through them. You want a wakeup call, you ask them for it. But there’s limits - they probably won’t read you a bedtime story. An API is much like this middleman. They have a set of services and provide a structured way for you to access these services through a request, this request results in a reponse - which could be the delivery of a thing, information or some other kind of outcome.

Now with that in mind and to get a little more detailed, Kevin Stanton, API Chapter Manager at Sprout Social: “API is a precise specification written by providers of a service that programmers must follow when using that service,” he says. “It describes what functionality is available, how it must be used and what formats it will accept as input or return as output. In recent years, the term API colloquially is used to describe both the specification and service itself, e.g., the Facebook Graph API.” via

It consists of a few things: a REQUEST and a RESPONSE. Both are structured and often really well documented by the platform that makes them available.

When we work with API’s on the web, almost all are RESTful or REST-based APIs. REST means Representational State Transfer and while there’s a lot we could cover on the underlying technology and operation of REST, the main thing to know is that it’s how APIs on the web work and communicate between client (your web browser, your phone, your software) and server (the web application you want to access).

Simply put, APIs are hosted on web servers.

REST is a style for designing networked applications. HTTP is how we send messages on the web - you’ll probably have noticed it in your browser’s toolbar. In HTTP, there are two different roles: server and client. In general, the client always initiates the conversation; the server replies. It makes HTTP requests to post data (create and/or update), read data (e.g., make queries), and delete data. Notice these things. These are our major actions: Create/Read/Update/Delete (CRUD). These are the basic things we might want to do to any piece of information we encounter. We want to make a new one, we want to look it up or read it, we want to delete it or we want to change it (update.)

Now let’s take a look at an API specification. Let’s start by looking at Twitter

Making Requests

Our API requests consist of a few things.

1. The method we want to access. This is normally a URL (or web address) e.g. https://api.twitter.com/1.1/statuses/user_timeline.json

2. The request will have a type which relates to the kind of action we want to perform. These can be GET, POST, PUT or DELETE - these map to our CRUD actions too.

   • DELETE /clients/anne - would delete anne from the service
   • GET /clients/anne - would get you information on Anne
   • PUT /clients/anne - create/update/edit information about Anne
   • POST is normally used for other custom actions or things that fall outside of REST/CRUD

The good news is that the documentation will always tell you what kind of request you want.

1. Parameters. When you’re creating an new piece of information or if you want to search for something specific you’ll need to pass that information. You do this by adding parameters to the request. If you’ve ever searched fro something on the web you’ll probably have noticed a long string of extra information after the URL. This is a querystring - and it provides parameters to a HTTP service. You’ll see them a lot in google searches e.g. https://www.google.com/?q=querystring. This has a parameter named ‘q’ and the piece of information given to it is ‘querystring’. Now google will search for stuff relating to ‘querystring’ based on the information we’ve passed.

The documentation will also tell you what parameters you can pass.

Handling Responses

APIs work much the same way, except instead of your web browser asking for a webpage, your program asks for data. This data is usually returned in JSON format (sometimes it’s returned in XML!).

JSON - The body and format of the response

JSON or JavaScript Object Notation is a syntax for storing and exchanging data. And it looks like this:

{
    "id": 1,
    "name": "A green door",
    "price": 12.50,
    "tags": ["home", "green"]
}

Here’s an example of XML and JSON side by side

{"employees":[
    {"firstName":"John", "lastName":"Doe"},
    {"firstName":"Anna", "lastName":"Smith"},
    {"firstName":"Peter", "lastName":"Jones"}
]}

<employees>
    <employee>
        <firstName>John</firstName> <lastName>Doe</lastName>
    </employee>
    <employee>
        <firstName>Anna</firstName> <lastName>Smith</lastName>
    </employee>
    <employee>
        <firstName>Peter</firstName> <lastName>Jones</lastName>
    </employee>
</employees>

To find out more about working with JSON in Ruby read this awesome guide

Status codes

Request’s also have a status code. They’re returned with every request that is made to a web server. Status codes tells us what happened with a request. These include:

• 200 – everything went okay, and the result has been returned (if any)
• 301 – the server is redirecting you to a different endpoint. This can happen when a company switches domain names, or an endpoint name is changed.
• 401 – the server thinks you’re not authenticated. This happens when you don’t send the right credentials to access an API (we’ll talk about authentication in a later post).
• 400 – the server thinks you made a bad request. This can happen when you don’t send along the right data, among other things.
• 403 – the resource you’re trying to access is forbidden – you don’t have the right permissions to see it.
• 404 – the resource you tried to access wasn’t found on the server.

HTTP response codes standardize a way of informing the client about the result of its request.

Exploring APIs

Take a look at Twitters for example: https://dev.twitter.com/rest/tools/console

Read more

• The Nutshell: A beginners’ guide to APIs - http://www.theguardian.com/media/pda/2007/dec/14/thenutshellabeginnersguide
• What is an API - http://sproutsocial.com/insights/what-is-an-api/
• REST API concepts and examples - https://www.youtube.com/watch?v=7YcW25PHnAA
• Tools for Entrepreneurs: Introduction to APIs - https://www.youtube.com/watch?v=FknvOGcLHmc
• Learn REST: A RESTful Tutorial - http://www.restapitutorial.com and What Is REST?
• http://www.restapitutorial.com/lessons/whatisrest.html