Best practices and guidelines for designing an API

Question

What are some guidelines and best practices that I can adhere to while designing an API? At the bare minimum, I know that an API should be easy to use and flexible. Unfortunately those terms can be rather subjective, so I was looking for some concrete guidelines relating to good API design.

Answer 1

There is a good presentation about this topic from Joshua Bloch. The presentation uses Java but the ideas are language independent. Another source (pdf) for a quick overview.

Answer 2

I think your question will not get answered in this amount of space with the amount of information you are giving. I have put several links from typing 'api design' in google, and on the first page get these that look pretty good

http://lcsd05.cs.tamu.edu/slides/keynote.pdf

http://www.artima.com/weblogs/viewpost.jsp?thread=142428

http://chaos.troll.no/~shausman/api-design/api-design.pdf

Answer 3

I found the following to be worth a watch Joshua Bloch - How To Design A Good API and Why it Matters

The examples are in Java though but still you can draw parallels. Since you didn't mention a specific technology ; I assume you don't want niche solutions.

Answer 4

This is a link from Microsoft: http://msdn.microsoft.com/en-us/library/ms229042.aspx

There is also this book: Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries

Answer 5

As someone who has to consume tons of APIs...

Please write your API in a consistent manner:

1) Consistent naming within the API itself. Use verbs, nouns, keywords in EXACTLY the same style.

2) Consistent with the target environment it will be used in. If .NET, then consult Microsoft's naming guidelines.

3) Consistent concepts. Factory pattern? Builder pattern? Static methods? Interfaces? Just pick one, and stick with it. REALLY. There is no such thing as a small exception to the rule. It will stick out as a big sore thumb. More than 1 exception? Your API is more and more amateur.

Here's another one: Specificity.

1) Base classes that I can implement, if you choose to provide them, should have few and well-defined functions to implement. Don't tell me "GetData()" returns a "object[]" and then expect me to implement it, figure out why I have to cast it to a string[], and then debug why it is being called 20 times.

It is much better to have DataPoint[] GetChartData(), string[] GetLabelData(), etc. and let me choose which ones I should implement.

2) Please don't get silly-long with names: PostRenderColorWheelModifyHSVBaseHandler. YOu can often refactor super-specific things into a more generic name + parameters.

3) String parameters are a no-no! Use enumerations. I don't want to use a Handler like

PostRenderHandler("ColorWheel", "HSV", someDelegate);

I'd much rather like an enum I can investigate:

PostRenderHandler(ModuleType.ColorWheel, Options.ColorWheelHSV, someDelegate);

Man, I could go on... Power to that Josh Bloch guy - well-written APIs can be really awesome... bad ones can be really painful.