Designing Good API & Its Importance

Designing Good API and its importance Imran M Yousuf Entrepreneur Smart IT Engineering Ltd.

Outline
What is an API?
Why is API important?
Designing API
General Principles
OOP Design Principles
Smart IT Engineering Ltd.

What is an API?
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 with each other.
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

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?

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.
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.

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?

Imagine the following
FB JavaScript API is so difficult to use that you are not able to use them. What would you do?
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?
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?
What would be your opinion of such API providers?

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

API can cause a Company and its Developer both Glory and Gloom depending on its user experience
API can be among a company's greatest assets
Customers invest heavily: buy, write, learn
Cost to stop/change API can be prohibitive
Successfully Public APIs capture customers
Bad API causes unending support request and becoming a liability to the company

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
Good reusable modules are corporate assets
Thinking in terms of APIs improves code quality

Characteristics of a Good API
Easy to learn
Easy to use, even without documentation
Hard to misuse
Easy to read and maintain code that uses it
Sufficiently powerful to satisfy requirements
Easy to extend
Appropriate to audience

Designing API Smart IT Engineering Ltd.

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 of use-cases .
Can be easier and more rewarding to build something more general
Beware of the cost factor and target audience

Start with short spec
Start of all API should begin with writing a spec, preferably within 1 page
At the very beginning agility trumps completeness
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

Write it early & often
API comes before the implementation
API is the concept and should elaborate on behavior
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

Write an SPI
Service Providers Interface (SPI)
Plugin API enabling multiple implementations
It serves as an API used by API implementations
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.
If you write one, it probably won't support another
If you write two, it will support more with difficulty
If you write three, it will work fine

Maintain Realistic Expectation
Most API designs are over constrained
You won't be able to please everyone
Aim to displease everyone equally
Stick to what you want to achieve
Expect to make mistakes
Real world use will continuously flush out the mistakes
Expect to evolve API

General Principles Smart IT Engineering Ltd.

Should Do One Thing & Do It Well
Functionality should be easy to explain
If it's hard to name, it indicates rethink
Good names enables API to thrive
Be open to splitting and merging modules
Functionality should be well specified
Specify how the API should be used
Write tests demonstrating API usage
Specification will get more specific through usage

Keep it Small but No Smaller
API should satisfy its requirements
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

Implementation shouldn't impact API
Implementation details
Confuse users
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

Minimize Accessibility of Everything
Make classes and members as private as possible
Public class should have no public fields other than constants
This maximizes information hiding
Allows modules to be used, understood, built, tested and debugged independently

Names Matter – API is a Language
Names should be largely self-explanatory
Avoid cryptic abbreviations
Be consistent – Same word means same thing
Be regular – strive for symmetry
Code should read like prose

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 th International Conference on Software Engineering, 1994

Document Religiously
Document every class, interface, method, constructor, parameter and exception
Class: What an instance represents
Method: Contract between method and its client
Preconditions, postconditions, side-effects
Document state space very carefully

Performance Consequence
Bad decisions can limit performance
Do not wrap API to gain performance
Be aware of stateful vs stateless requirements

OOP Design Principles

Class Design
Minimize Mutability
Classes should be immutable
If mutable keep state space small, well-defined
Subclass only where it makes sense
Subclass only when is-a relationship exists
Prefer composition over inheritence
Bad example of inheritance is Properties of Java
Document for inheritance else prohibit it

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
Provide programmatic access to all data available in string form to avoid user parsing strings

Method Design
Overload with care
Avoid ambiguous overloadings. Preferable no two methods with same number of arguments
Just because you can doesn't mean you should
Use appropriate parameter and return types
Favor interface over classes for input
Use most specific possible input parameter type
Avoid using float (32 bits) in favor of double (64 bits)

Method Design
Use consistent parameter ordering across methods
Avoid long parameter list
Three or fewer parameters is ideal
Lon list of identically typed params is harmful
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.

Exception Design
Throw exceptions to indicate exceptional conditions
Don't force client to use exceptions for control flow
Conversely, don't fail silently
Favor unchecked exceptions
Checked – Client must take recovery action
Unchecked – Programming error
Include failure capture information in exceptions

Conclusion
API design is a notable and rewarding craft
This presentation covered some heuristics of the craft
API design is tough
Once a API is Public it can evolve but has to support earlier releases

Questions? Smart IT Engineering Ltd.

http://imyousuf-tech.blogs.smartitengineering.com	352
http://www.blogger.com	2
http://webcache.googleusercontent.com	1

Designing Good API & Its Importance

by imyousuf

Accessibility

Categories

Upload Details

Usage Rights

3 Embeds 355

Statistics

Designing Good API & Its Importance Presentation Transcript