i am dustin diaz

Surface level tips for good API writing

There are times when venturing into a new project where a developer is faced with the task of needing to write an API to either future proof the project, aid the development process, or develop for an entire group of developers. Believe me. This is no easy task. However this pain-staking process doesn't need to be as hard as one thinks.

Let's pretend...

We're developing an API for a blogging system. So for humor sake, instead of WordPress, we'll call it "LetterStamp". We want to give the author/developer some tools to put together their new blog with ease.

Think Dumb

Imagine yourself using 'the very' API that you're developing. Is it developer friendly? Does it give you the control you need? Or does the API need tweeking just to do what you're trying to do? Consider some functions you wouldn't mind having. Are they over-complicated? Under-complicated?

Abstraction

Have you ever thought to yourself Hey, it would be nice if I could plug in my own variables here.... Abstraction is key. Decoupling presentation from perhaps logic. Avoid 'set in stone' variables and conditions. For instance, let's say we had a function that gave us the last five articles from our article database table. Wouldn't it better if it was the last n%? We could then allow the developer to plug in their own number.

You shouldn't have to know how it works

You only need to know what you can do with it. For example, I don't want to know that my processor communicates with my hard drive which then goes through a buss...or...whatever (I better stop before I really sound like I don't know what I'm talking about). All I want to do is hit the power button, click an icon, and be surfing the web in seconds. Applying this theory to our new LetterStamp blogging system - as developers using the API, we don't need to know that in the background there's a persistant database connection, a private call to some cleaning functions that prepare our content for ouput, or that query that gathers all our categories together. That stuff should be considered off-limits. If you've found yourself playing around on the API side of things, then that is almost a sure sign that the API is flawed. If this were a tangible item - and you paid for it, I would most certainly take it back for a refund.

So what did we learn?

If anything, it's something to consider when making an API. When I sit down to write a class or two, I consider the impact and usability. Am I going to be helping the developer? In practicality, you would want to make it as best as possible so you won't be bothered so much in the future about it.

Work Backwards

I can guarentee it will help. In retrospect, the API is not developed first, but my pretend application. I like to imagine that it's already built and I'm calling pretend functions that do exactly what I want them to do. When that part is finished, I can then begin working on my API development.

Todays question and book information

The winner of today’s contest will receive a copy of Ajax in Action by Dave Crane, Eric Pascarello, and Darren James. Put together an "Ode to my first job" in exactly four lines. (Yours, not mine)

Please remember to put your answers encapsulated within a <blockquote> element, and the regular discussion as normal.