Keys to an excellent web-app: API
During the development on phpVMS, I found I was splitting my time as 95% programming new features, and 5% debugging. I attribute this to something, which is often over-looked when creating a web-application, an API – "Application Programming Interface". When you hear the word(s), you probably are thinking more towards actual applications, something running on your desktop, or maybe in Windows or Linux. But an API serves well in web applications also. While frameworks, like my own Codon, or Symfony, Zend, etc all have APIs, it serves well to plan and write out your own API for your application.
To start, what’s an API? It’s a common interface to do things. For example, database operations, an API serves well to managing all your queries from a central place. But what’s the point? Look at my new code to bugs ratio. An API speeds up development time, allowing you to concentrate on logic, rather than fumbling with getting the basics working. Frameworks serve the same purpose, but a framework is only as good as the API backing it.
Designing your data model
I first designed my database for phpVMS. I knew I needed a table to contain all of the pilot reports, “pireps” for short. So there are a few steps to designing a good API:
- Adding a PIREP
- Removing a PIREP
- Editing a PIREP
- Changing the status of a PIREP
- Retrieving PIREPs
- Retrieve PIREPs on a certain date
- Retrieve PIREPs for a certain pilot
- etc
Instead of writing them in-line, while I’m writing the front-end code, I like to work backwards, starting with the database functions I would need., working my way to the controller, than then finally the HTML template. This works well combined with a feature of PHP 5 – static classes.
[php]
class PIREPData
{
public static function GetAllPIREPS()
{
$sql = "…";
return db_results($sql);
}
}
[/php]
Now with the above code, in any piece of code, I can do:
[php]
$allpireps = PIREPData::GetAllPIREPS();
foreach($allpireps as $pirep)
{
echo …
}
[/php]
And have all of my PIREPS, and I can cleanly display it. If I need to do it anywhere else, I don’t need to copy/paste SQL code, which I may have to debug or change later on.
Being Consistent
This is the next step to designing a good API. Consistency means:
- Keep return data uniform
- Keep variable names consistent
- Make sure you use it!
Returning uniform datasets:
This seems a little odd, but I’ve seen code where one API function will return HTML, another will return just a dataset. I keep as a rule to only return datasets, and then decide what I want to do with that dataset. For instance, I keep track of “flights” through an interface. I use the same API call to build an HTML table, and also the same API call to then build an XML result-set from that data to use elsewhere.
Keep variable names consistent
This one bugs me when I see it. For instance, I use the variable name $pilotid. I only use $pilotid. Not $p_id, $pid, $pilot_id, or the worst I’ve seen, $p (wth is $p??).
Make sure you use it!
I’ve often seen a good API, but no one bothers using it, instead re-writing the code to either it’s in the format that they (and only they!) want, even though the API function can easily be processed to provide the functionality, or just plain-out re-writing code. Always drill it into your head and programming to look before you code! Spending 15 minutes to analyze an existing data model can save a lot of time and head-ache in the long run.
