Introduction

Hello learner, and welcome back.

This is the last in our four-part series of explaining APIs using simple everyday words.

Previous lesson

In case you missed it, here are the three earlier sections in the series;

• Part 1 – we introduced the topic of APIs and the various components
• Part 2 – we looked at how the components work together
• Part 3 – we looked at the API methods and HTTP codes

Now that you are all caught up, let us continue today’s lesson.

Today’s lesson

Objective for today

In today’s lesson, we will want to

• write an API class file
• be able to generate responses

I will use PHP to illustrate this. Even though this is being illustrated with PHP, it can quite easily be written in many other programming languages. Finally, we will work with a hypothetical user list.

Writing your API class file

We will need to include functions that do the following:

• process the request
• get request method
• send response
• get a status code message

Generating a response

The Representation format of the information is usually JSON / XML. There are other formats like HTML, RSS, CSV, and JSON.

It is common to have the server response as an XML, however, it is preferable to use JSON. JSON is also much easier to interpret and more popularly used.

The two components of a ReST response are

• the body
• and the status code

Basic XML response

First, let’s look at a basic XML response

<?xml version='1.0'  encoding='UTF-8'?>
<myXML>
    <function>order</function>
    <values>
        <orderID>123</orderID>
        <reference>ref</reference>
    </values>
</myXML>

This is another example of a ReST response

<?xml version='1.0' encoding='UTF-8' ?>
<messages>
    <message>
        <date_created>Mon May 15 2013</date_created>
        <user>Eli</user>
        <text>Checking stuff out</text>
        </message>
        <message>
        <date_created>Wed June 12 2013</date_created>
        <user>Anthony</user>
        <text>Moving stuff in</text>
    </message>
</messages>

The code to produce this output should look something like this:

$sql = ‘select * from users’; // list info 

$q = mysql_query($sql);

Switch($format)
{
    Case ‘json’:
        Header(‘Content-Tye: application/json; charset=UTF-8’);
        If(count($q)){
        Echo json_encode(array(‘data’=>$q));
        }else{
        Echo json_encode(array(‘data’=>’Nothing found’));
        }
    Break;
    Case ‘xml’:
    $sCode = ‘’;
    If(count($q)){
        While($a=mysql_fetch_array($q)){
        $sCode = “ 
        <unit>
        <id>{$a[‘id’]}</id>
        <name>{$a[‘name’]}</name>
        </unit>
        ”;
        }
    }
    Header(‘Content-Type:text-xml; charset=UTF-8’);
    Echo “
    <?xml version=’1.0’  encoding=’UTF-8’ ?>
    <info>
    {$sCode}
    </info>
    ”;
}

This is a simple example of adding information to users

$aData = array(‘result’=>’Info added successfully’);
Switch($format){
    Case ‘json’:
    Header(‘Content-Type:application/json; charset=utf-8’);
    Echo json_encode($aData);
    Break;
    Case ‘xml’:
    Header(‘Content-Type:text/xml; charset=utf-8’);
    Echo “
    <?xml version=’1.0’  encoding=’utf-8’ ?>
    <res>
    {$aData[‘res’]}
    </res>
    ”;
    Break;
}

This is an example code showing how to display results

$sql = 'select * from users where id = $id ';
$q = mysql_query($sql);
if(mysql_num_row($q)>0){
$r = array();
while($a = mysql_fetch_array($q)){
$r[] = $a ; 
}
$this-> response($this->json($r),200);
}
$this->response('',204);

private function json($d){
if(is_array($d)){
return json_encode($d);
    }    
}

An XML parser can interpret XML responses. You can even let clients specify the ReST response with XML or JSON by doing something like users.xml or users.json.

Conclusion

Other issues

If PUT or DELETE requests do not work in your Apache setup, then put the following in the .htaccess file of your application web root folder. It would be written like so

<Limit GET POST PUT DELETE>
Order deny, allow
allow from all
</Limit>

Keep learning

Now, that is a wrap. That was not so bad? If you have any questions or if you would like me to go over specific areas of the series, then kindly let me know.

Please share your comments, and re-share the post to let us know how this explanation went with you.

As always, keep learning, and cheers.