Forgive me if I start a little basic here, I’ll get directly to your query soon.
The use for an API is to expose functionality without giving any sort of real access to your server. This allows third parties to do things while allowing you complete control over it. So to start developing an API you first need to figure out what functionality to expose. For the purposes of example let’s look at this form the perspective of someone who needs to build an API. The reseller, RecordInformant™ (completely made up), has a bunch of server that can search terabytes of information using a proprietary method they spent nearly a million dollars developing. Now we don’t care what our clients sell this for or how do they any of that, they get to query us unlimited times per term for $50,000 a year. This business model presents an issue because it is unreasonable to give 5tb of information to each client with 10gb of data updates each day and expect them to have the server capabilities for this, furthermore you want to keep your search methods a secret. The solution to this is an API. We control all the servers and there is one copy of the data in our datacenter.
RecordInformant has a number of secret search features in PHP, two being searchAddressesForName($name) which can search though billions of address records in seconds and the second is searchFormerNames($name) which does about the same thing. To expose it they might use some code like the following (this is 100% untested PHP):
PHP Code:
<?php
include("../core/reallyImportantStuff.php");
//Check the cridentials
if(loginCheck($_REQUEST["user"],$_REQUEST["pass"])==true)
{
//A real script would use better methods to create XML but I don't want to look up the docs for how to do it.
$output = '<?xml version="1.0"?>';
if($_REQUEST["method"]=="getAddressesForName")
{
$output .= "<response method='getAddressForName'>";
$addrs=getAddressesForName($_REQUEST["name"]);
foreach($addrs as $addr)
{
$output .= "<record><year>$year</year><fullAddress>$fullAddr</fulladdress></record>";
}
$output .= "</response>";
}
elseif($_REQUEST["method"]=="searchFormerNames")
{
$output .= "<response method='searchFormerNames'>";
$addrs=searchFormerNames($_REQUEST["name"]);
foreach($addrs as $addr)
{
$output .= "<record><year>$year</year><fullName>$fullName</fullName></record>";
}
$output .= "</response>";
}
}
else
{
echo "No Acccess";
}
This API takes POST/GET requests and sends back an XML response. So a reseller would query the URL (
https://api.recordinformant.com/api....Name&name=John Doe) and get the response:
HTML Code:
<?xml version="1.0"?>
<response method='getAddressForName'>
<record><year>1989</year><fullAddress>132 W. 54th Ave, New York, NY</fulladdress></record>
<record><year>1992</year><fullAddress>3524 E Grant St, Queens, NY</fulladdress></record>
<record><year>2002</year><fullAddress>4522 N Maple Ave, Portland, ME</fulladdress></record>
</response>
Which he can display to the client and maybe do some more things like integrate the addressed with Google maps.
APIs can get far more complicated than this, the one I work with the most (Ubersmith) has many functions that can do anything from create hosting accounts to generate invoices. It’s closed source so that is the way they chose to allow their clients to get custom stuff done. Different APIs also differ in their approach to this, some use GET/POST in and XML out, some use XML in and out, some use REST, SOAP or JSON both way. Furthermore it doesn't have to be in one file, instead of passing a method parameter some have a different file for each one (although almost all of them give a method in the response). Others that use a structured input such as XML can even support many queries at once, giving a structured response back.