I have heard of many web APIs like that of Facebook, Twitter, etc., which helps third party access data and manipulate it. I would like to know how a web API works. What are the basics of a web API?

If I want to create an API for my site, so that people can access or update it, what will I need to start with?

  • 1
    Not that it's crucially important, but which language is your site built with? – ocodo Jan 12 '11 at 11:02
  • Have you read the documentation for the facebook web API yet? developers.facebook.com/docs If you haven't read it, why not? If you have read it, what specific questions do you have? – S.Lott Jan 12 '11 at 13:15
  • ok sure i will do @S.Lott ! – Harish Kurup Jan 12 '11 at 13:17

At its simplest, you create a set of GET/POST requests that anyone can call and publish the information on the URLs, parameters and effects. GET requests for read-only tasks and POST requests for anything that will change data on the server.

Add in a authentication system if needed and you have yourself a simple Web API.

A Web API is just an Interface to allow access to your system (such as site) via standard HTTP request methods. The data itself is usually wrapped in some standard format (such as JSON or XML) to make it easy to handle.

Here is an example Web API for 'TextWise'

  • ok. which format of dat will be the best to use JSON or XML?? – Harish Kurup Jan 12 '11 at 10:34
  • 1
    JSON - XML is very hard to manipulate and doesn't provide any advantage over JSON. And in XML you have large overhead because you have to have closing tags. – Slawek Jan 12 '11 at 10:42
  • 1
    @Harish. Once again, it is one of those 'entirely depends on your purpose/situation'. Whereas I may prefer the JSON format, if I did it for one of our systems at work, I would use XML since it has inbuilt XML parsing abilities, but not JSON. This means code maintenance is easier and the other developers will be familiar with the commands. – Dan McGrath Jan 12 '11 at 10:46
  • 1
    @Harish, it's a good idea to favor one, and release it first, but to provide both XML and JSON will help your users. – ocodo Jan 12 '11 at 11:01
  • In practice XML and JSON gzip to similar file sizes. I'm seeing a gradual tendency to shift towards JSON (JSON is newer than XML), though it's currently very common to offer both. JSON is ideal for exchanging data whereas XML is ideal for exchanging documents. – Brian Sep 24 '13 at 18:11

I'm actually developing an API for my company's virtualization platform now. You can go about them in a few different ways, but my favorite (and the fastest route to getting something working that people can understand) is using simple HTTP GET requests and returning a JSON response.

My URL's look something like this:


I then break down the HTTP GET variables, and do what the caller wants done with them. One of the biggest reasons that I signed up as a beta user to the Stack Exchange API development was that I knew that it would be a tremendous learning experience, and indeed it was.

Usually, I return two JSON encoded arrays, one being result, which basically just says if the call was successful and gives an error code / error string if not. The other is usually just called data, and the contents of that are described in the documentation of that particular call. Additionally, GET based API's are far easier to test and debug.

Lots of other formats exist, such as SOAP / XMLRPC, I just find that chosing JSON gives me incredible simplicity and freedom of choice.

For instance, if I need to send a lot of fields and don't want to deal with a ton of GET variables, I can just do this (example in PHP)

$to_send = base64_encode(json_encode($some_array));

That is easily decoded on the other side, giving me dozens of variables to work with, while still only accepting 2 - 3 GET variables via the API.

I just try to keep my methods and calls short and succinct, and design it in such a way where each call returns a uniform 'worked or failed' response, followed by the data requested.


That's actually a very broad question. In the most basic sense, a web API works when a client (like a Web browser) makes an HTTP request of some kind to a Web server. The server examines that request to figure out what the user wants, and then returns data in some format (like a page) that the client then examines to get what it wants. These are just about the only things that Web APIs have in common; I realize that this doesn't really answer your question, but I wanted to give a reason why the question is so broad.

There are all sorts of ways that a client could format its request, or that a server could format its response, and so in order for any of it to make sense, the client and server have to agree on some basic rules. Generally speaking, nowadays there are two very general styles that get used for this sort of thing.

Remote Procedure Call (RPC)

In an RPC style API, there's usually just one URL for the whole API. You call it by POSTing a document of some kind which contains information about what you want to do, and the server returns the document that has what you want. In general computing terms, the request document typically has a function name and some arguments.

Some standards for this style of API include XML-RPC and SOAP. These standards attempt to create a format that can be used to describe the function calls you're making, or even to describe the whole API.

REpresentational State Transfer (REST)

In a REST style API, you don't so much have a URL for the API as a name space: a server, or a folder inside of a server, where a lot of different objects reside, and every URL within this namespace becomes part of the API. Rather than telling the server that you want to use the API, the URL tells the server what you want to use the API on. You then use the HTTP method, and possibly the request body, to explain what you want to do to that object: GET (retrieve something that's already there), POST (create something new), PUT (replace something that's already there), or DELETE (get rid of something that's already there). There are a few other verbs you can use, but those are by far the most common.

So far, I haven't mentioned standard formats for REST. In theory, you could use just about any format. HTTP already provides for saying what you want to do and what you want to do it to, so the format of the request body could be just about anything: some representation of the object you want to create or replace. But in practice, REST authors tend to agree on a format anyway, because it would be difficult to make sense of every possible format.

Not the answer you're looking for? Browse other questions tagged or ask your own question.