How to define an api
Download as PPTX, PDF3 likes4,946 views
This document discusses guidelines for developing application programming interfaces (APIs). It defines an API as an interface that allows software applications to communicate with each other. The document outlines properties an API should have like being easy to use and learn. It provides guidelines for APIs such as having a single responsibility, using proper naming conventions, adding documentation, and considering performance. It also discusses API maintenance, C/C++ specific issues, anti-patterns to avoid, and concludes that the best API is no API.
How to define an api
- 1. How to define an API Presenter Alexandru Chica
- 2. Summary • What is an API? • Properties of an API • Guidelines for developing an API • API maintenance • C/C++ specific APIs • Anti-Patterns • Conclusion
- 3. What is an API? • An API is the interface implemented by an application which allows other applications to communicate with it. • An application programming interface (API) is a specification intended to be used as an interface by software components to communicate with each other.
- 4. Properties of an API • Easy to learn • Easy to use • Hard to misuse • Easy to read and maintain • Easy to extend • Satisfies requirements • Designed for an audience
- 5. Guidelines #1 • An API should do one thing and do it well o Single responsibility principle • An API should be as simple as possible o should satisfy requirements o apply KISS (Keep It Simple Stupid) o should be open to extension and closed to modification • Implementation details should not leak into the API
- 6. Guidelines #2 • Minimize accessibility o Encapsulation • Proper naming o names should be self-explanatory o naming consistency o one goal should be symmetry o "code should read like prose"
- 7. Guidelines #2 - Examples isNotAvailable() vs isAvailable() isNull() vs isValid() getApples(), getRaisins() vs getFruit(Fruit_t ) setValue1(), setValue2(), setValue3() vs setValue1(), applyValue2(), writeValue3() if(car.speed() > (2*SPEED_LIMIT)) generateAlert("Watch out for cops!")
- 8. Guidelines #3 • Documentation o very important! o impacts reusability good design without documentation won't be reused o documented units: class: what the instance represents method/function: precondition, postcondition, side-effect parameter: meaning, ownership
- 9. Guidelines #4 • Performance o depends on the environment o how will the component be used? lots of calls/lots of clients few calls/few clients does it scale? vs does it need to scale? o concurrency o parallelism • Logical consistency (naming & behavior)
- 10. API Maintenance • Versioning • Documentation • Backward compatibility • Usability • Extensibility
- 11. API Maintenance • No API is perfect in the first shot • Expect to make mistakes o real-world usage will reveal design mistakes o expect to evolve the API • Rule of user opinions: if you have n users that use your API you will get n+1 suggestions to "improve" the API o Fact: you won't be able to please everyone o Suggestion: aim to displease everyone equally
- 12. C/C++ Specific APIs • Design issues: o Who should allocate? o Type safety o Preprocessor usage o Debugging o Testability o Strings
- 13. C/C++ Specific APIs • PIMPL • Changing private members does not require recompilation of class and dependencies • The header does not need to include dependant headers since objects are forward declared faster compile time
- 14. Anti-patterns #1 • Logical inconsistency o Some windows functions that return a HANDLE use NULL/0 for an error (CreateThread), some use INVALID_HANDLE_VALUE/-1 for an error (CreateFile). o pthread_cond_wait in the POSIX pthreads API, is actually an unconditional wait
- 15. Anti-patterns #2 • Stringification (##) • Defining functions in public header files • Not using namespaces (non-C) • Writing non-cross-platform code in public header files
- 16. Conclusion The best API is no API • The ideal features of an API are those that require no or very little code from the application developer.
- 17. References • http://lcsd05.cs.tamu.edu/slides/keynote.pdf • http://chaos.troll.no/~shausman/api- design/api-design.pdf