0
Designing Good API  and  its importance Imran M Yousuf Entrepreneur Smart IT Engineering Ltd.
Outline <ul><li>What is an API?
Why is API important?
Designing API
General Principles
OOP Design Principles </li></ul>Smart IT Engineering Ltd.
What is an API? <ul><li>API  stands for –  Application Programming Interface
API is a source code-based  specification   intended to be used as an interface by  software components to communicate  wi...
ABI (Application Binary Interface) differs to API in that the former is specified on binary interface
In this presentation we will consider ABI as API too </li></ul>Smart IT Engineering Ltd.
Why is API important? <ul><li>What do we Software Engineers develop? How do others interact with our software?
Do we integrate Facebook API (FB Login, Like, Share, etc.)? How?
How do we develop softwares that require system level integration?
How do Web 2.0 portals communicate with its server?
How do Smart Phone / Tablet Apps communicate with server? </li></ul>Smart IT Engineering Ltd.
Why is API important? <ul><li>We, software engineers, develop softwares which users use through UI, write plugins for, use...
A lot of (Almost all) websites integrate with FB using its JavaScript API
For Windows we use MFC or Windows API; for *nix system we use POSIX etc.
Web 2.0 / Smart Phone / Tablet Apps make server side calls via HTTP protocol either from a App or from browser using AJAX....
Why is API important? <ul>All of this signifies -  “Software components communicate with each other” So either we are  dev...
Why is API important? <ul><li>Imagine the following </li><ul><li>FB JavaScript API is so difficult to use that you are not...
You are developing an Android or iPhone App and having problem using their API as you not understanding how to simply achi...
Your client asked you to use a Web Service to integrate one service to another and the Web Service makes no sense what so ...
What would be your opinion of such API providers? </li></ul></ul>Smart IT Engineering Ltd.
Why is API important? <ul><li>Contact FB and ask them how to use it
Contact Andoid community mailing lists/forums and ask there
Contact iPhone Developer Community and ask there
Ask my customer to get me documentation or ask the company/developer for help
We think those companies and their developers are crap and we are better than them </li></ul>Smart IT Engineering Ltd.
Why is API important? <ul><li>API can cause a Company and its Developer both Glory and Gloom depending on its user experie...
API can be among a company's greatest assets </li><ul><li>Customers invest heavily: buy, write, learn
Cost to stop/change API can be prohibitive
Successfully Public APIs capture customers </li></ul><li>Bad API causes unending support request and becoming a liability ...
Why is API important? <ul><li>If you code, you are an API designer </li><ul><li>Good code is modular – each module has an ...
Upcoming SlideShare
Loading in...5
×

Designing Good API & Its Importance

2,582

Published on

This is a presentation inspired (heavily) by that of Joshu Bloch's presentation on "How to design a good API and its importance". I tried to simplify on API importance and tried to generify how to conceive it. No point referring to that presentation explicitly as I am mentioning it here and mentioned it at the start and end of the presentation as I made it in BASIS SoftExpo 2012

Published in: Technology
0 Comments
1 Like
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total Views
2,582
On Slideshare
0
From Embeds
0
Number of Embeds
2
Actions
Shares
0
Downloads
51
Comments
0
Likes
1
Embeds 0
No embeds

No notes for slide

Transcript of "Designing Good API & Its Importance"

  1. 1. Designing Good API and its importance Imran M Yousuf Entrepreneur Smart IT Engineering Ltd.
  2. 2. Outline <ul><li>What is an API?
  3. 3. Why is API important?
  4. 4. Designing API
  5. 5. General Principles
  6. 6. OOP Design Principles </li></ul>Smart IT Engineering Ltd.
  7. 7. What is an API? <ul><li>API stands for – Application Programming Interface
  8. 8. API is a source code-based specification intended to be used as an interface by software components to communicate with each other.
  9. 9. ABI (Application Binary Interface) differs to API in that the former is specified on binary interface
  10. 10. In this presentation we will consider ABI as API too </li></ul>Smart IT Engineering Ltd.
  11. 11. Why is API important? <ul><li>What do we Software Engineers develop? How do others interact with our software?
  12. 12. Do we integrate Facebook API (FB Login, Like, Share, etc.)? How?
  13. 13. How do we develop softwares that require system level integration?
  14. 14. How do Web 2.0 portals communicate with its server?
  15. 15. How do Smart Phone / Tablet Apps communicate with server? </li></ul>Smart IT Engineering Ltd.
  16. 16. Why is API important? <ul><li>We, software engineers, develop softwares which users use through UI, write plugins for, use as a library and/or use by executing and working with the output of the software.
  17. 17. A lot of (Almost all) websites integrate with FB using its JavaScript API
  18. 18. For Windows we use MFC or Windows API; for *nix system we use POSIX etc.
  19. 19. Web 2.0 / Smart Phone / Tablet Apps make server side calls via HTTP protocol either from a App or from browser using AJAX. </li></ul>Smart IT Engineering Ltd.
  20. 20. Why is API important? <ul>All of this signifies - “Software components communicate with each other” So either we are developing and using API everyday. That is not enough for getting our attention? </ul>Smart IT Engineering Ltd.
  21. 21. Why is API important? <ul><li>Imagine the following </li><ul><li>FB JavaScript API is so difficult to use that you are not able to use them. What would you do?
  22. 22. You are developing an Android or iPhone App and having problem using their API as you not understanding how to simply achieve them. What would you do?
  23. 23. Your client asked you to use a Web Service to integrate one service to another and the Web Service makes no sense what so over and furthermore, it does not have ample documentation. What would you do?
  24. 24. What would be your opinion of such API providers? </li></ul></ul>Smart IT Engineering Ltd.
  25. 25. Why is API important? <ul><li>Contact FB and ask them how to use it
  26. 26. Contact Andoid community mailing lists/forums and ask there
  27. 27. Contact iPhone Developer Community and ask there
  28. 28. Ask my customer to get me documentation or ask the company/developer for help
  29. 29. We think those companies and their developers are crap and we are better than them </li></ul>Smart IT Engineering Ltd.
  30. 30. Why is API important? <ul><li>API can cause a Company and its Developer both Glory and Gloom depending on its user experience
  31. 31. API can be among a company's greatest assets </li><ul><li>Customers invest heavily: buy, write, learn
  32. 32. Cost to stop/change API can be prohibitive
  33. 33. Successfully Public APIs capture customers </li></ul><li>Bad API causes unending support request and becoming a liability to the company </li></ul>Smart IT Engineering Ltd.
  34. 34. Why is API important? <ul><li>If you code, you are an API designer </li><ul><li>Good code is modular – each module has an API </li></ul><li>Useful modules tend to get reused </li><ul><li>Once module has users, can't change API at will
  35. 35. Good reusable modules are corporate assets </li></ul><li>Thinking in terms of APIs improves code quality </li></ul>Smart IT Engineering Ltd.
  36. 36. Characteristics of a Good API <ul><li>Easy to learn
  37. 37. Easy to use, even without documentation
  38. 38. Hard to misuse
  39. 39. Easy to read and maintain code that uses it
  40. 40. Sufficiently powerful to satisfy requirements
  41. 41. Easy to extend
  42. 42. Appropriate to audience </li></ul>Smart IT Engineering Ltd.
  43. 43. Designing API Smart IT Engineering Ltd.
  44. 44. Gather Requirements <ul><li>We usually get a project to work in the form of a solution </li><ul><li>We should keep in mind better solutions may exist </li></ul><li>We must extract true requirements in form of use-cases .
  45. 45. Can be easier and more rewarding to build something more general </li><ul><li>Beware of the cost factor and target audience </li></ul></ul>Smart IT Engineering Ltd.
  46. 46. Start with short spec <ul><li>Start of all API should begin with writing a spec, preferably within 1 page
  47. 47. At the very beginning agility trumps completeness
  48. 48. Bounce spec off as many “head” as possible </li><ul><li>Listen to their input seriously </li></ul><li>Once confidence is there that we understand what it is grow the spec </li><ul><li>This growing could involve coding, e.g., prototypes </li></ul></ul>Smart IT Engineering Ltd.
  49. 49. Write it early & often <ul><li>API comes before the implementation </li><ul><li>API is the concept and should elaborate on behavior
  50. 50. Thus saving implementing something that is not useful </li></ul><li>API code helps you show the spec itself </li><ul><li>Saves time in writing documents that is useless </li></ul><li>Continue writing to API </li></ul>Smart IT Engineering Ltd.
  51. 51. Write an SPI <ul><li>Service Providers Interface (SPI) </li><ul><li>Plugin API enabling multiple implementations
  52. 52. It serves as an API used by API implementations
  53. 53. For example, Data Access Layer implementations </li></ul><li>Write multiple SPI implementations before release </li><ul><li>If its a target that we want to support multiple implementations then we should implement at least a couple of them.
  54. 54. If you write one, it probably won't support another
  55. 55. If you write two, it will support more with difficulty
  56. 56. If you write three, it will work fine </li></ul></ul>Smart IT Engineering Ltd.
  57. 57. Maintain Realistic Expectation <ul><li>Most API designs are over constrained </li><ul><li>You won't be able to please everyone
  58. 58. Aim to displease everyone equally
  59. 59. Stick to what you want to achieve </li></ul><li>Expect to make mistakes </li><ul><li>Real world use will continuously flush out the mistakes
  60. 60. Expect to evolve API </li></ul></ul>Smart IT Engineering Ltd.
  61. 61. General Principles Smart IT Engineering Ltd.
  62. 62. Should Do One Thing & Do It Well <ul><li>Functionality should be easy to explain </li><ul><li>If it's hard to name, it indicates rethink
  63. 63. Good names enables API to thrive
  64. 64. Be open to splitting and merging modules </li></ul><li>Functionality should be well specified </li><ul><li>Specify how the API should be used
  65. 65. Write tests demonstrating API usage
  66. 66. Specification will get more specific through usage </li></ul></ul>Smart IT Engineering Ltd.
  67. 67. Keep it Small but No Smaller <ul><li>API should satisfy its requirements
  68. 68. When in doubt leave it out </li><ul><li>API extended but not curtailed once it is public </li></ul><li>Conceptual weight more important than bulk </li><ul><li>Decrease the conceptual weight, i.e. things to learn new </li></ul><li>Look for a power-to-weight ratio </li><ul><li>Do more by reusing interfaces, i.e. add implementations targeted at solving different problems </li></ul></ul>Smart IT Engineering Ltd.
  69. 69. Implementation shouldn't impact API <ul><li>Implementation details </li><ul><li>Confuse users
  70. 70. Inhibit freedom to change implementation </li></ul><li>Be aware of what is an implementation detail </li><ul><li>Do not over specify the behavior, e.g., hash functions </li></ul><li>Don't let implementation details “leak” into API </li><ul><li>On-disk and on-the-wire formats, exceptions </li></ul></ul>Smart IT Engineering Ltd.
  71. 71. Minimize Accessibility of Everything <ul><li>Make classes and members as private as possible
  72. 72. Public class should have no public fields other than constants
  73. 73. This maximizes information hiding
  74. 74. Allows modules to be used, understood, built, tested and debugged independently </li></ul>Smart IT Engineering Ltd.
  75. 75. Names Matter – API is a Language <ul><li>Names should be largely self-explanatory </li><ul><li>Avoid cryptic abbreviations </li></ul><li>Be consistent – Same word means same thing
  76. 76. Be regular – strive for symmetry
  77. 77. Code should read like prose </li></ul>Smart IT Engineering Ltd.
  78. 78. Documentation Matters <ul>Reuse is something that is far easier to say then to do. Doing it requires both good design and very good documentation. Even when we see good deign, which is still infrequently, we won't see the components reused without good documentation <ul><ul><li>- D. L. Parnas, Software Aging. Proceedings of 16 th International Conference on Software Engineering, 1994 </li></ul></ul></ul>Smart IT Engineering Ltd.
  79. 79. Document Religiously <ul><li>Document every class, interface, method, constructor, parameter and exception </li><ul><li>Class: What an instance represents
  80. 80. Method: Contract between method and its client </li><ul><li>Preconditions, postconditions, side-effects </li></ul></ul><li>Document state space very carefully </li></ul>Smart IT Engineering Ltd.
  81. 81. Performance Consequence <ul><li>Bad decisions can limit performance
  82. 82. Do not wrap API to gain performance
  83. 83. Be aware of stateful vs stateless requirements </li></ul>Smart IT Engineering Ltd.
  84. 84. <ul>OOP Design Principles </ul>Smart IT Engineering Ltd.
  85. 85. Class Design <ul><li>Minimize Mutability </li><ul><li>Classes should be immutable
  86. 86. If mutable keep state space small, well-defined </li></ul><li>Subclass only where it makes sense </li><ul><li>Subclass only when is-a relationship exists
  87. 87. Prefer composition over inheritence
  88. 88. Bad example of inheritance is Properties of Java </li></ul><li>Document for inheritance else prohibit it </li></ul>Smart IT Engineering Ltd.
  89. 89. Method Design <ul><li>Reduce need for boilerplate code </li><ul><li>Generally done via cut/copy-and-paste </li></ul><li>Don't violate the principle of least astonishment </li><ul><li>User of API should not be surprised by behavior </li></ul><li>Fail Fast – report errors as soon as possible
  90. 90. Provide programmatic access to all data available in string form to avoid user parsing strings </li></ul>Smart IT Engineering Ltd.
  91. 91. Method Design <ul><li>Overload with care </li><ul><li>Avoid ambiguous overloadings. Preferable no two methods with same number of arguments
  92. 92. Just because you can doesn't mean you should </li></ul><li>Use appropriate parameter and return types </li><ul><li>Favor interface over classes for input
  93. 93. Use most specific possible input parameter type
  94. 94. Avoid using float (32 bits) in favor of double (64 bits) </li></ul></ul>Smart IT Engineering Ltd.
  95. 95. Method Design <ul><li>Use consistent parameter ordering across methods
  96. 96. Avoid long parameter list </li><ul><li>Three or fewer parameters is ideal
  97. 97. Lon list of identically typed params is harmful
  98. 98. Break up methods or create helper class to hold parameters </li></ul><li>Avoid return values that demand exceptional processing </li><ul><li>Return zero-length array or empty collection instead of null. </li></ul></ul>Smart IT Engineering Ltd.
  99. 99. Exception Design <ul><li>Throw exceptions to indicate exceptional conditions </li><ul><li>Don't force client to use exceptions for control flow
  100. 100. Conversely, don't fail silently </li></ul><li>Favor unchecked exceptions </li><ul><li>Checked – Client must take recovery action
  101. 101. Unchecked – Programming error </li></ul><li>Include failure capture information in exceptions </li></ul>Smart IT Engineering Ltd.
  102. 102. Conclusion <ul><li>API design is a notable and rewarding craft
  103. 103. This presentation covered some heuristics of the craft
  104. 104. API design is tough
  105. 105. Once a API is Public it can evolve but has to support earlier releases </li></ul>Smart IT Engineering Ltd.
  106. 106. Questions? Smart IT Engineering Ltd.
  1. A particular slide catching your eye?

    Clipping is a handy way to collect important slides you want to go back to later.

×