Top Ten ways to create a great API

I explained API’s in an earlier post, now, as someone who works with several APIs it’s time to put down my top ten features every API needs. If you’re working on a web 2 application and you haven’t thought about your API yet, then this is for you.

If you still need an analogy think of a railway station designer – you are making platforms for the trains to use. Everyone uses common elements to make it work – railway time, signals, timetable boards, track guage, platform numbers and so on. These are the building blocks of a good API – common standards and terms.

So, my top ten, in reverse order:

10. Provide good libraries and example code – it’s obvious but so often missed. You can’t just write your API and stop there – do the developer’s work for them and provide a class library and example app. Nothing gets us coding and using your API faster.

9. Fast Perfromance – no-one likes a slow coach, this is as true for platforms as for applications. If our application is fast we don’t want your platform to slow us down.

8. Use jargon – Jargon exists for a reason – to make sure we are all talking about the same thing. I’d rather learn new jargon FQL, FBML (et al.) than have to continually deal with long winded explanations of how the new technology differs from an old one.

7. Use jargon consistently – if a view is a list in your world keep using the word view for a list, don’t suddenly flick and use the word view for a viewing window. One word = one job.

6. Reduce the features- keep it simple, just have one way to do things. The more options there are to an API the harder it is to learn.

5. Version your platform – I know this is a contentious subject but versions really do help – even if you take the Microsoft approach of 16 digit version numbers. If you’re doing nightly builds then make this visible – there’s nothing more frustrating than seeing your app work one day and fail the next and you don’t know whether it’s your own slack code or that the platform has moved underneath you.

4. Add a Sandbox – Paypal’s developer Sandbox is absolutely wonderful, Facebook have some API and FQL tools that work. Give us ways to test our apps properly.

3. Support a developer forum – we learn best from others who have been there. Most API issues I solve by seeing how others who hit the same stumbling block did it – don’t forget to add a really good search engine.

2. Be a responsive tech team – if you put up a post on the forum or a bug in the tracker – you want a response asap. By the time a software project has got to the actual developers every day counts, this is the coal face and time waiting for the API team to get back is a real bind. Sometimes you can’t progress your code without their response.

1. Believe in Up-to-date documentation – if your documentation falls behind your API forget it, the worst phrase I see from API developers is “implemented but not documented” – well what use is that? Put in place a Wiki and get your developers to make updates if needed.

Top 5 Web 2.0 development technologies to watch in 2008

I was asked to advise a budding web developer on what technologies to get into for 2008. Here’s the list I gave her. Would you agree?

1. Maps API’s – there is probably enough work around just integrating mapping into people’s web sites for them. (Google, Yahoo and 192.com all have APIs)

2. Drupal – lots of people need intranets and drupal works really well for this – most of the work is configuration rather than hard programming

3. Silverlight / ASP.net – this is the top of the range one – Microsoft release Surface next year, likely to drive demand for apps in this technology.

4. Facebook Platform – it feels like flavour of the month I know but it’s so wonderful it’s likely to be around for a while.

5. Netvibes UWA – Netvibes have a universal widget architecture that actually works on lots of different platforms – saves having to write widgets several times (see illustration)

Have your say, why not comment to this note on your top five web 2 technologies to watch in 2008.

What’s an API and why it’s important – part 1

The nitty gritty of Web 2.0 is all aboutthe “API” – that’s short for Application Programming Interface.

API’s are the new doors into software programmes and web sites that allow other software programmes to “talk” to them without human interaction.

If you imagine the software as a big building, then the front entrance would be the “user interface” (where we all use the software i.e. when we browse the web), then the “application interface” is like the delivery entrance, where deliveries are sent. It’s another door to the same building but for a different type of building user. In this case its a door made for other computers instead of people.

An Application Programming Interface (API) allows other software applications to put information in, get information out and use services as if they were real users. For example the Google Maps API allows other applications to send a list of longitude and latitude coordinates and it will return a map with markers on each of those coordinates. Check out this Google Map ‘mash-up’ of World Bank country data to see what APIs can make easy.

APIs are not all created equal – some are wonderful and some are downright difficult to use.

As a web 2 programmer I deal with APIs on a daily basis. In my next blog post I’ll explain some of the ways to evaluate whether an API is any good, before you decide to use it.