I am a big fan of the SharePoint API and I was thrilled to see this MSDN article suggesting many great uses of the SharePoint API that you might not have thought about:
May 2008 MSDN magazine article on MOSS is a must read for SharePoint developers. It summarizes all the options, and also has a really innovative and I think great way to roll out changes to multiple environments and that is to “script” those changes using the SharePoint API in a console app, and run it in both dev, staging and production. SharePoint API requires just a few lines of code for most tasks and is easy to log, debug etc. You can do almost everything with the API: site navigation changes, webpart customizations, Web.config changes, create web app, create site, create list, create a publishing page from a layout. The one thing you can’t do with the API, is create site and list definitions.
Comments on Site Templates vs. Site Definitions:
Using Site Templates has performance costs as SharePoint stores the parent list definition on disk and all variances in the content DB. Also if you have data in your list, it is lost or has to be migrated to the new list that you create from the template. With Site Definitions you can make changes to multiple sites or lists without loosing data. The only good thing about Site Templates is they are very easy and require no coding.
There are list definitions and site definitions and this is the Microsoft recommended approach because you can roll these out as features and they perform well because they live on the Web Front End file system. And most importantly you can roll out changes to a list or site without losing the data in existing sites and lists. Good article on Creating custom site and list definitions. MS tool to make it easier. (Unfortunately this tool from Microsoft is not supported on VS 2008 until June, so you'll have to use VS 2005.)