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.
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)
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.