How to Build an API

Let's build a basic, functional API.

An API that works. Software on a remote website asks for information. The software at the API website responds with the information.

It's usefulness is in showing how building an API is done.

To become familiar with what an API basically is, click this direct download link for a PDF describing what an API is and how API works.

It's essential to understand how an API works to get the most out of this tutorial. If you're unsure, grab that PDF.

The API (the Application Programming Interface) system in this tutorial has three parts:

1. The API Software. The API software authenticates requests. It's the gatekeeper. It relays requests to the responding software and sends the response back to the requesting software.

2. The Requesting Software. This software sends requests to the API. Requests can be initiated by, among other things, a web page user request or an automatically scheduled event. Along with the request is information that lets the API authenticate the request as being from an authorized source.

3. The Responding Software. This software receives the request relayed by the API and sends its response back to the API.

This tutorial's intent is to provide a simple framework for a deeper understanding and from which a more sophisticated API can be built.

In production implementations, the requesting software and the responding software might occasionally switch roles, depending on requirements. To keep things as simple as possible for this tutorial, the requesting and responding parts of the API system do not switch roles.

Various parts of an API system can be built with any programming language the computers they're deployed on can run. For this tutorial, all three parts are PHP scripts.

The Three PHP Scripts

For reference, here are the file names and example URLs of the three PHP scripts for the API system described in this tutorial.

1. The API Software.
   api-api.php
   http://example.com/api-api.php

2. The Requesting Software.
   api-request.php
   http://otherdomain.com/api-request.php
   (Assumed to be on a domain different than the API software, but it's not required to be on a different domain.)

3. The Responding Software.
   api-response.php
   http://example.com/api-response.php
   (On the same domain as the API software.)

The API Software

The API software operates in the middle as the communicator between the requesting software and the responding software.

Here's the source code. Notes follow.

<?php
$Credentials = 'abcXYZ'; // The access credentials.
if( empty($_GET['request']) or empty($_GET['credential']) ) { exit; }
include('./api-response.php');
$Response = ObtainResponse($_GET['request']);
echo $Response;
exit;
?>

The value of the $Credentials variable (colored blue) needs to be identical in both this software and in the requesting software. Otherwise, the request won't authenticate.

When authenticated, the request is passed to the responding software (the software location colored red).

Note: If the responding software is not installed in the same directory as the API software, then the responding software's location (specified in the example source code as ./api-response.php) needs to be adjusted to reflect its other location.

The Requesting Software

The requesting software contacts the API software and requests information.

Here's the source code. Notes follow.

<?php
$Credentials = 'abcXYZ'; // The access credentials.
$URLofAPI = 'http://example.com/api-api.php';
if( isset($_GET['request']) )
{
   echo file_get_contents("{$URLofAPI}?request={$_GET['request']}&credential={$Credentials}");
}
?>

The value of the $Credentials variable (colored blue) needs to be identical in both this software and in the API software. Otherwise, the request won't authenticate.

The value of the $URLofAPI variable is the URL of the API software colored red). It will need to be updated.

When a request is made to the API software, it includes which information is desired. For the example software, either of these two can be requested:

1. The current universal date and time.
2. A specific web page.

To request information, type the URL of the requesting software into your browser, followed by a "?" character, and that followed by your request.

To request the current universal date and time:

http://otherdomain.com/api-request.php?request=current_universal_time

To request a specific web page:

http://otherdomain.com/api-request.php?request=http://blogsjustin.com/

Change http://blogsjustin.com/ to the URL of the web page you want to see.

The api-request.php requesting software will send your request to the API software. The API software will relay the request to the responding software. When the API software receives a reply from the responding software, it relays the information to the api-request.php requesting software.

The Responding Software

The responding software is contacted by the API software with the request from the requesting software.

Here's the source code. Notes follow.

<?php
$CheckCredentials = 'abcXYZ'; // The access credentials.
date_default_timezone_set('UTC');
function ObtainResponse($request)
{
   global $Credentials, $CheckCredentials;
   if( $Credentials !== $CheckCredentials ) { return ''; }
   if( $request == 'current_universal_time' ) { return date('l, F j, Y \a\t G:i:s'); }
   if( preg_match('!^https?://!s',$request) ) { return file_get_contents($request); }
   return '';
}
?>

Note that the credentials are the same as the other two PHP scripts, but the variable name is different. That's to prevent just anyone else's API software from using your responding software.

The value of the $CheckCredentials variable (colored blue) needs to be identical to the value of the $Credentials variable in both requesting software and the API software. Otherwise, the responding software will return a blank value.

The responding software responds with either the universal date and time or the requested web page. (If something else is requested, the responding software will return a blank value.)

Putting It All Together

To install the customized PHP scripts, put the API software and the responding software on the same domain in the same directory.

Next, put the requesting software at any domain. It may be on another domain or the same domain as the API software.

Now you're ready to test. Modify these URLs to reflect the location of the requesting software, the first URL to obtain the universal date and time and the second URL to obtain a web page:

http://otherdomain.com/api-request.php?request=current_universal_time

http://otherdomain.com/api-request.php?request=http://blogsjustin.com/

(The http://blogsjustin.com/ URL can be changed to obtain a different web page.)

You now have a working API system.

To be sure, it's simple. That was the intent — a simple working framework to convey the functionality and from which a more sophisticated API system can be built.

(This article first appeared in Possibilities ezine.)

Will Bontrager