|
|
|
|
| Tutorial |
An API Design Example
In the midst of all this theory, let’s design an application program interface (API) from
the ground up to familiarize you with the conventions and concepts discussed earlier.
Please note that this is a practical approach, not a theoretical approach.We’ve chosen
to do it in a practical manner to let you memorize each step; in future projects, you’ll
have to design APIs on a mere theoretical basis, without having seen a line of code
first. For hints, tips, and tricks about the theoretical approach, see Chapter 3,
“Application Design: A Real-Life Example.”
The module for which we’ll be creating an API is meant to handle a simple scheduler.
The actual implementation of the scheduler functions isn’t of any importance;
remember that this is exactly what has to be obscured to the user.The user just wants
to manage a set of appointments, so the API has to present itself as just that, namely
providing an interface for appointment management. It’s not necessary to inform the
user of the underlying system, whether you’re using Julian or Gregorian dates or
maybe even your own format—at some point, you might want to provide an extra set
of such features to the user (for example, date format conversion), but it’s completely
unnecessary when all you need initially is simply to enable someone to manage
appointments.
On the other hand, this doesn’t mean preventing or even disabling a future implementation
of these features.The trick when designing an API is to meet your
requirements exactly, while being able to extend the API to any eventual needed
functionality.This requires in-depth planning and thoughtful definitions, as discussed
throughout this chapter.
The API has to present itself to the user as the only way of accessing the functionality
of the module it represents. No functionality can be missing, nor can any
unnecessary functionality be available—or even functionality that doesn’t belong
directly to this module.
The list of requirements for a simple scheduler may be as follows:
n Add an event.
n Delete an event.
n Retrieve a list of upcoming events.
Let’s define prototypes for the add and delete functions first, as shown in Listing 1.10.
What might these functions need as information and what could they provide as
return values?
|
|
|
|
|
|
| Link Partners: Asia florist, Flowers to India, Hong kong flowers, Site submit, Cheap web hosting, China florist, Japan florist |
|
