1. Designing Good APIandits importance Imran M Yousuf Entrepreneur Smart IT Engineering Ltd.

2. Outline

What is an API?

3. Why is API important? 4. Designing API 5. General Principles 6. OOP Design Principles Smart IT Engineering Ltd. 7. What is an API?

APIstands for Application Programming Interface

8. API is a source code-basedspecification intended to be used as an interface bysoftware components to communicatewith each other. 9. ABI (Application Binary Interface) differs to API in that the former is specified on binary interface 10. In this presentation we will consider ABI as API too Smart IT Engineering Ltd. 11. Why is API important?

What do we Software Engineers develop? How do others interact with our software?

12. Do we integrate Facebook API (FB Login, Like, Share, etc.)? How? 13. How do we develop softwares that require system level integration? 14. How do Web 2.0 portals communicate with its server? 15. How do Smart Phone / Tablet Apps communicate with server? Smart IT Engineering Ltd. 16. Why is API important?

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. A lot of (Almost all) websites integrate with FB using its JavaScript API 18. For Windows we use MFC or Windows API; for *nix system we use POSIX etc. 19. Web 2.0 / Smart Phone / Tablet Apps make server side calls via HTTP protocol either from a App or from browser using AJAX. Smart IT Engineering Ltd. 20. Why is API important?

All of this signifies -Software components communicate with each other So either we aredeveloping and using APIeveryday. That is not enough for getting our attention?

Smart IT Engineering Ltd. 21. Why is API important?

Imagine the following

FB JavaScript API is so difficult to use that you are not able to use them. What would you do?

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. 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. What would be your opinion of such API providers? Smart IT Engineering Ltd. 25. Why is API important?

Contact FB and ask them how to use it

26. Contact Andoid community mailing lists/forums and ask there 27. Contact iPhone Developer Community and ask there 28. Ask my customer to get me documentation or ask the company/developer for help 29. We think those companies and their developers are crap and we are better than them Smart IT Engineering Ltd. 30. Why is API important?

API can cause a Company and its Developer both Glory and Gloom depending on its user experience

31. API can be among a company's greatest assets

Customers invest heavily: buy, write, learn

32. Cost to stop/change API can be prohibitive 33. Successfully Public APIs capture customers Bad API causes unending support request and becoming a liability to the company Smart IT Engineering Ltd. 34. Why is API important?

If you code, you are an API designer

Good code is modular each module has an API

Useful modules tend to get reused

Once module has users, can't change API at will

35. Good reusable modules are corporate assets Thinking in terms of APIs improves code quality Smart IT Engineering Ltd. 36. Characteristics of a Good API

Easy to learn

37. Easy to use, even without documentation 38. Hard to misuse 39. Easy to read and maintain code that uses it 40. Sufficiently powerful to satisfy requirements 41. Easy to extend 42. Appropriate to audience Smart IT Engineering Ltd. 43. Designing API Smart IT Engineering Ltd. 44. Gather Requirements

We usually get a project to work in the form of a solution

We should keep in mind better solutions may exist

We must extract true requirements in form ofuse-cases . 45. Can be easier and more rewarding to build something more general

Beware of the cost factor and target audience

Smart IT Engineering Ltd. 46. Start with short spec

Start of all API should begin with writing a spec, preferably within 1 page

47. At the very beginning agility trumps completeness 48. Bounce spec off as many head as possible

Listen to their input seriously

Once confidence is there that we understand what it is grow the spec

This growing could involve coding, e.g., prototypes

Smart IT Engineering Ltd. 49. Write it early & often

API comes before the implementation

API is the concept and should elaborate on behavior

50. Thus saving implementing something that is not useful API code helps you show the spec itself

Saves time in writing documents that is useless

Continue writing to API Smart IT Engineering Ltd. 51. Write an SPI

Service Providers Interface (SPI)

Plugin API enabling multiple implementations

52. It serves as an API used by API implementations 53. For example, Data Access Layer implementations Write multiple SPI implementations before release

If its a target that we want to support multiple implementations then we should implement at least a couple of them.

54. If you write one, it probably won't support another 55. If you write two, it will support more with difficulty 56. If you write three, it will work fine Smart IT Engineering Ltd. 57. Maintain Realistic Expectation

Most API designs are over constrained

You won't be able to please everyone

58. Aim to displease everyone equally 59. Stick to what you want to achieve Expect to make mistakes

Real world use will continuously flush out the mistakes

60. Expect to evolve API Smart IT Engineering Ltd. 61. General Principles Smart IT Engineering Ltd. 62. Should Do One Thing & Do It Well

Functionality should be easy to explain

If it's hard to name, it indicates rethink

63. Good names enables API to thrive 64. Be open to splitting and merging modules Functionality should be well specified

Specify how the API should be used

65. Write tests demonstrating API usage 66. Specification will get more specific through usage Smart IT Engineering Ltd. 67. Keep it Small but No Smaller

API should satisfy its requirements

68. When in doubt leave it out

API extended but not curtailed once it is public

Conceptual weight more important than bulk

Decrease the conceptual weight, i.e. things to learn new

Look for a power-to-weight ratio

Do more by reusing interfaces, i.e. add implementations targeted at solving different problems

Smart IT Engineering Ltd. 69. Implementation shouldn't impact API

Implementation details

Confuse users

70. Inhibit freedom to change implementation Be aware of what is an implementation detail

Do not over specify the behavior, e.g., hash functions

Don't let implementation details leak into API

On-disk and on-the-wire formats, exceptions

Smart IT Engineering Ltd. 71. Minimize Accessibility of Everything

Make classes and members as private as possible

72. Public class should have no public fields other than constants 73. This maximizes information hiding 74. Allows modules to be used, understood, built, tested and debugged independently Smart IT Engineering Ltd. 75. Names Matter API is a Language

Names should be largely self-explanatory

Avoid cryptic abbreviations

Be consistent Same word means same thing 76. Be regular strive for symmetry 77. Code should read like prose Smart IT Engineering Ltd. 78. Documentation Matters

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

• • - D. L. Parnas, Software Aging. Proceedings of 16 thInternational Conference on Software Engineering, 1994

Smart IT Engineering Ltd. 79. Document Religiously

Document every class, interface, method, constructor, parameter and exception

Class: What an instance represents

80. Method: Contract between method and its client

Preconditions, postconditions, side-effects

Document state space very carefully Smart IT Engineering Ltd. 81. Performance Consequence

Bad decisions can limit performance

82. Do not wrap API to gain performance 83. Be aware of stateful vs stateless requirements Smart IT Engineering Ltd. 84.

OOP Design Principles

Smart IT Engineering Ltd. 85. Class Design

Minimize Mutability

Classes should be immutable

86. If mutable keep state space small, well-defined Subclass only where it makes sense

Subclass only when is-a relationship exists

87. Prefer composition over inheritence 88. Bad example of inheritance is Properties of Java Document for inheritance else prohibit it Smart IT Engineering Ltd. 89. Method Design

Reduce need for boilerplate code

Generally done via cut/copy-and-paste

Don't violate the principle of least astonishment

User of API should not be surprised by behavior

Fail Fast report errors as soon as possible 90. Provide programmatic access to all data available in string form to avoid user parsing strings Smart IT Engineering Ltd. 91. Method Design

Overload with care

Avoid ambiguous overloadings. Preferable no two methods with same number of arguments

92. Just because you can doesn't mean you should Use appropriate parameter and return types

Favor interface over classes for input

93. Use most specific possible input parameter type 94. Avoid using float (32 bits) in favor of double (64 bits) Smart IT Engineering Ltd. 95. Method Design

Use consistent parameter ordering across methods

96. Avoid long parameter list

Three or fewer parameters is ideal

97. Lon list of identically typed params is harmful 98. Break up methods or create helper class to hold parameters Avoid return values that demand exceptional processing

Return zero-length array or empty collection instead of null.

Smart IT Engineering Ltd. 99. Exception Design

Throw exceptions to indicate exceptional conditions

Don't force client to use exceptions for control flow

100. Conversely, don't fail silently Favor unchecked exceptions

Checked Client must take recovery action

101. Unchecked Programming error Include failure capture information in exceptions Smart IT Engineering Ltd. 102. Conclusion

API design is a notable and rewarding craft

103. This presentation covered some heuristics of the craft 104. API design is tough 105. Once a API is Public it can evolve but has to support earlier releases Smart IT Engineering Ltd. 106. Questions? Smart IT Engineering Ltd.