Information hiding and API Design  

Both Jon Udell: Hiding versus revealing and Phil Wainewright:Bring down the walls have been commenting on the amount of information that should be public in a URL.

URL's should be considered public API's - they are visible and usable by others therefore should be treated that just like any other public API. This does not mean that everything should be in the URL. A real world example of a bad URL design is as follows:

There is a certain Ivy League school that has worked very hard to put all its admissions onto the web. You are notified of your admission status by an e-mail that contains a link. Clicking on the link directs you to a web page (with a password prompt) that is a beautifully formatted letter with university logo and scanned signature of the university president. You are instructed to print out the letter as evidence of admission status. The only problem is that there is a URL parameter "status=x", and changing the status code among 0,1 and 2 and resubmitting the link changes the letter from accepted to rejected to wait listed.

This is obviously a poor design of a API and violates the basic principles of information hiding. the rules to designing a good URL is very similar those for designing a good API. Provide as much flexibility and robustness to the potential users as possible. If you do a good job you make the API evolvable; if you do a great job you will also generate unintended consequences. In either case like any other API that is used by others you need to provide a migration path among versions.

There should not be black and white rules about what should be in a URL. Rather it is about the quality and flexibility of the service that is provided through the URL. Great services will expose the right amount of unintended consequences and will evolve to even more interesting services.

posted by John McDowall | 8:36 PM