How to define an 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 anAPI? • 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 anAPI • 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