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.
January 2nd, 2006 at 2:41 pm
I’m currently working on an API for one of my Web Apps, and something I’m doing is developing a PHP interface to it. If I find the API too difficult to use, I change it.
January 2nd, 2006 at 8:34 pm
Some good ideas/tips. I think WordPress does a great job at this, in both usability and abstraction.
January 2nd, 2006 at 10:20 pm
Now the nightmares will start again…
…sadly a true story… my second day on the job.
January 2nd, 2006 at 11:25 pm
Congrats on making the 9Rules network!
January 3rd, 2006 at 1:11 am
January 3rd, 2006 at 1:29 am
Hey, (I guess you’re aware of this but here goes anyway =) ) your server-side parsing of comments seperates from the live preview as only the live preview replace newlines with <br />’s
Have a nice day!
January 3rd, 2006 at 7:02 am
January 3rd, 2006 at 11:12 pm
[...] rane, Eric Pascarello, and Darren James. For details check the entry at the bottom of this post. Look for similar articles under these categories: Contests Was [...]
January 4th, 2006 at 6:59 am
Nice thoughts. Although logic maybe says that an API should be built on top of an app, since I heard that Flickr is the biggest user of it’s own API, it made me wonder if creating the app out of the API could be interesting way to go.
My ode:
My colleagues were dumb,
and selling phones really sucked.
But I got lots of satisfaction
when I told them to get coffee.
January 4th, 2006 at 2:36 pm
Yes, if I were creating a web content management system, I would want to provide default settings when no input is provided and customization when the user requests it. Oh that’s right, I am creating a web content management system. Better keep this list handy! Good post.
January 5th, 2006 at 2:23 pm
January 6th, 2006 at 4:21 pm
I was thinking about submitting an ode to my first job, but there’s no way I could write anything better than Jim A. in #7. Especially since it was a job in fast food. Plus, I already own a copy of the book. Love the site!
January 7th, 2006 at 10:43 am
@Craig: Aww, thanks!
January 7th, 2006 at 4:28 pm
I don’t really think I was a prick, but what the heck, it rhymed.
January 9th, 2006 at 11:02 pm
[...] ;
Surface level tips for good API writing
Tips for writing API read more
[...]
January 13th, 2006 at 12:23 am
[...] g a lovely meal. 11) Surface level tips for Good API Writing Write an Ode to my first job Jim A http://www.auldridges.com Jim wrote a fancy little ode abou [...]
September 27th, 2006 at 2:44 am
Someone else below asked this already.
I am getting nailed with Spam in my guestbook for our catalog website. Is there anyway to stop this? If not, there really isn’t any point in leaving it up and active. Any help will be greatly appreciated.
Thanks