SDK Design Considerations
API design principles
Following list summarizes some of the rules and laws which should be adhered to build a complete API for a SDK
1. Easy to learn
2. Make interfaces easy to use correctly and hard to use incorrectly.
Interface should not be misleading to use it incorrectly. You should define contracts preciously to avoid mistakes by the person who is using it.
3. Consistent API design
An interface that is predictable serves better than one which is locally optimal but inconsistent across the whole set.
4. It should be sufficiently powerful to satisfy the requirements, but should not be over complex.
5. Don’t try to please everyone by making the API generic.
6. Do not return resources that the caller is responsible for releasing.
Always try to encapsulate the resource releasing, cleaning and destructing logic.
7. Namespaces, Type names and function names should reflect the intended use.
8. Consider the API evolvement and extend over time.
Need to facilitate to effectively evolve an API to keep it relevant and useful over time, without having to throw it away and start over every 18 months.
Consider the coexistence with other versions when evolving
Other SDK requirements
1. SDK should be able to easily setup and configure(installation pack)
2. SDK should clearly define the development platforms which supported.
3. It should be able to maintain different versions and their coexistence.
4. SDK should contains following artifacts
a. Libraries
b. Documentation and tools utilizing the APIs
c. Samples
d. Licensing agreements
e. Source code(if open-source)
Development best practice
1. Code consistency using coding best practices, coding standards and basic frameworks
2. Unexpected behaviors need to be avoided.
3. Ensure graceful termination of unavoidable situations while providing proper information to the client.
4. SDK should be well tested before release.
5. Modularization should be done for reuse.
6. Access modifiers should be properly defined.
