How to define an api


Published on

  • Be the first to comment

  • Be the first to like this

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide

How to define an api

  1. 1. How to define an API Presenter Alexandru Chica
  2. 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. 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. 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. 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. 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. 7. 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!")
  8. 8. 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
  9. 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. 10. API Maintenance• Versioning• Documentation• Backward compatibility• Usability• Extensibility
  11. 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 wont be able to please everyone o Suggestion: aim to displease everyone equally
  12. 12. C/C++ Specific APIs• Design issues: o Who should allocate? o Type safety o Preprocessor usage o Debugging o Testability o Strings
  13. 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. 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. 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. 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. 17. References•• design/api-design.pdf