Tag Archives: Web

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:

Static social media “share” buttons without JavaScript

Hand-shaped cursorSometimes you want a “share” link in your website or email newsletter but you don’t want the extra JavaScript and iframes that come with the standard social media buttons. Here’s how to do it, giving your users faster page loading times and a bit more privacy.

Twitter

Firstly Twitter, who like to make it easy for us. It’s possible to use twitter.com/home or twitter.com/share but the most useful sharing URL is this:

https://twitter.com/intent/tweet?
  • Parameters: url, text
  • Encode parameters? Yes

The difference is that the user will see a friendly “Share a link with your followers” heading rather than the usual “What’s happening?”. Not only that, but the text within the Tweet is highlighted to make it immediately editable. Nice touch.

Example

<a href="https://twitter.com/intent/tweet?text=Static%20social%20media%20%22share%22%20buttons&url=http%3a%2f%2fdaniemon.com%2fblog%2fstatic-social-media-share-buttons%2f">
    Share on Twitter
</a>

Try it out here: Twitter buttonShare on Twitter

Documentation


Facebook

Despite having an official “Share” button in the past, Facebook have now deprecated it in favour of the ubiquitous “Like” button. For backwards compatibility, however, the “Share” URL still works:

https://www.facebook.com/sharer/sharer.php?
  • Parameters: u (URL)
  • Encode parameters? Yes

Example

<a href="https://www.facebook.com/sharer/sharer.php?u=http%3a%2f%2fdaniemon.com%2fblog%2fstatic-social-media-share-buttons%2f">
    Share on Facebook
</a>

Try it out here: Facebook buttonShare on Facebook

Documentation


LinkedIn

Apparently sharing links on LinkedIn is very good for SEO so this could be an important one to include. The base URL is:

http://www.linkedin.com/shareArticle?
  • Parameters: url, title, summary
  • Encode parameters? Yes

Example

<a href="http://www.linkedin.com/shareArticle?url=http%3a%2f%2fdaniemon.com%2fblog%2fstatic-social-media-share-buttons%2f&title=Static%20social%20media%20%22share%22%20buttons&summary=How%20to%20build%20social%20media%20sharing%20links%20without%20JavaScript%20and%20iframes.">
    Share on LinkedIn
</a>

Try it out here: LinkedIn buttonShare on LinkedIn

Documentation


Pinterest

The relatively new kid on the block is Pinterest. Note that for it to work properly, you should include the media parameter and point it to an image at least 750 pixels wide. The base URL is:

http://pinterest.com/pin/create/button/?
  • Parameters: url, description, media
  • Encode parameters? Yes

Example

<a href="http://pinterest.com/pin/create/button/?url=http%3a%2f%2fdaniemon.com%2fblog%2fstatic-social-media-share-buttons%2f&description=Static%20social%20media%20%22share%22%20buttons&media=http%3a%2f%2fdaniemon.com%2fblog%2fwp-content%2fuploads%2f2012%2f09%2fstatic-social-media-buttons.png">
    Share on Pinterest
</a>

Try it out here: Pinterest buttonShare on Pinterest

Documentation


Google+

Let’s not forget Google who have a bookmarking service, however this has now largely been usurped by Google+ which uses this URL:

https://plus.google.com/share?
  • Parameters: url, hl (human language, e.g. “en”, “ja”, etc. – optional)
  • Encode parameters? Yes

Example

<a href="https://plus.google.com/share?url=http%3a%2f%2fdaniemon.com%2fblog%2fstatic-social-media-share-buttons%2f">
    Share on Google+
</a>

Try it out here: Google+ buttonShare on Google+

Documentation


Hatena Bookmarks

Hatena Bookmarks is a popular bookmarking site in Japan, particularly among the tech crowd. It uses this URL:

http://b.hatena.ne.jp/entry/
  • Parameters: None – just append your target URL
  • Encode parameters? No

Example

<a href="http://b.hatena.ne.jp/entry/http://daniemon.com/blog/static-social-media-share-buttons/">
    Share on Hatena Bookmarks
</a>

Try it out here: Hatena Bookmarks buttonShare on Hatena Bookmarks

Documentation

Other similar resources

Readability for Android

So you want Readability bookmarklets on your Android device, huh? Not so fast! At the time of writing, it’s not possible to access the official Readability bookmarklets on Android but there is a workaround. Here’s how to do it in three easy steps.

Step 1: Copy the Readability script

In Opera Mobile or Mini (I don’t think this works in other browsers), select and copy the code below:

javascript:((function()%7Bwindow.baseUrl%3D'http%3A//www.readability.com'%3Bwindow.readabilityToken%3D''%3Bvar%20s%3Ddocument.createElement('script')%3Bs.setAttribute('type'%2C'text/javascript')%3Bs.setAttribute('charset'%2C'UTF-8')%3Bs.setAttribute('src'%2CbaseUrl%2B'/bookmarklet/read.js')%3Bdocument.documentElement.appendChild(s)%3B%7D)())

Step 2: Create a bookmark

Open the Bookmarks menu and click on the Add button (don’t click Save yet).

Step 3: Edit the bookmark

Screenshot of Opera Mobile Readability bookmarklet

  1. Change the title to Readability (or something similar).
  2. Delete the address and paste in the code copied from above.
  3. Click Save.

Voila! You should now be able to go to any article or blog post, click the Readability bookmarklet and enjoy a better reading experience.

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.

On vendor prefixes — An interview with Dr. Stanley Dards

At last, the existence of vendor prefixes, one of my pet peeves, is under the spotlight. Also at last, the fact that not all modern browsers are WebKit (shock!) is getting some attention.

I (personally) believe vendor prefixes cause more harm than the problem they were designed to solve, namely how to elegantly introduce experimental features in browsers. My belief is that a non-browser-specific prefix such as -beta- has fewer obstacles to overcome than other proposals. Having said that, there’s clearly no easy, one-size-fits-all answer but hopefully more awareness and public discussion will lead to a more plausible solution.

So far, there have been great contributions to the discussion from all sides. A selection of ones I’ve found valuable, but may not necessarily agree with, are listed here:

And as if that wasn’t enough, here are the insights of one Dr. Stanley Dards:

Web Guru

♫ “I wanna be a billionaire…” ♫ Yeah, it’s not a bad song (http://www.youtube.com/watch?v=8aRor905cCw), but a billionaire? Is that all? I wanna be something a bit more… special.

Video URL (with captions): http://www.youtube.com/watch?v=jdgXT0wEuFU

Downloads

For your downloading pleasure, here are the video and audio–only.

License is Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported. If you need a media player, I recommend VLC.

Lyrics

I wanna be a web guru,
so frickin’ much.
Someone even Zeldman couldn’t touch.

I wanna be on the cover of
Wired magazine,
smiling next to Sir Tim Berners Lee.

Oh every time I’d go online,
I’d fix another site’s design.
Another day, another interview.
Oh what, what I wouldn’t do,
to be a web guru.
To be a web guru.

Yeah, I would have a show like Diggnation, be a web sensation.
All the geeky girls could not resist the temptation.
Every newspaper would have a photo with my face on,
but not on the front page – in the technology section.

And I’d tell everybody how to make a website.
Using open standards is the only way to get it right.
And people would smile as I do my thing.
I’d give them something special, yeah, I’d start to sing!

Oh, every time I’d go online,
I’d fix another broken site.
Another day, another interview.
Oh what, what I wouldn’t do,
to be a web guru.
To be a web guru.

I wanna be a web guru,
so frickin’ much.

Web conference blues

You know that lonely feeling, where all the hip web designers and developers gather at the coolest conference and you’re stuck at your desk? Here’s a song for those of us that miss out on all the glamour.

The original song, by the way, is Folsom Prison Blues by Johnny Cash.

Video URL (with captions): www.youtube.com/watch?v=u_gAPRJmEWs

Downloads

For your downloading pleasure, here are the video and audio–only files.

License is Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported. If you need a media player, I recommend VLC.

Lyrics

I see the tweets a-comin’
They’re comin’ down the screen.
They’ve all got the same hashtag and I,
I know what that means.
It means I’m stuck here at my desk
and time keeps draggin’ on.
And the web conference keeps rollin’
all tickets sold except one.

When I was just a baby
my momma told me “Hey!”
“Always do things early or
you’ll regret it some day.”
Well I knew I should have booked
but I left it too late.
Yes, I missed the earlybird discount.
Why did I procrastinate?

I bet there’s web folks tweetin’
in a fancy conference hall.
They’re probably drinkin’ coffee
and talkin’ ’bout HTML.
Well I knew I had it comin’.
I know it’s not to be.
But those tweets, they keep on comin’
and that’s what tortures me.

If my boss gave me approval,
let me register online,
I’d jump on to the next plane.
I could still make it on time.
But I’m stuck here at my desk.
Here’s where I’m gonna stay.
I’ll just go right back to Farmville
and hoe my blues away.

Mailing list of fire

With apologies to Johnny Cash, the sorry tale of a mailing list that takes no prisoners. On a totally unrelated note, how’s HTML5 coming on?

Mailing list of fire on YouTube (with captions): www.youtube.com/watch?v=HCwgKtiu1II

Downloads

For your downloading pleasure, here are the video and audio–only files.

License is Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported. If you need a media player, I recommend VLC.

Lyrics

The web is a wondrous thing.
Flickr, Facebook and Bing.
One thing you must resist.
The pull of the mailing list.

I fell in to a mailing list of fire.
I scrolled down, down, down
and the flames went higher.
And it burns, burns, burns
this list of fire,
mailing list of fire.

And it burns, burns, burns
this list of fire,
mailing list of fire.

A geek, he never forgets.
When someone’s wrong on the internetz.
I tried not to act like a child.
Oh… but the trolls went wild.

I fell in to a mailing list of fire.
I scrolled down, down, down
and the flames went higher.
And it burns, burns, burns
this list of fire,
mailing list of fire.

And it burns, burns, burns
this list of fire,
mailing list of fire.