Book Review: APIs: A Strategy Guide

Book Review: APIs: A Strategy Guide by Daniel Jacobson, Greg Brail, and Dan Woods: Publisher- O’Reilly: ISBN- 13: 978-1449308926

This is one of the first books on strategic part of API in software industry. APIs: A Strategy Guide is not for developers or designers but for non-technical folks of Software industry – PMs, Business Development staff, C Level Executives and anyone who is interested in Software marketing and Sales and its management.

Book is written in very lucid manner though in initial chapters same information and facts are repeated but still overall book maintains good flow.

Mix of Authors makes good combination. Provider of API related products and Services - Greg Brail, CTO Apigee , customer - Daniel Jacobson, Director of Engineering Netflix API and Researcher, Speaker, & Entrepreneur - Dan Woods.

Book is consisting of eleven chapters and each chapter takes a dive into API strategy and business. Neither a deep dive nor a shallow one.

Book is certainly a good read and going to be on my book shelf for long time.

Disclaimer: I did not get paid to review this book, and I do not stand to gain anything if you buy the book. I got this book as reviewer from publisher. I do not have any relationship with the author.

Further reading: A complementary book is REST API Design Rulebook by Mark Masse and RESTful Web Services Cookbook: Solutions for Improving Scalability and Simplicity by Subbu Allamaraju.

One can get more information about book and related topics from:

1. Book at Aamazon: http://www.amazon.com/APIs-Strategy-Guide-Daniel-Jacobson/dp/1449308929
2. Apigee: http://apigee.com/
3. Publisher: Orielly: http://shop.oreilly.com/product/0636920021223.do

Typical API Design Goals

1. Clear separation in Content and Transaction API
2. Call on URL must be separate for regular site and API site
3. API site must be divided into two – test and prod
4. API site must be clearly demarked - json, rest and soap (myapplication.com/api/json, myapplication.com /api/rest, myapplication.com /api/soap).
5. Throttling/Rate Limiting for API calls must consider following factors
a. Time of call
b. Number of records per call
c. Number of calls per second using a API key (free and well as paid)
d. Hits per method/function
e. Test or prod API site
f. Content and Transaction API
g. IP address
h. Geographic Location
i. Specific Key may have enhanced SLAs/priority
j. Developer or Enterprise Key
k. Class of Enterprise – Platinum, Gold, Silver
l. Class of developer – MahaGuru, Guru, GuruBhai
m. Read or Write Call
6. API vs normal site traffic prioritization
7. API response caching ( not now but as application grow this should be pluggable)
8. Provision of deprecation of API
9. Versioning of API
10. Full backward compatibility
11. SSL/TCL availability for critical data – password, payment, etc
12. The call from client may be synchronous but internally it must go to queue (logical) and the requests must be served as per throttling priority  Example sfdc custom or enterprise WSDL
13. The outward call from myApplication.com must go to queue (logical) and then served synchronously to client (myApplication.com will make synchronous call). Messages remaining in queue will die after certain amount of time. This time is not configurable by API users but by admins of myApplication.com.  Example salesforce outbound message
14. To access API each developer must register and must be given key which identifies him/her.
15. To access user (normal site user – API should supply user credentials in secure fashion – SSL). Usage of OAuth needs to be explored.
16. Developer Key will be deactivated if not used for certain period of time.
17. If certain key tries to break throttling. First give warning, then deactivate for certain period of time and then deactivate permanently. Three Strike rule.
18. Reporting
a. Track overall API performance
b. Track API performance for each operation
c. Track API performance by developer
d. Track API performance by specific developer customers
e. Track API performance by client IP
f. Report on API usage by individual developer
g. Report on API usage by developer group
h. Report on API usage by specific developer customers
i. Ability to generate reports in multiple (i.e., CSV, PDF and HMTL) formats
j. Ability to integrate with an existing enterprise reporting system
k. API throughput report
l. API routing failure report
m. API utilization report
n. API availability report
o. API usage report
p. API availability report
q. API methods report
r. API response times report
s. API backend latency report
19. Billing & Metering and API integration
a. Support for Developers account
b. Support for Developers’ customers
c. Ability to bill specific API feature/function

How to achieve Business Goals

1. Prepare API strategy which cater to developers in comprehensive fashion
a. Open API
b. Separation of Content & Transaction API
c. Major part of API should be free
d. Thorough but easy and efficient developer registration process
e. Developers should be able to showcase their work
f. Developer should be able to discuss and share issues/challenges (forum)
g. Comprehensive documentation (developers manual) – pdf book as well as Wiki
h. Over the time period 3rd party developers should be major contributor to API management.
i. Some mechanism like Java Bug Parade
j. Involve developers in documentation translation
k. Distribute small projects – tool specific like – SOAP UI, Sahi, etc
2. API must be marketed at/via
a. Company microsite at facebook, linkedin, twitter
b. API documentation – manual & presentations must be available at webapplication/platform, document repositories – scribd, slideshare, desi forums, etc
c. Sample applications must be available at mobile application development sites – android, iPhone, iPad, HTML5, etc
d. Sample application must be available at Webservices sites – java, c#, scala, .net, php, etc
e. API details must be available at programmableweb.com and other similar sites
f. Conduct competition for innovative, most traffic generated web application
g. Pay application developer if that application develop uses paid API and generate certain amount of traffic over a time period.
3. No differentiation on the basis of end product (developed by 3rd party) licensing regime.
4. Developer portal
a. Discussion forum
b. Documentation
c. Bug Parade
d. Gamification ( Badge, enhanced role in management of API, etc)
e. Facility to showcase developers’ work
f. Enterprise and individual accounts

API Business Goals

1. Develop mobile applications, MS office plugins etc
2. Spur the 3rd party application development which can drive traffic and hence usage of web application/platform
3. Use it as marketing tool for developers
4. Collect analytic to design future strategy for platform/web application
5. Data collection about developers which can be utilized in future.

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

Benefits of API Driven Design

• Saves development time in medium to long term
• Reduces errors and debugging time.
• Facilitates modular design.
• Provides a consistent development platform.

Why a Good API is difficult to Design

• Forces designer to anticipate future usage of code.
• Requirements are incomplete (may never be complete).
• Requires abstraction.
• Requires modularization of functional as well as non functional requirements
• Requires in-depth skills in programming and design.
• Loads initial investment in terms of money, time and intellect.

Software without API Design

• +ves

• Fast and easy to implement in small projects
• Can serve as a starting point for API design. Agile!
• No need to consider how code interfaces with other softwares.
• Relaxed resource requirement in terms of intellect
• Immediate results

• -ves

• Code has a limited (as opposed to general) functionality.
• Code might not be reusable.
• Code is evolution will be difficult so the functionality.

Characteristics of a Good API

• • Easy to learn
• • Easy to use, even without documentation
• • Hard to misuse
• • Expose only what is required
• • Easy to read and maintain code that uses it
• • Sufficiently powerful to satisfy requirements
• • Easy to extend
• • Appropriate to audience

General Principles

• API Should Be As Small As Possible But No Smaller
• Implementation Should Not Impact API
• Minimize Accessibility of Everything
• Names Matter–API is a Little Language
• Documentation Matters
• Document Religiously
• Consider Performance Consequences of API Design Decisions
• Effects of API Design Decisions on Performance are Real and Permanent
• API Must Coexist Peacefully with Platform

API Documentation Mistakes and How to Avoid Them

Treat API documentation as User Interface for developers who will develop and extend your application/product beyond your imagination. Good API documentation is first step of making your API popular.

Mistake #1: Developer doubles up as documentation writer
The Mistake and Misconception
Developer, the creator knows about the system the best, so she can write the best documentation. More over API documentation is targeted to developers’; they understand each other’s lingo and mindset.
The Truth
Certainly developer the creator knows the best but most of the time her sight is myopic due to limited understanding of whole system. Moreover developers are not got in natural language due to their engineering background (no offence to engineers and developers. I am a proud engineer and developer). And lastly, developers are too near to system. What is obvious to them may not be so simple and straight forward to a greenhorn or outsider.
The Solution
Get a good technical writer.

Mistake #2.: A typical technical writer writes the documentation
The Mistake and Misconception
A typical technical writer is good at writing about user interface which targets non technical users. API documentation writer should be skilled to explain from developers’ perspective.
The Truth
Sometimes you will find technical writers who have dabbled in programming. This is a big improvement to working with those who haven't, because they will at least have an understanding of the concepts of programming. But what they won't have is an understanding of how a commercial software developer thinks. How do developers get started learning something new? How do they use prototyping and architectural design? How do they debug their code?
The Solution
Get a technical writer who can code (certainly not on regular basis) or at least have done coding in past.

Mistake #3: Focusing on How and forgetting Why
The Mistake and Misconception
Most of the documentation put emphasis on How to use an API but ignore Why.
The Truth
Sometime this avoidance is purposefully but most of time this is due to lack of attention. Just remember that if documentation does not answer Why, they may end up using API in wrong way and API may become unpopular among developer community.
The Solution
With How, answer Why as well and explain under what scenario what to use, How, and Why.

Mistake #4: Not providing enough help for Getting Started
The Mistake, Misconception, and Truth
In most of API documentation, certain level of maturity of developer is assumed but never stated. This lead to lot of confusion and un-popularity of API..
The Solution
Provide multiple levels of documentation. One targeted to newbie and one at advanced developers. Also state the assumptions very clearly.
Provide simple tutorials and sample codes. Strive for sample applications which use the best practices of API.

Mistake #5: Sketchy sample code
The Mistake, Misconception and Truth
For a technical writer it is very tempting to be descriptive about API.
The Solution
Certainly descriptive text is important and helpful but just remembers that developers like to learn by doing not only by reading. Pair up Technical Writer and developer if needed to develop sample code and sample applications.
Sample code should consider:
1. Relevant information should be grouped together
2. Clarity is more important than efficiency
3. Simplicity is one of the most important factor
4. Completeness of code
5. Avoid unnecessary details ( for example use hardcoded values instead of parametrization)
6. Comment the code
7. Use sensible nomenclature

Book Review: Practical API Design: Confessions of a Java Framework Architect

Book Review: Practical API Design: Confessions of a Java Framework Architect by Jaroslav Tulach: Publisher- Apress: ISBN- 13: 978-1-4302-0973-7

Before start reading Practical API Design, I googled and not able to find much of stuff on API design. Only worth while to mention are discussion on Artima forum dated 2005 and a paper by Brian Ellis, Jeffrey Stylos, Brad Myers. Certainly Effective Java Joshua Bloch also discusses the topic. I was surprised and started reading the book.

Once I started the book I was hooked to it. This book is written clearly demarcated three parts: Theory, Design aspects and Advice characterized as Theory & Justification, Practical Design and daily Life.

As confessed by Tulach book covers only Java language specifics but still book is must read for non java professionals.

Book primarily focuses on few topics: Evolve-ability, Backward & forward compatibility, architecture by committee and lessons learnt from NetBeans API development.

The book is serious readers and those who like to read book with notebook and pencil. This book is not easy read which you can read during your lunch. It needs serious time and efforts to read and then grasps. It discusses various aspects of API design with respect to backward & forward compatibility, runtime behavior, testability, separation of API & SPI, mingling with other APIs (here certainly I recommend reads to look into Struts 2.x and Grails architecture, design and source, because these frameworks/API uses third party libraries extensively), interface vs. abstract classes etc.

Tulach has recommended not to rewrite because of breaking old loyal clients. Personally, I also subscribed to this line of thought but certainly Struts 2.x violets this line and still very successful. It has to be studied in details.

Though book is comprehensive but it has not covered few topics:

1. Effect of hard coding of SUID (static final long serialVersionUID =xx)
2. Performance
3. How to make API accessible from different programming languages (say C#)

Tulach is maintaining books web presence at http://www.apidesign.org, I hope he will take care of the different views and uncharted topics in future.

I am hoping for similar book by other veterans of industry both open source & proprietary frameworks and APIs (Eclipse, Spring, Hibernate, jUnit, Glassfish, Ant, Struts, Groovy on the Grails) as well as non Java frameworks and APIs (Ruby on the Rails , AspectDNG, Netron graph library, NAnt).

Practical API Design must be in your bookshelf if you are java architects veterans or aspiring one. It is also a good reference book for non java folks as principles discussed are very much applicable in other languages but must be tweaked to adjust with language specifics.

Disclaimer: I did not get paid to review this book, and I do not stand to gain anything if you buy the book. I have no relationship with the publisher or the author.

Further reading: A competing book is Effective Java by Joshua Bloch

One can get more information about book and related topics from:

1. Book’s web presence at http://apidesign.org
2. Purchase book at Amazon
3. Publisher -- Apress
4. Interview with Author
5. Review at 72 Miles
6. 90th Percentile Blog
7. The Factory Pattern in API Design: A Usability Evaluation by Brian Ellis, Jeffrey Stylos, Brad Myers
8. Discussion on API Design
9. Java Language Specification, Chapter 13: Binary Compatibility