Writing an api is hard there’s no doubt, ACM have a good article with some best practice rules to follow.
It’s always hard building one and deciding who your target audience is. Obviously once you’ve built in the problem is deciding when to stop refactoring and polishing it 
I wrote a while ago about JSR-296. Well, John O’Connor has put up a new article on using it Using the Swing App Framework and provides a real example showing the lifecycle, session management, resource bundles and how a project gets organised. There’s even a demo app to keep you going…