The Unwritten Human Interface Guidelines for iOS 4.2

Published on November 30, 2010 in Technology. 1 Comment

Apple’s iOS Human Interface Guidelines (HIG) (PDF) provides great advice for creating an app for iOS. However, for an app to really fit in with iOS, it should embrace the unwritten conventions that Apple follows in their apps. To help myself and other developers stay on the right track, I’ve assembled a guide with lots of the things that should probably be in the HIG but are not. I’ll continue to update this guide as I see apps with “incorrect” user interfaces. I’ve included screenshots of the right way to do things (usually from Apple’s apps or Iron Money for iOS).

Button placement

Buttons should almost always go on the right first, then the left. Additionally, add buttons should go on the right, and edit buttons should go on the left; there are very few circumstances in which this rule should be broken.

Use “Done” buttons for adding or editing data from a list; use “Save” to save a value to an editing table. In general, if you have a list of objects, a user should be able to select an object, then tap “Edit” to edit it, and tap “Done” to save their changes. If an object has an attribute, it is permissible to let them tap the attribute and then tap “Save” to save the change to that one attribute (because they’re not “done” with the entire editing process).

Settings screens should have a “Done” button in the upper right.

Table views

When making a custom UITableViewCell, follow the other UITableViewCell’s styles as much as possible.

When a user selects something from a table view with checkmarks, the checkmarked cell’s text should not be in black, but in blue.

On iPhone/iPod touch, a search feature should usually be hidden underneath the navigation bar until it’s pulled down by the user. Then, above the status bar, there should be a solid color.

Don’t use the detail disclosure icon unless you actually have details to disclose when the icon is tapped.

Keyboard

Almost all keyboard types have some sort of “done” button. When developing an app, it’s important to change the done button to whatever makes the most sense in that particular view. For example, if you have multiple text fields that the user might want to move between, changing the done button to “Next” on the keyboard (and moving the user to the next text field when they tap the next button) will make your app easier to use.

The keyboard uses a “Next” button in the bottom right because the user has multiple text fields to complete.

iPad popovers

Many iPad apps use popovers to display additional views once a button is pressed. Some apps use popovers to allow users to choose between different things; the App Store allows you to choose between different categories, the iTunes app allows you to choose different genres of music, etc. When a user selects one of the options provided in the popover, the button should update to include their selection.

Language

Staying consistent with the text that Apple uses is a great way to have an interface users might already be familiar with and helps with localization.

Many apps provide in-app passcode protection. Apple’s Settings app is a great resource for deciding how to title all of the buttons and views associated with passcode protection.

If your app allows users to sign in and out of a service, you probably provide buttons for signing in and out of the service. The Find iPhone and MobileMe Gallery apps both include this functionality. Their sign out buttons read “Sign Out” and display an alert view with the text “Are you sure you want to sign out?” and the buttons “Cancel” and “Sign Out”. If you include text with the username, it should read: “Signed in as: %@” (replacing %@ with the username).

The Devil is in the Details

iOS is a great platform for creating amazing user experiences. Apple’s apps provide a great foundation for designing user interfaces for iOS. Breaking the rules is okay, but be wary of unintentionally breaking the unwritten rules of designing apps for iOS.

Using a Queue to Fake Fast UUID Creation

Published on October 31, 2010 in Uncategorized. 0 Comments

Today I released an update to Iron Money that made uploading 60% faster. A significant part of that speedup was related to changes in how UUIDs are created; this post outlines the problems the old version had and the solutions in the most recent version of Iron Money.

When a transaction is added to Iron Money, it’s assigned a UUID. A UUID typically takes about 10ms to generate; that might seem fast, but compared to everything else, it’s really slow. When a user uploads account data to Iron Money, a UUID is generated for the upload and all of the transactions in the upload; so if an upload contains 100 transactions, it’ll take an entire second just to generate the UUIDs for the transactions. This is terrible, and for an action as frequent as uploading account data, fairly unacceptable.

As with all programs, the easiest way to make something go faster is to make it do less. In Iron Money’s case, the goal was to move UUID creation out of the uploading process. The easiest way to do this is to pre-generate the UUIDs before they’re needed, then get the pre-generated UUIDs as they are needed.

I decided to create a new table in MySQL that had two columns: one for an ID, and another with a UUID. Every few minutes, Iron Money fills this table with new UUIDs (actually, it fills it until it has 1000 UUIDs, which is more than enough for any given few minutes). The ID column is filled with zeroes by default.

When a UUID is required, Iron Money creates a random ID to use with the table. It then updates a row in the table with this random ID, selects the row that was updated, and then deletes the row that was updated. This makes it possible for the same table to be used by different processes; since there are billions of possible random IDs, the chances of two processes creating the same random ID near the same moment in time is very unlikely. If you’re really concerned about the chances of collision, you can store the random ID in memcached and check memcached before using a random ID.

This works well, but there is one last part to this system that makes it perform very well. In an upload situation, I typically know about how many transactions are going to be created by the upload. Thus, instead of doing the update-select-delete dance for every UUID needed, I do this dance once before any UUIDs are needed and simply store the UUIDs in an array. When a UUID is needed, I can simply pop one off the array instead of going to the database; of course, if there aren’t any in the array, I can always fall back to the database, or fall back to creating a new UUID from scratch.

Using Far-Future Expires for Static Resources

Published on August 31, 2010 in Performance. 0 Comments

Creating a high-performance website can be tough, especially if you have a lot of resources (CSS, images, and JS) on your site. Seller’s Market’s home page weighs in at a hefty 992.56KB right now, but if the page is refreshed, only the HTML document needs to be downloaded again (at 17.60KB); 98% of the resources used to make up the home page are kept in the browser’s cache. In this post, I’ll dive into the implementation details behind what makes this possible.

Yahoo’s “Add Expires or Cache-Control Header” recommendation is the driving force behind what makes this possible. The recommendation suggests adding an Expires or Cache-Control header to responses to tell the browser how long a resource can be cached. If you tell a browser that it can cache a resource for ten years, it probably won’t need to download the resource again if it’s in the cache. This is exactly what’s happening on Seller’s Market; each resource can be cached for up to ten years, so subsequent reloads or going to a different page can reuse items in the cache (and since multiple resources are used across pages, this means less needs to be loaded for subsequent page loads).

The big catch to this is invalidating the browser’s cache; if it has a cached version of “/home.css” that it can use, it’ll use it. If you update home.css, you’ll need to make sure the browser downloads the new version.

In the interest of keeping things simple, the easiest way to do this is to change the URL of a resource when the resource changes. For example, the “/home.css” file might be called “/home-1.css” and change to “/home-2.css” when it’s updated. Since the URL changed, the browser won’t have a copy in cache and will download the updated resource.

I went through a few ways of doing this, but I settled on the following method: whenever a resource changes, a script is run to minify any changed resources (with Minify), the minified resources are then saved to disk with a hash of the resource’s contents appended to the filename, and a manifest is created that contains all of the original URLs and all of the versioned URLs. I’ve found this solution optimal because it allows each resource to be versioned separately, it lowers the dependencies for serving the files (a simple HTTP server is all that’s required), and the manifest file allows the original URLs to be used in code.

The manifest file is used in any code that needs the URL to a resource. I can simply look up the current versioned URL (e.g. “/home-3.css”) by supplying the original URL (e.g. “/home.css”), so I don’t have to change any URLs when the resources are updated.

The end result is that each resource gets served with an Expires header with a long time and the browser can hold onto the resource for as long as its cache can handle it. If there’s a change, a simple recompile will update all of the appropriate resources, and only the changed files will be downloaded by the browser, creating a better experience for your users.

Conducting Usability Tests for Websites

Published on July 14, 2010 in Uncategorized. 1 Comment

I conducted a usability test for Seller’s Market last week and a friend asked me about my method. The following post is a look at how I conduct usability tests for websites.

Why?

Usability testing is useful for determining three things: what captures users’ attention on your site, your website’s effectiveness, and your website’s usability. The first is important because you’ll want to learn what the user looks at on your site; you have a problem if your message isn’t being delivered immediately or your users never end up looking at your call-to-action. The second item, your website’s effectiveness, is important because if your message isn’t being quickly and efficiently conveyed to your users, they might leave the site with no memory of what you actually do for them. Third, it’s important to determine whether or not your website’s design and forms are easy to use—if users have a difficult time completing your call-to-action, then your website isn’t converting as many users as it could.

[I’ve mentioned call-to-action twice now; presumably, you want your users to do something (sign up, call you, buy something, etc.)—your call-to-action is whatever is asking/telling them what to do next. In the case of Seller’s Market, we want them to either call a broker or fill out our Get Started Now form.]

What to test and how to test it

Before you conduct your usability test, you’ll need to sit down and determine what you want to test and how you want to test it. For determining what captures a user’s attention, I suggest having them look at the page for about ten seconds and then asking them what they remember looking at and what they remember from the page. This should help you determine what captures their attention and whether or not you’re conveying your message quickly enough.

I also suggest testing your website’s effectiveness by giving them a few minutes to use your site. A user should have a good idea about what your business offers them within the first ten seconds of using your site, but giving them a few minutes to soak up the rest of the information will allow you to determine whether or not the rest of the text properly conveys what you what them to understand.

To test your call-to-action(s), you can ask your user about where they would go if they wanted to take advantage of what your business offers. Additionally, be sure to actually go through the pages that your user would use; have them fill out your contact form or have them sign up and start using the website. It’s really important to determine whether or not your website is actually usable, so this is where you should probably spend most of your time.

Getting yourself and your user ready for the test

Now that you’ve determined what you should test, I highly recommend writing down a full script of what you’ll say to your user. This helps you repeat tests in the future and phrase your questions appropriately—if you ask leading questions during the usability test, it’s probable that your user will hear the words you’re using and look for them on the site. For example, Seller’s Market has a listing search feature called Search Actives; it’d be leading to ask a user to search for active listings, but asking them to “find properties for purchase” will make them think on their own once they don’t see a “Properties for Purchase” link.

I suggest keeping the user in as familiar of an environment as possible—if you can conduct the test in their home, or at least on their computer, you’ll keep them more comfortable. While I’ve never had an issue with a user testing on a computer that wasn’t theirs, it does make the situation a little bit more stressful.

I do recommend staying side-by-side with your user and recording audio of the entire usability test. If you can record the screen, fantastic (it’s great for reference), but it’d recommend against recording video of the user’s face while testing (recording from behind is probably okay, although I can’t say I’ve ever done this). It’s okay to have another person in the room during the test, but be sure to explain to them that they’re only there for observation.

I’ve used the word “test” throughout this post, but it’s very important to convey to your user that it is not a test of their ability or comprehension, but a test of the website‘s effectiveness and usability. Every user I’ve had has felt a bit pressured because it feels like the test is testing them, so do as much as possible to make the user comfortable.

Before you start the test, you’ll want to ask the user to speak their thoughts. You’ll need to prompt them to do this throughout the test (since most of us don’t constantly talk about what we’re reading or doing when we’re using websites), but it’s helpful to know more about their thought process.

Test time

Hurray! You’ve written your script, have a user that’s in your website’s target demographic, and have everything setup for a smooth usability test. Hopefully everything will be perfect and the user won’t run into any issues, but when they do, you’ll want to be prepared.

First, if they ever run into an issue that is not their fault, immediately intervene and help them out; I’ve conducted usability tests early enough in the testing process that bugs have cropped up—simply tell your user that it’s not their fault and walk them through whatever is necessary to get around the bug. The only other time to step in is when they become visible/audible frustrated and are unable to complete a task; you’ll want to show them what you were expecting them to do and phrase it like that (e.g. “we were expecting you to do this, but obviously we didn’t think that over well enough”).

Otherwise, you’ll want to stay as hands-off as is possible. This includes when they ask you questions about what happens if they were to do a certain action (e.g. “what would happen if I clicked this link?”); when users ask questions, I recommend giving them as much of a non-answer as possible (e.g. “you’re free to click on that link to find out”).

Your user might suggest things as well, especially if they don’t think something makes sense. While it’s great to hear what they would have done, you’ll probably need to stay as non-committal as possible and simply say that “that’s something [we’ll] definitely consider.”

I don’t encourage you to mislead people, but when they suggest features or say how things are, don’t bother disagreeing or stating how things are in reality. I still haven’t figured out how to smoothly deal with this: just saying “okay” can leave a bit of a bad taste.

Above all, you’ll need to continually give your user positive encouragement, even when they don’t complete a task or give a wrong answer. Telling them that they’re doing something “totally wrong” is really inappropriate feedback, even if they are doing something “totally wrong.” Likewise, the use of sarcasm is typically inappropriate, especially if you’re not close friends with your user.

The results

Before concluding the usability test, you might want to tell them that the testing is over and ask for any other comments they might have. Also, I suggest providing them a little bit of feedback regarding what you learned from the test; users can find it satisfying to complete a usability test and be of assistance.

After the test, I always go back through the audio I recorded during the test and write up as many notes as possible about the test. I write my notes after the test for two reasons: first, I want to be focused on what the user is doing while they’re sitting in front of me; second, you’ll probably pick up on things you didn’t catch during the test.

After conducting a few usability tests, you’ll have a good feel for the kinds of questions you should ask and how to handle users throughout the test. I’m hoping that this gives you a good foundation for your first usability test!

Setting Up an Apache and PHP server on Slicehost with CentOS 5.4

Published on June 30, 2010 in Uncategorized. 0 Comments

I recently set up a new slice at Slicehost for serving Seller’s Market, Frugal Me, and California Bungalow. The following post describes what was required for setting up a new CentOS 5.4 slice for serving a few PHP websites with Apache.

First, I changed the DNS records at my registrar to point to Slicehost’s name servers. Then, I followed Slicehost’s article on creating DNS records.

Slicehost has a great intro to CentOS 5.4; their guide will show you how to securely set up your new slice.

To install Apache, I followed Slicehost’s guide to installing Apache on CentOS. Then, I followed their guide to setting up the virtual hosts (for the multiple domains I plan to run on a single slice); I diverged from their directory layout without any problems.

Earlier, I mentioned that I decided to use CentOS 5.4; this is because I wanted to run a newer version of PHP with as little hassle as possible. I used this guide to installing PHP 5.3 on CentOS 5.

After PHP was installed, I still needed a few application-specific items: Memcached, MCrypt, and MySQL. These were easy to install with the repository from the above article:

  • Memcached: sudo yum install –enablerepo=webtatic php-pecl-memcached
  • MCrypt: sudo yum install –enablerepo=webtatic php-mcrypt
  • MySQL: sudo yum install –enablerepo=webtatic php-mysql

And that’s it! Hopefully this post is a helpful guide in getting started with Slicehost. While I haven’t actually had any sites live with Slicehost yet, the experience has been great thus far and I’d recommend them to anyone looking for more advanced hosting. If you haven’t signed up with them yet, I’d appreciate your use of this referral url.

More on Using ETags and UUIDs for Internal Caching

Published on May 31, 2010 in Technology and Web Services. 0 Comments

A while back, I wrote about ETags and how they could be used within a web application for caching. Since then, I’ve had some time to work with using ETags and UUIDs in two applications—Iron Money and a yet-to-be-launched site.

Both of these sites use ETags and UUIDs for their resources; when a resource is created, it’s given a UUID and an ETag; when it’s updated, the ETag is changed. They also use Memcached for caching resources; when a resource is created, the Memcached key is the UUID and ETag; when the resource is updated, the resource is simply stored again. Memcached already throws out objects that haven’t been fetched recently, so the old resources eventually fall out of the cache.

When a resource is requested, both sites simply look up the ETag in the database and then check the cache to see if the resource is already stored. If it’s not, then they go through the regular process of fetching the resource from the database. This is particularly efficient because the database can easily have an index on the UUID and ETag, making it very cheap (less than a millisecond) to look up the most recent ETag before fetching from the cache.

For resources that are compromised of other resources (say, a list of accounts), the process is the same; the ETag for the main resource is fetched (the /accounts/ ETag), and Memcached stores a list of UUIDs for the resource (all of the account UUIDs). Then, each resource is fetched individually with the same process (get the ETag, check Memcached for the resource). This means that the resources are not stored multiple times in the cache, but the entire list of resources can still be cached.

Overall, this system works very well; most resources stay in cache and there are no concerns regarding ACID compliance. However, one issue that I have run into is with the aforementioned lists of resources. For small lists of resources, the system works very well; it takes about a millisecond to get the ETag for the list of resources, and then takes about a millisecond for each resource.

This, however, does not work well with very large lists of resources. Even with everything in cache, a millisecond for each resource in a list can take too long if there are 100 or more resources to fetch from the cache.

So what’s the solution? If you’re willing to trade memory for speed, then there’s a rather simply solution: simply store the ETags for each of the resources in a list. By storing the UUIDs and ETags for each resource in a list, you can avoid looking up each resource’s ETag, which will make everything faster.

Implementing Basic Text Search

Published on April 30, 2010 in Technology and Web Services. 0 Comments

I added text search to Iron Money in early March and had a few requirements: I wanted to implement the AND and OR operators, I wanted to support quotes for exact matches, I wanted to support a “not” operator (“-”), I didn’t want any stop words, and I needed to be able to search encrypted text. Here are some examples of queries I wanted to support:

  • a b [both a and b]
  • a or b [a or b]
  • “a b” [the string “a b”]
  • -a b [strings that contain b but not a]

I decided that implementing my own text search would be my best option with those requirements. I wasn’t able to find any good articles about implementing text search, thus I’ve decided to write up my thoughts here. I can’t guarantee that this is the best solution for you, but given the above contraints it was the best option for Iron Money.

The first thing I do is parse the string like a CSV with PHP’s str_getcsv(). str_getcsv() is a function for parsing CSV strings; I set the delimiter to the space character and leave the enclosure to the default ‘”‘. If you’re writing this in another language, any CSV parser should do the trick; just make sure it splits the search text by spaces and respects quote values.

After I get an array of strings with str_getcsv(), I run through that array and add it to a brand new array (we’ll call it $parts). As I run through the strings, I check to see if the string starts with ‘-”‘; this indicates that the next string in the array is going to be a NOT value. Once I get to the next string, I append the rest of the NOT value to the previous string that was added to the $parts array and continue with the rest of the array. We end up with an array of $parts that has an array of strings.

With $parts in hand, I check each string in $parts to find if any of the strings are the word “or”. If the string is “or”, then I know that the string before and after the “or” belong to that “or”; thus, both of them are added to a special $or_conditions array, and I remove the three strings from the $parts array.

At this point we have two arrays: $parts has all of our AND conditions, while $or_conditions has all of our OR conditions. My goal, however, is to have an array of all of the conditions that a string must meet; this includes values that it needs to contain, values that it should not contain, and a list of OR conditions which the string must meet. Thus, I create a $conditions array which will contain all of the conditions a string must meet to match the search.

We continue along by creating a new array ($condition) with two values: a $contains array and a $does_not_contain array. We run through all of the strings in $parts; remember, all of the strings in the $parts array are AND conditions. We check each string in $parts to see if it starts with the “-” character; if it does, we put the string in $does_not_contain; otherwise, we put the string in $contains. After running through all of the strings in $parts, we’ll end up with a single $condition array that we add to the $conditions array; it represents all of the AND conditions.

Now we move on to the $or_conditions array. For each of the $or_conditions, we’ll create a new $condition that has a $contains array, a $does_not_contain array, and a value called “operator” that indicates that this is an OR condition. We use the same process as before to modify the $condition array, and then add it to the $conditions array.

At this point in time, you have a $conditions array that has a list of conditions a string must meet to match the search. Each value of the $conditions array has a $contains and $does_not_contain array, and it might have an “operator” value to indicate if it’s an OR condition.

Now, we get all of the potential candidates to search through. In Iron Money’s case, we have an array of transactions that we need to sift through; if the “name” or “description” attribute matches the text search, then the candidate is returned in the search results.

To determine whether or not a value matches the search conditions, we run through the $conditions array that we created earlier. For each $condition, we check to see if the candidate strings match the $condition—if the strings have the $contains text and don’t have the $does_not_contain text. If the candidate is a match, we add it to the search results.

Manually implementing text search can be a real pain; I think it’s almost always better to use existing, proven solutions for text-matching needs. However, if you’re in a situation like I was with Iron Money, hopefully the above will be useful when implementing a robust text-matching algorithm.

More on ETags

Published on March 31, 2010 in Technology and Web Services. 0 Comments

In a previous post, I mentioned how including the ETag and Last-Modified headers in an API can be a real benefit to third-party clients. What I didn’t mention is how ETags can provide a large benefit inside your API as well. This post is about implementing ETags in your application and using them to make your application more efficient.

ETags, or entity tags, are identifiers for a resource. In short, they are similar to version identifiers for resources; when a resource changes, its ETag changes. When a client GETs a resource, they can store the associated ETag; then, the next time they GET the resource, they can ask for the resource only if it has changed; or, if they fancy, the client could even make a request that should only be executed if they have the latest ETag for a resource!

Strong and weak

One thing I didn’t mention in my original post is that there are two different kinds of ETags: strong and weak ETags. A strong ETag changes whenever a resource changes at all; if any bit in the resource changes, a new ETag is required. Weak ETags, on the other hand, change whenever the resource semantically changes; a resource won’t necessarily have a new ETag if it means the same thing as its previous version.

So how should you generate your ETags? Strong ETags would probably best be generated right after the message body is generated or if entire message bodies are stored by the API; alternatively, for a more effective use of ETags, you could regenerate them whenever the resource changes, although that might be an expensive solution. [In practice, what Iron Money does is create a hash from the data and then stores the hash with the data in MySQL. Your mileage may vary.]

Weak ETags, on the other hand, could be generated from the internal representation of resources in your API. Whenever the resource is changed, simply generate the weak ETag and store it along with the resource’s data.

If you provide a resource that lists a bunch of child resources (e.g. a /books/ resource that lists all of the book resources), I highly recommend creating an ETag for the resource from all of the ETags of the child resources; this way, you don’t need to generate the entire list when one of the child resources changes.

Generating ETags for resources that are searchable can be problematic. You could generate the list of child resource ETags and create the ETag from that; however, this requires you to perform the search even when the request is conditional. Another way of handling the problem is to use the same ETag for the search as you would use for the entire resource (e.g. the ETags for /books/ and /books/?author=Steinbeck would be the same). I recommend doing the latter; it saves you time and shouldn’t hinder clients’ use of your API.

Using ETags internally for caching

The benefits of ETags to third-party clients is rather obvious, but how can ETags be used within your application?

If you’re using a caching system (like Memcached), you’re probably storing your resources by their UUID or by some sort of resource and primary key identifier. Whenever a resource is created, you put it in the cache; whenever a resource is updated, you delete it from the cache or update the cache, and whenever a resource is deleted, you delete it from the cache.

This might work well for your application. However, cache invalidation can be difficult, especially if your application requires ACID capabilities.

ETags can help your application with both of these issues. If you store each resource by its primary identifier and its ETag, you can always be sure that each cache lookup will only return the version of the resource you want. For example, if you’re simply getting a resource, you can look up its ETag in your database, then retrieve the entire resource from the cache and be sure that, if it’s in the cache, then it’s the correct version that you want. Additionally, you don’t have to worry about cache invalidation, because there is no invalidation—you simply let your cache system remove the old versions of resources as the cache fills up.

ETags: because its good for the Internet

ETags are surprisingly powerful once you start to make the most of them. They help HTTP clients cache resources and make conditional requests, and they can help your application with its caching needs as well.

Iron Money Public Beta

Published on February 19, 2010 in Iron Money and Web Services. 2 Comments

I’ve been working on a personal finance web app called Iron Money for the past couple of years. In September 2008 I released it as a private beta; you could sign up and use the API, but to actually use the web app you’d need my approval. Last week, I made the Public Beta available for everyone to use—no special approval, just sign up and go.

This post is an in-depth look at the kind of decisions that went into making the current version of Iron Money.

Simplify

I focused on making this release as simple as possible. I wanted a simple, well-tested foundation for future versions of Iron Money; thus, I actually cut features from the private beta. I wasn’t happy about cutting some features: I think the undo/redo feature was great from a usability perspective and the budgeting feature was something that was very useful. By the end of September, however, I knew that if I was going to get the public beta out the door, I’d need to cut down on things for the initial release and focus on the features that were core to Iron Money’s purpose: keep users up to date on their finances.

The simplification theme extended to the features that were kept as well. For example, I changed how categories worked so that they were easier to use (Iron Money used to have four default categories, two of which could have children categories; now, it has three default categories, all of which can have children categories).

Everything has a UUID

One of the things that changed fairly early on was my move from using MySQL’s auto-incrementing primary keys as IDs to using UUIDs for IDs. The primary reason for this change was my desire to make sharding user’s data easy. With UUIDs, I don’t need a central table dictating the IDs for everything and I don’t need a complicated auto-increment scheme; instead, I can add as many shards as I want to as Iron Money’s user-base grows.

Everything has an ETag

Iron Money now keeps track of an ETag for every resource. In a future post I’ll talk more about how Etags are used by Iron Money, but creating an ETag for each resource allows Iron Money to support better caching through the API. Whenever something is added, edited, or deleted from Iron Money, at least one resource’s ETag is updated.

api.ironmoney.com

Iron Money now uses a new domain exclusively for the API. This was mainly brought on for security reasons: I didn’t want any cookies set on ironmoney.com to be available on api.ironmoney.com. Furthermore, I think it’ll make it easier to run the API on a separate server in the future.

OAuth permissions

Iron Money’s API now supports a permission system that is fairly flexible: instead of authorizing an application to access all of your Iron Money data, the application can limit itself to just what it needs to access. For example, an application can ask for read permission to your accounts if it wants to show you your latest balances, without requiring read or write access to anything else.

The permissions system is a win for both third-party applications and users. Users have a clearer understanding of exactly what they’re authorizing an application to do, while apps can prove that they are only reading your information (instead of making it just a trust issue).

Almost everything is cached

a href=”http://memcached.org/”>Memcached is an amazing caching system; if you’re not using it in your web app or API right now, you’re missing out on faster reads. Basically, whenever data is written to Iron Money, it updates its cache and almost every subsequent read is from memory.

Simple can be difficult

Rewriting Iron Money over the past few months has been a lot of work, but I think the changes above will pay off in the long run with a faster, easier to use Iron Money.

API First and Only Features

Published on January 22, 2010 in Technology and Web Services. 0 Comments

A few days ago, Kellan Elliott-McCrea asked: Anyone have thoughts/experiences with API first, or API only features?

Yes. I initially worked on the API for Iron Money while working on the iPhone app. While I never finished the iPhone app (it’s currently sitting in a Subversion repository while I work on Iron Money’s Public Beta), Iron Money’s API has had API-first and API-only features (and will continue to in future versions).

API-first

API-first features, or features that come to a web service’s API before making it to the web app, can be useful for “testing” new features. For features that can be thoroughly thought through, adding the feature to an API first can be an easy way of letting third-party developers start working with the feature and see what kind of issues and functionality should be added before adding the feature to the web app.

An example of an API-first feature in Iron Money’s private beta was the multi-transaction editing functionality. Editing multiple transactions at the same time was too-complex of a task to add into the initial interface, but adding it to the API was trivial; eventually, the web app “caught up” with the API with regard to this functionality.

API-only

API-only features, or features that are only exposed through an API (and not through the web app), are similar to API-first features; neither are exposed in the web app first. However, API-only features might serve two additional purposes: to provide advanced, potentially more complex functionality, and to make more things possible for third-party apps.

An example of an API-only feature in Iron Money is its notification functionality. It doesn’t make sense for a user to be able to write and send themselves a notification, but it does make sense to allow third-party developers to send their users a notification.

While a feature is API-only, I highly recommend making sure that it doesn’t break the web app (or any other apps for that matter). One way an API might break a web app is if the functionality in the API is more advanced than in the web app; the web app might need to support displaying what can be done through the API.

Let’s say, for example, you’re building a calendar API and web app. You might initially build the web app to support very simple event repetition (say, every day, week, month, and year). However, you might allow the API to do more complex repeats (say, every three days or every January of every other year).

What you want to avoid is having a user set up their events in another calendar app (which does support the API’s more advanced event repetition) and viewing it in your simplified web app. The web app should not break because the event was created through the API; your web app should still display the event correctly.

An API before a web app

There’s one more concept I’d like to discuss: building your API before building your web app. Brent Simmons mentioned this idea in a post about the iPhone App Store Gold Rush, in which he theorized that APIs and iPhone apps might be built together (instead of building the web app, API, and client apps in tandem).

As I mentioned earlier, I built Iron Money’s first public API while writing an iPhone app for it, all of which came before writing the web app. I would avoid doing this again because, as Erik F. Kastner brought up on Twitter, it can limit your ability to make the right thing. I’ve found that engineering the perfect solution ahead of time can result in suboptimal solutions—even if it looks really good in theory.

Here’s an example of this problem in action. In Iron Money’s private beta, transactions could be categorized into three different types of categories: Income, Spending, Transfer, and Uncategorized. Everything would go into Uncategorized by default so that users could have a quick overview of what still needed to be categorized. The Uncategorized category was a sensible default category for all transactions.

However, as I found out while writing the web app, this is an inefficient way of solving the problem of tracking a user’s money. Categorization, as a feature, is mainly useful for searching and reporting. For reporting things such as a person’s income and spending, the web app needed to figure out what was income and what was spending. For transactions in the Uncategorized category, it would guess that positive amounts were income and negative amounts were spending.

This guessing didn’t make things any easier on the web app or any other app built on top of the API; everyone would have to implement their own guessing algorithm. Furthermore, the default graphs for categories weren’t very helpful to users because everything was lumped together by default. At the end of the day, what seemed like the best idea while writing the API turned out to be a suboptimal decision.

I think that building an API as a foundation for your web app and client apps is a good idea; building an API with third-party applications in mind is also a good idea, even if you don’t expect to make it public in the near future. However, I don’t believe that making a brand new API available to the public is a good idea until you’ve had enough time to ensure that your API promotes the best experience for both your users and API consumers.