Coding for Coders – Good API Design
Posted by Chris Alcock on Tuesday 16th January 2007 at 11:37 pm | Tagged as: .NET, Design, Development
As a developer I am most happy writing code for other developers to write code with. I attribute this in part to the fact that I don’t enjoy writing user interface code as much as writing the code that no-one sees. For me, my favourite user interface is an API or even a web service.
One of my favourite books about APIs is Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries by Brad Abrams and Krzysztof Cwalina. I’ve been reading Brad’s Blog for quite some time and today he posted a link to a really good presentation by Joshua Bloch about designing good APIs. The presentation is video with the full slide deck, and covers a range of topics from the initial specification of an API, through implementation considerations with some specific references to good and bad APIs. I found the parts about specification of an API and avoiding implementation details leaking into the published API and controlling the interface of the API.
Things I took away from watching the presentation:
- Consult people about the specification – get as much input as possible before committing to a design
- Keep the interface simple – over complication makes using the API confusing – Usability is important for APIs, stick to naming conventions already in use for your platform
- Control what you expose – don’t let internal implementation escape through your API, control the exceptions and types you expose
- Documentation is important – make sure all public parts of the API are documented, the level of reuse of your API will be defined by the how good the documentation is
- Consider performance of your API – make sure its not going to cause any horrid performance characteristics
- Subclass only when the type is really a sub class of the parent type (Liskov Substitution Principle)
- Don’t make the client do work if the module can do it for you – avoid the need for boiler plate code to use your API
- Report errors as early as possible – compile time is best, runtime is worst
- Be careful about your parameters – use the most appropriate types, keep the number of parameters under control, make sure overloads are obvious
- When throwing exceptions give as much information about why the error occurred as possible
The list above is not exhaustative, I highly recommend watching the full presentation – its well worth the 68 minutes it will take.
[…] Posted by Chris on 17 Jan 2007 at 11:29 pm | Tagged as: Uncategorized, .NET, IIS, SysAdmin, COM Interop In the presentation about Good API Design I talked about in yesterdays post one of the key points made was that once an API is defined you should never make changes to it that will break your client’s code. An example cited throwing exceptions based on values previously considered fine. […]
[…] Coding for Coders – Good API Design […]
[…] Coding for Coders – Good API Design […]