The Design of Software (CLOSED)

A public forum for discussing the design of software, from the user interface to the code architecture. Now closed.

The "Design of Software" discussion group has been merged with the main Joel on Software discussion group.

The archives will remain online indefinitely.

Designing an API for your project

I'm a self-admitted beginner, in the realm of software design. I've programmed several trivial, but very helpful to me, utilities -- nothing worth public release. I do it as a hobby, because I'm fascinated with it. I've recently come up with an idea and I've set a very ambitious goal to have a working version within 5 years. I say ambitious because I really only have a year of programming as a hobbyist. Ok, enough with the back-story and on to the question. Without giving away too much of my idea, I'd like to build a community around the software, and freely offer tools and an API so that users can participate. I figure the only real way to do this, effectively, is to integrate them into the software design, before a single line of code is written. What are the techniques used when designing an API?
AverageMidget Send private email
Friday, August 03, 2007
Here's a good reading about communities:
* A Group Is Its Own Worst Enemy -

Also Paul Graham has advices of the sort of "don't make users have to register". Reddit used somewhat his advices and made the registration very painless without requiring email authentication I think. Also, Reddit doesn't make users keep logging all the time as long as the cookie is in place.

I don't know what you want to achieve, but as you see, sometimes the best way is to listen to the pros. :-)
Joao Pedrosa
Friday, August 03, 2007
Read on Guy Kawasaki's Truemors as well:
* By the Numbers: How I built a Web 2.0, User-Generated Content, Citizen Journalism, Long-Tail, Social Media Site for $12,107.09 -

The API is not user friendly. You probably want users who are not much into how computers work.
Joao Pedrosa
Friday, August 03, 2007
Your software idea is going to be completely out of date in five years.  Can you release something in five months, even if it is extremely basic?

It's not necessary or even necessarily desired to release a "perfect" product as v1.  Let something out into the wild that has basic functionality, see if anyone even likes it, then improve it as time goes on.

If you spend the next five years developing something, wow ... that's a very painful and protracted way to commit suicide.
Karl Perry Send private email
Saturday, August 04, 2007
Read this one as well, by the creator of Gmail:
* The first thing that you need to understand about humans -
Joao Pedrosa
Saturday, August 04, 2007
One more interesting little text to read, this time it's about APIs:
* API grows like fungus! -
Joao Pedrosa
Saturday, August 04, 2007
First, at your skill level, I would not expect to ever finish this project. That said, I don't want to discourage you in the least: tackling a project like this will teach you all sorts of valuable stuff. As an amateur programmer, the things you learn from such projects are far more important than the projects themselves.

As for designing APIs, my approach is to start at the oposite end: dummy up a few example clients for your proposed API and see what you will need from the API in the client code. These are very rough estimates of what real clients will look like, not ever meant to be working programs (though you may, eventually, package them up as example programs once the API is written and working), only to focus your thinking when designing the API and the underlying runtime. Don't try to throw in every feature that you can think of, just put in the features that are necessary to implement the sample clients. You can always expand the API later to include the nice-to-have features that aren't strictly required.

An extension of this approach is the advice from "The Mythical Man-Month" by Fred Brooks: plan to throw one away. Even after you've extracted your APIs requirements from the sample clients, you will find that, once you have started coding the API, there are still things that you either overlooked or never realized. You will need to revamp the API at least once during implementation in order to work around stuff you simply got wrong. Even if you have released the API early, you should not be afraid to scrap and redesign major portions that are clearly mis-designed. Be prepared to make several such radical changes during pre-1.0 implementation.

Finally, try not to get distracted by gee-whiz facets of your implementation language: keep the API simple and make it look like other libraries in the language. The gain from unusual contortions of a language (even when legal and portable) are completely offset by the harm done to program readability and the alienation of new programmers using the system. As an example, an API that I designed a few years ago makes heavy use of tagged variable argument lists in C (as in foo(x, INT, i, FLOAT, f, STRING, s, NULL) which calls the function foo(X,...) with one explicit argument x or type X, and three variable arguments i, f and s of types INT, FLOAT and STRING). This seemed Really Cool [TM] when I thought of it, but it's really just a source of hard-to-debug runtime errors that should be caught at compile time, but aren't. Another example, in my opinion, is the C++ streams system (as in: cout << "Hello World\n";) which overloads perfectly readable logical/arithmetic operators (<< shift left and >> shift right) for entirely unrelated purposes. Nowhere else in the C++ libraries do we find such a gross abuse of operator overloading, and there's a good reason for that: it's not helpfull and just makes programs harder to read.

Take a leason from these two examples: don't be a showboater, make your API look familiar to the normal practitioner, make it easy to understand. You users will thank you later.
Jeffrey Dutky Send private email
Saturday, August 04, 2007
First of all I agree that if you are going to take 5 years the chance of you succeeding is very, very small.

For instance, dating sites are taking a big hit right now, because of the rise of social networks like Facebook and Myspace. This is not something that anyone could have foreseen. Friendster which was one of the first social network is not as successful as Facebook or Myspace.

But regardless in terms of API design, I've been looking into this for a few months and here are a few resources:

1) Interface driven design (Pragmatic Programmers) - This book will teach you about how to design an interface, which is basically what an API is. Even though the title might not seem like it, it basically covers a lot about API design.

2) Framework Design Guidelines (Microsoft .NET development series) - This book might be good for advanced and complex API design.
Praveen Angyan Send private email
Saturday, August 04, 2007
"I figure the only real way to do this, effectively, is to integrate them into the software design, before a single line of code is written."

Not necessarily.

It *IS* possible to retrofit these things. And it's probably sensible in your case. Really.

Go build your site and see if you get initial users. At the point you need an API building you'll a) have a better idea of how to architect the site and b) have either cashflow or demonstrable interest to raise VC with to hire some people who can do that without sweating over it.

What usually happens is that you'll discover attempts 1 and 2 (and sometimes 3) of site architecture won't work anyway. So by the time you need to do #3 (or #4) you'll be rewriting tons of stuff anyway.

For example; we have a website which manages the main product. We need to basically rewrite the entire thing over the next six months because of scalability problems with the framework that was picked a couple of years ago. While we're doing it, we're exposing a lot of the functionality for customers to use through XMLRPC. On the other hand, we now have more people to do this with than the first draft used.
Katie Lucas
Saturday, August 04, 2007
Obviously I don't know anything about your idea or preferred implementation choice, but Ruby on Rails makes it trivial to add an API to a web application by extending the existing controllers:
John Topley Send private email
Saturday, August 04, 2007
I left it vague to get a broad range of ideas, but I should probably clarify something. I'm not planning on doing a social networking site. When I said "I'd like to build a community around the software" I meant that I want the people using my software to easily make content to be used inside my software. Kind of like how some community-created tools let you put custom content inside video games. I plan on programming it in c++ and initially on Windows. Ideally I learn enough, before I start, to write portable code so that it can easily be compiled on other platforms.

I could be wrong, but I don't think my idea will be out-of-date in five years, being that it's not a social networking site. And the reason I give myself five years is because I want to continue to learn all I can before I start writing it. I only do this as a hobby and can only devote a few hours a day to learning.

Thanks everyone.
AverageMidget Send private email
Saturday, August 04, 2007
planning is for the highly experienced.  Once I removed most planning from my development process I have become a far better programmer.
Tom C
Saturday, August 04, 2007
If you're going to expose an API for your app/system/whateveritis, the best way to ensure that you've got a good API is to use it yourself in the implementation of the project.

If it sucks for you to use, you know nobody else will use it either.
Chris Tavares Send private email
Saturday, August 04, 2007
I can only agree that 5 years is much too long. You ought to have something going in 6 months, with the aim of continuously improving from there on in.

The rule of thumb for API's

a) Adding things to an API is much easier than taking something out. Why? Adding a function call doesn't break other people's code. Taking one out will always break things, and you will get the blame.

b) Use your own API before you ship. Try to implement part of your product using your own API. You can then fix things before they are released, rather than releasing them and then realising that it's wrong and you'll now have to support it all the same. That will also help you document it, and give you some example code to release.

c) Version your API. Allow software to choose which API version it wishes to use. This will at least allow you to confine your interface mistakes to given API versions, and provide a defined way in which users of the flawed API can stay working whilst new software moves on to better things.

d) Talk to users a lot, and offer really high quality support to those with genuine issues.

e) Going from hobbyist to API programmer is a big leap. The main things you must must have are
- Really good unit tests. You don't want to support a poorly tested API in the field, believe me.
- Proper version control (eg Subversion).
- A backup policy that will survive the destruction of your building and its entire contents.
Duncan Sharpe
Sunday, August 05, 2007
In a nutshell, the API must add the greatest possible value to its customers, for the least cost.

The GNU Compiler Collection is a great API. The gcc can do anything you want it to, but that power and flexibility is tied to an incredibly heavyweight API (i.e. you must write the program).

My personal opinion: an API should be as lean and mean as you can possibly make it. If the user has to read a page or fifty of documentation to understand the API (think XML), they will feel they were better off rolling their own.

You may be tempted to use a "richer" API to deal with s
"special cases" (ignore_first_line_flag), or "optimize" things (list_is_already_sorted_flag), but it will only cause trouble. The UNIX way "do one thing, and do it well".  Extreme programmers suggest refactoring special cases into the API if the case crops up 3 times, but that number goes waaay up if someone else may use the code.

Also, the more complex your data is, the more pain you will have when you try to operate with other code. The more I code, the more I find myself trying to code unambiguous functions that accept a simple lists or strings, even if they are a little slower or solve less problems. Complexity if for the object, not the API.

As for your project, try to extract the absolute minimal set of components that could possible be of any use. One week later, cut out half of them and work on what is left. You will probably find that the grand plan changes direction, or you find a better opportunity, or somebody looks at your quick and dirty solution (once it is up and running) and realizes that you can do everything you want with 3 simple changes. And unit test, use source control, consult users / developers, and all that jazz.

Best of luck.
Monday, August 06, 2007
Joshua Bloch (designed the Collections API for Java) gave this amazing talk at Google -
Dave Send private email
Tuesday, August 07, 2007

This topic is archived. No further replies will be accepted.

Other recent topics Other recent topics
Powered by FogBugz