This week I did a presentation at the London iPhone Developer Group meeting. Given my experience with using lots of APIs, I thought it might be a good, if dry, topic. I tried to spice it up by complaining about lots of them and trying to condense that negativity into some useful lessons to take away.

Most of the other discussions of this subject that I’ve seen focus on designing libraries but I thought the same lessons could be applied to all kinds of interfaces, from Objective C libraries to REST API’s for connecting to web services. (I don’t mean to suggest that the focus of the two articles I link to is wrong. They’re both very much worth reading.)

You can see a PDF of the slides here (though they might not make much sense without what I was saying at the time), but the gist is as follows:

• Design your APIs around use-cases. Many appear to be designed around “how can I made the data I have available.” This is the wrong way round
• Clients need to access data in a predictable, reliable way. Being clever accepting any old junk and trying to do the right thing is often not the right thing to do
• Communicate how it works and how it’s going to change clearly. Examples and sample code are always useful
• Think about error cases. “Something went wrong” is not a good error message
• Think about the devices that people are likely to be accessing your service from. Mobile apps have latency, bandwidth and CPU constraints that desktop computers and other servers do not. The iPad 4 has more resources to throw at a problem than an iPhone 3GS. Your code might need to work on both
• Be consistent. Make your API look like other, similar APIs and use the patterns of the technology you’re using. That means delegates and return codes for Objective C, inheritance and exceptions for C#
• And, most importantly, use your own API. Don’t keep special “secret sauce” for your self. How else are you going to know whether it works than by actually using it?

Ideally I’d end a presentation (or blog post) with salient advice on the best way to do something. This is an exception. I don’t think there’s a one-size-fits-all solution and I’m generally weary of Best Practice guides.

So I’ll end by noting that poor APIs result in poor applications. It’s worth investing the time and energy in doing it well. Your users and your future self will thank you.

If you follow any iOS technology blogs you might have seen this recent scandal:

If you bought the app on Google Play (even if you cancelled the order) I have your email address, your suburb, and in many instances your full name.

This, they say, is bad because this is not what happens with Apple’s App Store.

However, I don’t think Google are doing anything weird here, and I say this as someone who is not a fan of Android. The commercial relationship between developers and Apple is different from the relationship between Google and developers¹.

In Apple’s case, the developer has a single customer (Apple). You licence your code to Apple and Apple sells your app. The end users relationship is with Apple, not the developer. You get royalties, much in the same way that you get royalties when you publish a book. I’m still waiting for my million dollar advance from Apple, but the principle is the same.

Google plays a different role. They’re just an intermediary. The customers buys the app directly from the developer (using Google Wallet). This is why the developer has access to email, location, etc.

Saying that this is a privacy issue is like paying for a latte with a credit card and complaining that Starbucks now has your Amex number and name. Of course they do.

There are always stories of disreputable restaurants skimming credit cards and defrauding consumers. The trick, insofar as there is one, is not to eat at those restaurants. Similarly, if you think a developer is likely to use your data in an underhand manner, don’t download their software. It’s that simple.

Should Google be more upfront about who gets what details? Possibly. It never hurts to be open and honest — dare I say, not evil — about privacy matters. But I don’t think what they’re doing is inherently bad.

1. Please let me know if I have any of this wrong. I don’t develop Android software but this is my understanding of how it all works. [↩]

Eric Schmidt says Google is the new Microsoft and it’s winning the war against Apple. I think he’s missing some perspective.

One of the key things that Steve Jobs realised when he returned to Apple in the late nineties was that the industry is not necessarily a zero sum game.

“We have to let go of a few things here. We have to let go of the notion that for Apple to win, Microsoft has to lose.”

The current situation is not identical but I think that the lessons might be substantially the same. While Google believe that they’re winning it’s not clear to me that they’re playing the same game as Apple and Microsoft. It’s like saying that you’re winning at Scrabble when your opponent is playing Chess; sure, you played some great words on triple letter scores, but your chances of getting check-mate are limited.

For all Google’s efforts and marketshare, most web traffic and ad impressions — the real metric that they’re interested in — still comes from iOS. They largely succeeded in commoditising the smartphone, unfortunately their users either don’t surf the web much or, in the case of Android-derived devices like the Kindle Fire, do but don’t go via Google.

Would they not be better toning down the rhetoric and figuring out how everyone can play nicely? War makes for good headlines but often ends in everyone losing.

For Google to win, Apple does not have to lose.

Like all the best upgrades, iOS 6 is almost entirely invisible. It works just like iOS 5 — which is to say, pretty well most of the time — but with some convenient new additions. Also, unlike version five, it’s been relatively stable throughout the beta process.

What’s new and what will you like? I’ve grown so accustomed to most of them that I had to look up the “What’s new” page on Apple’s website. Really, that’s a good thing. Invisibility is the fate of a feature that’s quickly integrated with how you use a device. (The thing that makes it tricky is that it’s also the fate of a completely useless feature that you never use.)

Roughly ordered by how much I like them:

• Do not disturb. This is the one feature that the Blackberry had that I missed in iOS. I only had a Bold for a few months but being able to switch off “work” between certain hours was brilliant, and the same is true of Apple’s implementation. You set a range of hours and it automatically mutes. This feature alone is worth updating for
• Shared Photo Stream. This will be even better when I can share directly with other people’s devices, but being able to create a web gallery of Photo Stream pictures has already proved to be useful
• iCloud tabs. This feature sat idle until Mountain Lion and then… great. The only thing I would ask is for this to work on my iPad!
• New options when receiving a phone call. The “decline but remind me later” is a great option

Stuff I’m ambivalent about:

• Maps. Apple switched from using Google’s maps to their own. I miss Street View but otherwise all the functionality seems to be there. Searching for stuff seems a bit hit and miss, just like with Google Maps. Search results differ but I’ve not used it enough to determine whether one is better than the other
• Siri. I have an iPhone 4 and an iPad 1, the former of which doesn’t support Siri, the latter of which doesn’t support iOS 6
• Passbook. This might be great when there are apps to support it. Right now, a waste of a spot on my home screen
• FaceTime over 3G. Not sure if it will be supported in the UK. Rarely had the need to call when there’s been no WiFi

The only “bad” I can think of is that it doesn’t run at all on my two year old first generation iPad. I understand technically why they made this decision, but at the same time it’s a little galling to have such a relatively recent device be declared obsolete.

In conclusion, this is one of Apple’s “refinement” releases. They seem to have a big update (iOS5, Lion) and then a release that fixes some of the rough edges (iOS6, Mountain Lion). 2012 has been a year of two spit and polish releases. I’m not complaining.

I’ve been using Mountain Lion, the new version of the Macintosh operating system, for less than a day so this isn’t intended to be detailed (see John Siracua’s review) or thorough. I have, however, kicked the proverbial tyres so here are a few, quick thoughts.

Good

• Probably the most stable 10.x.0 release I’ve used
• Little earth shattering but lots of really nice improvements, not all of which I’ve seen documented (for example, attachments in Mail now appear in the “All My Files” view in the Finder, multiple Time Machine disks)
• Notification Center works well; AirPlay mirroring is going to be really useful
• I’ve not found any software that worked in Lion that no longer works. That includes stuff like VMWare (scary because it’s low-level) and Photoshop Elements 6 which is not listed on Roaring Apps compatibility list

Bad

• You’re not going to be able to make the best use of everything until iOS 6 comes out. This is a bit of a pain if you own a first generation iPad and know that this will never happen…
• The installer got confused. After “less than a minute remaining” it went to “-1 minutes remaining.” It got to -7 before finally resetting to twenty minutes. It worked in the end so clearly this isn’t a “show stopper” but anything weird in a process that reconfigures your system is disconcerting
• I launched Mail. It upgraded my database successfully and then, while I was making a cup of coffee, crashed. It’s been stable ever since, but first impressions and all that
• Every time I click on Messages — the new iChat — it opens the instant message (“Messages”) window. Do Not Want

Ugly

• The font in the new Notes app. What were they thinking?!
• If you didn’t like the iOS-ification of Lion you’re not going to like Mountain Lion any better. But if that’s the case you’d probably start thinking about migrating to another platform!

But overall, at less than £15 it’s a no-brainer if you use your Mac a lot.

Imagine the scene…

Okay, that’s a bit dramatic.

Recall that I have an iPhone app called Yummy. It has, or rather had, a website called YummyApp.com. Last year I formed a company called Wandle Software and since then have been merging my various web “properties.” The website moved over to wandlesoftware.com earlier this year, email was the last thing that needed transferring.

My email is hosted using Google Apps — Gmail but without the gmail.com email address if you’ve not heard of it. What I wanted to do was move yummyapp.com from being a “proper” domain to what Google refer to as a domain alias for wandlesoftware.com.

I assumed that what I’d have to do was deactivate the old one, wait a bit and then reactivate it on the new domain.

So I looked at the Dashboard to find the “delete” option.

Nothing.

So I deactivate all the services. I delete all the users except one. And I look again. Still nothing.

Desperate times call for desperate measures. I look in the documentation.

According to the Help I was basically correct. Unfortunately the delete option just wasn’t there.

I reset my cache. I switched to Firefox. And cleared the cache in Firefox, all to no avail.

The Help for Google Apps is actually pretty good. These seems to be a lot of it and, as you’d imagine, search mostly works well. But help is different from support and — long story short — there’s no way to get the latter.

Instead there’s a forum that (I think) is user supported rather than directly by Google. This is fine unless there’s a problem with the software. I asked a question and within an hour got a very helpful reply that said that I needed to raise a support ticket.

So how do you raise a support ticket when that’s a “value add” feature reserved for paying customers? (Even when there’s a fault.)

I cheated.

I took the “free thirty day trial” of Google Apps for Business. I immediately raised a support ticket and only a couple of hours later got a phone call from the US. The guy was personable, efficient and immediately solved my problem. He even offered to stay on the line long enough for me to confirm that it had worked rather than hanging up immediately to improve call times (as many call centres do).

Of course I appreciate why Google can’t provide phone support to all and sundry, but surely there has to be a better of helping customer who find flaws in the software?

This is really starting to bug me. Nearly a week after Facebook’s IPO and the papers are still saying that it was a failure. It wasn’t, or at least, whether or not is was depends on who you are. And I suspect you prefer the winner to the so-called losers.

Let’s start with the basics. What is an IPO? It’s simple: a company sells a part of itself in exchange for cash. In the physical world, that’s the same as me making something and selling it to you. For the sake of this example, let’s say that I sell it to you for £1.

And what’s the share price? Well, once the IPO has completed, someone else can buy a share from you. The share price is basically just the price that you can agree on. Maybe you could sell it for £1.20. In this scenario, you just made 20%. Well done you.

And what about me? Well, I’ve made nothing more.

Let’s apply that back to Facebook. The initial price was $38. That’s the amount that Facebook got for each share. Let’s say that, as many expected, the share price rocketed to $50. Who benefits? From my example above, it should be clear that it would mostly be the people who bought the shares. The banks, the speculators. In short: not Facebook.

It doesn’t take a lot of thought to realise why the share price would rise so rapidly on the first day. Is it because the value of the stock increases rapidly in only a few hours? Or is it because the stock was originally underpriced? Contrary to what you read in a lot of papers, a rapid rise on the day of the IPO really means that the banks did a poor job of pricing the shares and that the company made far less money than they should have.

(To be clear, Facebook benefits from having a higher share price over time. I’m just talking here about the price rocketing on day one.)

Facebook wanted to get the most money possible out of the shares that they were offering. It turns out that the did an excellent job. They sold them for $38 and by the end of the day the market pretty much agreed. They left very little money on the table.

So unless you feel sorry for the banks or the speculators who failed to make a quick buck, the Facebook IPO was actually pretty successful.

Blocking content from the Internet is getting a lot of press of late. The last couple of weeks has seen the Pirate Bay being blocked by a number of large ISPs and debate over whether the blocking of “adult” content should be opt-in or opt-out.

Unfortunately the enthusiasm to “protect the children” and “protect the copyright holders” seems to have pushed aside much of the debate of whether we should be doing this at all or whether it’s practical.

Whether we should be doing it or not is political. I have my opinions¹ but what I want to concentrate on here is whether or not blocking such content is actually possible.

There are a number of different ways of vetting content. They’re not necessarily mutually exclusive, but they’re all deeply flawed.

First, a common one from politicians: the Internet is just like TV and cinema:

Perry said that she has been accused of censorship over the campaign, but argued that the internet was no different to TV and radio and should be regulated accordingly.

No, no it isn’t. There are a handful of TV channels, even taking cable and satellite into account, and a relatively small number of movies released every week. It’s practical to rate movies. TV programmes are distributed centrally, so pressure can be placed on a small number of UK-based commercial entities when they do naughty things.

The Internet is very different. Firstly, counting the number of web pages is rather harder. This is what Wikipedia has to say:

As of March 2009, the indexable web contains at least 25.21 billion pages.[79] On July 25, 2008, Google software engineers Jesse Alpert and Nissan Hajaj announced that Google Search had discovered one trillion unique URLs.

Note that even the smaller number is from three years ago. I’d bet that it’s not smaller now. Clearly the same system of rating an regulation clearly isn’t going to work on that scale. And even if it was possible to rate each of these sites, the UK government has little leverage over foreign websites.

There are basically three ways to automate the process: white list, black list and keyword scanning.

A white list says “you can visit these websites.” Even assuming no new websites are ever added and no new content is ever created, rating those 25 billion pages is not practical. I don’t think we want an official approved reading list.

A black list is the opposite: “you can visit anything except these pages.” We have the same scale problem as with white lists and a few more. Much of the Internet is “user contributed” and it’s not hard to create new sites. If my site is blocked, I can create a new one with the same content very, very quickly. Basically, there’s just no way to keep on top of new content.

Keyword scanning is exactly as it sounds. Your internet traffic is scanned and if certain keywords are spotted, the page is blocked. It’s automated and dynamic, but what keywords do you look for? “Sex”? Well, do you want to block “sex education” websites? “Porn”? That would block anti-porn discussion as well as the real thing.

The scanners can be a lot more sophisticated than this but the fundamental problem remains: there’s no way to be sure that they are blocking the correct content. Both good and bad sites are blocked, and still with no guarantee that nothing untoward gets through.

In all cases, if children can still access “adult” content with relative ease — both deliberately and accidentally — what’s the point?

Of course I’m not in favour of taking content without paying for it or exposing children to inappropriate material. But, to use a cliche, the genie is out the bottle. Like the reaction to WikiLeaks there is little point in pretending that nothing has changed or that the same techniques and tools can be used to fight them.

Instead, if you’re a publisher you need to make your content legally available and easier to access than the alternative. iTunes has showed that people are willing to pay. So far, you’ve mostly shown that you’d rather treat paying customers as criminals. That’s not helping.

As for protecting children, it all comes back to being a responsible parent. Put the computer in the living room. Talk to them. Sure, use white or black lists or filtering, just be aware that it can never be 100% effective and that not everyone has children that need protecting. Whatever the Daily Mail and your technically unaware MP says, you can’t say the connection is being checked, problem solved.

1. I’m basically anti-censorship and in favour of personal responsibility. There are already laws covering the distribution obscene materials, why should there be restrictions on legal materials? [↩]

Instapaper

• The save page bookmark works with Google Reader. That is, it saves the link I’m reading rather than the Google Reader web page.
• Page turn. Rather than display the page as a long, scrollable single page, Instapaper paginates the document. You can “turn” the page much as you do in iBook or the Kindle app.
• Progress indicators. I like that it shows roughly how long a document is and how much has been read.
• Clean, minimal interface.
• The trick of reading the current page to make site like NYTimes (with page view restrictions) or LWN (pay walls) is a great idea but not completely reliable.
• Recent updates have been less stable. Going from day to night mode — an otherwise nice idea — almost always crashes. Putting the app into the background often loses the current location (it returns to the end of an archived article).

Pocket

• Brighter, prettier interface. Much nicer to use than Read It Later, at least the last version that I used.
• Less app support.
• Syncing articles is (subjectively) faster.
• Stable.

Despite the longer list in favour of Instapaper I’ve been using Pocket more in the last couple of weeks. It’s the last bullet in both lists that’s the killer. The paywall-swerve, expensive fonts and even the Google Reader cleverness are all well and good, but if the app isn’t ready when I want to read it’s all for nothing.

You’ve probably seen that it’s the Sinclair Spectrum’s thirtieth birthday today. There are lots of great retrospectives — this is probably the best single source I read — so I’m not going to rehash all that. But I thought it might be worth a few words of my own.

Like many Brits my age, the Spectrum was my first computer. Technically it was the family computer, but after a few weeks I was pretty much the only one who used it.

I remember some of the first few hours using it. I remember, for example, ignoring most of the preamble in the manual and diving straight into typing in a programming example. Those who have used a Spectrum will realise that you can’t just type in code; you need to use special keyboard combinations to get the keywords to appear on screen. I didn’t know about that.

After a while I managed to persuade to let me type in the code. The computer didn’t really understand it and I didn’t know why. I can’t remember whether I found the right section in the manual before having to go to bed but even in my confusion I knew that I was hooked.

And really that was the start of my career in IT. I started really wanting to play games but I ended up spending more and more time programming and less and less loading Bomb Jack. Usually I saw something neat in a program and though “How do they do that?” Then I’d try to figure out what they’d done. I was quite proud of making some text slowly fade into view and then gradually disappear again. Obviously that was after the obligatory:

10 PRINT "Stephen was here!"
20 GO TO 10


I remember all that surprisingly well. Which makes the following line all the more shocking:

It may have been startlingly modern once, but at 30, the Sinclair Spectrum is as close in time to the world’s first commercial computers of the 50s as it is to the latest iPad.

The first commercial computers where created in the early fifties. The first computers — at least computers you’d kind of recognise as computers — were only built a few years before that. Computers are so powerful and connected these days that it’s difficult for me to remember what I even did with them. I wonder what we’ll make of the iPad in a few decades? I’m sure it’ll look just as dated.

The last thing I wanted to mention was about that weird, unique program entry system. In short, each key had a number of different keywords printed on it. The J key, for example, had LOAD (used to load a program from tape), VAL, VAL$ and the minus sign. When you entered code, the editor would be in one of a number of modes and, in addition to shift, there was a key called “Symbol Shift.”

I’ve never seen a sensible explanation for this. They all seem to say it was “easier” or a cue for users so they’d know all the valid keywords to Sinclair Basic. I never bought this. Is it really easier to remember a bunch of non-standard keyboard shortcuts rather than just type? Don’t think so.

And then when I was at university I did a course on compilers, the software that is used to turn human readable code into the binary gibberish that a computer can actually run.

The interesting bit was all around the grammars and recursive descent parsers and the mental challenge of writing a program that wrote other programs. But the first step of the process is called lexical analysis, which takes the jumble of letter that is your program and converts them into “words” that can be processed more easily, so PRINT is a keyword, 123.4 is a number and “Hello” is some text.

Given the resource limitations of writing a whole operating system and BASIC interpreter in 16k, my guess is that it was easier to write a strange keyboard entry system than a lexer.

Can anyone comment on the accuracy of this guess?

But back to nostalgia. From hazy memories, to university, to wild speculation and the iPad. We’ve come a long way. But it was the Sinclair Spectrum that started it all for me. Thank you Clive Sinclair!