Summary• What is an API?• Properties of an API• Guidelines for developing an API• API maintenance• C/C++ specific APIs• Anti-Patterns• Conclusion
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.
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
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
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"
Guidelines #2 - ExamplesisNotAvailable() vs isAvailable()isNull() vs isValid()getApples(), getRaisins() vs getFruit(Fruit_t )setValue1(), setValue2(), setValue3() vssetValue1(), applyValue2(), writeValue3()if(car.speed() > (2*SPEED_LIMIT)) generateAlert("Watch out for cops!")
Guidelines #3• Documentation o very important! o impacts reusability good design without documentation wont be reused o documented units: class: what the instance represents method/function: precondition, postcondition, side-effect parameter: meaning, ownership
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)
API Maintenance• Versioning• Documentation• Backward compatibility• Usability• Extensibility
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 wont be able to please everyone o Suggestion: aim to displease everyone equally
C/C++ Specific APIs• Design issues: o Who should allocate? o Type safety o Preprocessor usage o Debugging o Testability o Strings
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
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
Anti-patterns #2• Stringification (##)• Defining functions in public header files• Not using namespaces (non-C)• Writing non-cross-platform code in public header files
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.