First Plugin

I am working on writing my first plugin and am confused about the nature of the db object in an add on and the db.new_api. I am writing a user interface plugin to merge books while maintaining all the formats and metadata from the merged book.

I have hacked it together and it works for my purpose, but it seems like in some commands I needed to use db and others db.new_api.

Is there a best practice on when to use one over the other?
Is on expected to be deprecated and we should move to the other?

Thanks
Joe