Tag Archives: free

Web API Design – a definitive guide

Cover of Web API Design book“Web API” is a confusing term. It can refer to interfaces to be implemented by web software such as browsers, for example the W3C geolocation API, etc. It can also refer to how a web service exposes its data, and it’s in this context that Brian Mulloy has written what I hope will become the bible of REST-based API design. His ebook, entitled Web API Design, is available for free (well, in return for your email address).

As web developers, we want APIs that are easily-understandable and consistent, resulting in less time reading documentation and more time experimenting and being pleasantly surprised that something just works.

At around 30 pages long it’s a quick read but gets straight to the point with concrete advice. Right from the start he emphasises a pragmatic rather than theoretically ideal approach — developers should be able to experiment with and learn the API without the documentation — and highlights good and bad examples from popular APIs. Here’s a quick summary of some of his recommendations.

  • Use two base URLs per resource, e.g. /dogs and /dogs/1234
  • Keep verbs out of your base URLs, unless the data is the result of an action, e.g. “calculate” or “translate”.
  • Use HTTP verbs (GET, POST, PUT, DELETE) to operate on the data.
  • For clients that don’t support this, make the method an optional parameter, e.g. /dogs/1234?method=delete
  • Use plural rather than singular nouns.
  • Use concrete rather than abstract names.
  • Put complexities after a question mark, e.g. /dogs?color=red&state=running
  • Be verbose but simple in your error messages, ideally linking to online docs.
  • For specific fields, us a comma-delimted list, e.g. /dogs?fields=name,color,location
  • Use “limit” and “offset” for pagination, e.g. /dogs?limit=25&offset=50
  • To specify formats, use the familiar dot notation, e.g. /dogs/1234.json
  • Use JSON as the default format, following JavaScript conventions for attribute names.
  • Use OAuth 2.0 for authentication.

There seems to be a relative lack of guidance in this field so this book has a good shot at becoming the go-to reference. The result of that would be more consistency between APIs and an easier life for website and app creators. Of course, differences in existing APIs will linger on because of the difficulty in upgrading them once released, but that’s one more reason why it’s important to base an API design on solid guidelines such as these in the first place.

Download the ebook here: offers.apigee.com/web-api-design-ebook/ (no affiliation)

Also, here are a couple of other good resources about designing RESTful APIs:

Free HTML5 template

Official HTML5 logoAfter being asked for a bit of advice by a colleague, I decided to make a very simple starter template for creating an HTML5 page. You can download it here:

Download HTML5 template

Notes

The tricky part is making sure it works in older browsers, for which I used the following two steps:

1. Normalize.css
(Click on “normalize.css” -> “Raw” to get the main CSS file.)

This makes all browsers behave the same way, including making relevant HTML5 elements into block elements. I recommend minifying the CSS to save bandwidth and time.

2. HTML5 Shim

This makes HTML5 elements styleable in old versions of Internet Explorer. Put it after all styles in <head>.

I’ve also added a viewport meta tag as follows which, in most cases, should improve the readability of the page on small screen devices.

<meta name="viewport" content="width=device-width, user-scalable=yes">

Going further

You might want to include Modernizr in your page, to enable you to detect support for newer CSS3 and JavaScript features.

For a much more full-featured template, there’s the popular HTML5 Boilerplate with a host of built-in goodies.

I’d love to hear if this is useful for you or if you have ideas for improvement – let me know in the comments below.

Free online web development checkers

A green checkmark

Inspired by a forum post I came across the other day I’ve compiled a list of free online checkers/validators for web developers. Please let me know if you’re aware of others. (Updated 16th September 2010)

(X)HTML

XML/FEEDS

CSS

MOBILE

ACCESSIBILITY

LINKS

MICROFORMATS

OTHER