API Design

Useful Links

• Design tips for Library APIs
• Best Practices for Code documentation -Java Doc Style Guide
• Golden Rules of Code Documentation
• Google Talk: How To Design A Good API and Why it Matters

Versioning:

Use Semantic Versioning

The golden rules here are to use an [X].[Y].[Z] versioning scheme that can be summarised as follows:

• If a patch release includes bugfixes, performance improvements and API-irrelevant new features, [Z] is incremented by one.
• If a minor release includes backwards-compatible, API-relevant new features, [Y] is incremented by one and [Z] is reset to zero.
• If a major release includes backwards-incompatible, API-relevant new features, [X] is incremented by one and [Y], [Z] are reset to zero.