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.

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