Developer Friendly API Design

API Design

Ferenc Mihaly
Senior Software Architect

November 9, 2011

Slide 1
Copyright © Open Text Corporation. All rights reserved.

Agenda

 Introduction: Why it matters?
 Consider the perspective of the caller
 Keep it simple
 Strive for consistency
 Choose memorable names
 Specify the behaviour
 Make it safe
 Anticipate evolution
 Write helpful documentation

Slide 2

Agenda

 Keep it simple
 Make it safe

Slide 3

Why it matters?

“Software artifacts that
cannot attract programmers
are not reused, and fade
into oblivion.”
Brian Foote

Slide 4

Why it matters?

“The impact of API design
choices on users sometimes
shows time penalties of a
factor of 3 to 10.”
Brad Myers

Slide 5

Why it matters?

“Public APIs, like
diamonds, are forever. You
have one chance to get it
right so give it your best .”
Joshua Bloch

Slide 6

Why it matters?

“A key lesson here is that API
is not just a documented class.
And, APIs don't just happen;
they are a big investment..”
Erich Gamma

Slide 7

Agenda

 Keep it simple
 Make it safe

Slide 8

Consider the perspective of the caller

 Implementation focus results in poor APIs:

class ContentInstance
java.lang.Object
extended by DataObject
extended by ManagedObject
extended by ExtensibleObject
extended by ContentItem
extended by ContentInstance

All Implemented Interfaces:
IAttributedObject, IChannelAssociate, IPersistable,
IRelatedAttribute, java.io.Serializable

Slide 9


 Implementation perspective
class Document {
String getTag();
boolean isTagged(String tag);
void remove(String tag);
void removeTag(String tag);
}

 Caller perspective
if(document.getTag().equals(“Best Practices”))

if(document.isTagged(“Best Practices”))

document.remove(“Best Practices”)

document.removeTag(“Best Practices”)

Slide 10


 Write client code first
 Write client code for all major use cases
 Ask yourself
 Is this code simple?
 Is this code intuitive?
 Is this code consistent?
 Is this code performant?
 Does this code reveal any implementation
details?

 Not a wasted effort
 Code samples reused in tests
 Code samples reused in documentation

Slide 11

Agenda

 Keep it simple
 Make it safe

Slide 12

Keep it simple

“Simplicity is the ultimate
sophistication”

Leonardo da Vinci

Slide 13

Keep it Simple

 Measuring Conceptual Complexity
try {
AuthenticationProvider20 provider = new LocalAuthenticationProvider19();
SearchCriteria18 criteria = new SearchCriteria17(EntityName16.USER15);
criteria.addPropertyToFetch14(PropertyName13.COMMON_NAME12);
criteria.addPropertyToFetch(PropertyName.PHONE11);
criteria.addPropertyToMatch10(PropertyName.DEPARTMENT9, "R&D");
criteria.addPropertyToMatch(PropertyName.LOCATION8, "Waterloo");
criteria.setSortProperty7(PropertyName.COMMON_NAME);
ProfileIterator6 iterator = provider.search5(criteria);
while(iterator.hasNext()4){
Profile3 profile = iterator.next()2;
Property1 commonName = profile.getProperty0(PropertyName.COMMON_NAME);
Property phone = profile.getProperty(PropertyName.PHONE);
System.out.println(commonName.getValue()-1, “ ”, phone.getValue());
}
}
catch(AuthenticationProviderException-2 e) {
}

 The higher score is better; less than zero means too complex!
Slide 14

Keep it simple

 Accidental complexity
 Avoid asking callers to extend classes
 Avoid asking callers to implement interfaces
 Avoid “Gang of Four” design patterns
 Provide alternate implementations
 Handle change requests carefully

 Essential complexity
 Organize large APIs into smaller parts
 Increase API granularity
 Give up some control
 Leave functionality out!

Slide 15

Agenda

 Keep it simple
 Make it safe

Slide 16

Strive for consistency

 Do the same thing the same way every
time
 Rules, patterns, and conventions makes
everyday life more predictable
 A consistent API has no frivolous or
unnecessary variations in it
int fscanf(FILE* stream, const char* format,...);
char* fgets(char* str, int num, FILE* stream);

 Consistent APIs are easy to
learn, remember and use

Slide 17

Strive for consistency

 Follow established conventions!
 C#: IPublishable, PublishDocument()

 Java: Publishable, publishDocument()

 Create your own conventions
 eliminate unnecessary variations
 parameter ordering, error handling, use of
null, etc.

 Enforce consistency with code reviews
 Use design patterns
 Business Service – Business Object

 Beware of false consistency
 Attributes getAttributes() throws RemoteException

Slide 18

Agenda

 Keep it simple
 Make it safe

Slide 19

Choose memorable names

 Avoid silly naming mistakes
 antiquated naming conventions
 spelling and grammar
 synonyms
 overly generic terms
 inaccurate terms
 meaningless terms

 Choose names first
 Design abstractions are difficult to name
– LLValue, DTree
– DocumentWrapperReferenceBuilderFactory
 Best names come from the problem domain
– Familiar, intuitive, accurate, memorable
 API as a domain-specific extension
– Establishing a domain vocabulary

Slide 20

Choose memorable names

 Survey problem domain for suitable names

 “In online computer systems terminology, a tag is a non-
hierarchical keyword or term assigned to a piece of
information (such as an internet bookmark, digital
image, or computer file). This kind of metadata helps
describe an item and allows it to be found again by
browsing or searching. Tags are generally chosen
informally and personally by the item's creator or by its
viewer, depending on the system.”

 Let names guide design

void assignTag(Item item, String tag);
Metadata describeItem(Item item);
Item[] searchByTag(String tag);

Slide 21

Agenda

 Keep it simple
 Make it safe

Slide 22

Specify the behavior

 Consider the class:
TeamsIdentifier
Uniquely identifies an Artesia entity.
Methods:
TeamsIdentifier(String id)

Constructs an identifier from a string.
java.lang.String asString()

Returns the id as a String.
TeamsIdentifier[] asTeamsIdArray()

Convenience method to return this id as an array.
boolean equals(java.lang.Object o)
boolean equalsId(TeamsIdentifier id)

Checks if two ids are equal.
java.lang.String getTeamsId()

Intended for hibernate use only.
java.lang.String toString()

Returns a string representation of the id.

Slide 23

Specify the behavior

 Try answering the questions:
Expression True or False
TeamsIdentifier id1 = new
TeamsIdentifier(“name”); ?
TeamsIdentifier id2 = new
TeamsIdentifier(“Name”);
id1.equals(id2)
id1.equalsId(id2); ?
id1.toString().equals(“name”) ?
id1.getTeamsId.equals(“name”) ?
TeamsIdentifier id = new
TeamsIdentifier(“a.b.c”) ?
id.asTeamsIdArray().length == 3
TeamsIdentifier id = new
TeamsIdentifier(“a:b:c”) ?
id.asTeamsIdArray().length == 3
AssetIdentifier assetId = new ?
AssetIdentifier(“Donald”)
UserIdentifier userId = new
UserIdentifier(“Donald”)
assetId.equals(userId)
assetId.equalsId(userId) ?

Slide 24

Agenda

 Keep it simple
 Make it safe

Slide 25

Make it safe

 Developers make mistakes
 Prevent access to dangerous code
 Keep implementation code private
 Prevent class extension
 Control class initialization

 Prevent data corruption
 Maximize compiler checks
 Avoid out and in-out parameters
 Check arguments at runtime
 Provide informative error messages
 Make method calls atomic
 Write thread-safe code
Slide 26

Make it safe
public Job {
private cancelling = false;
public void cancel() {
...
cancelling = true;
onCancel();
cancelling = false;
...
}
//Override this for custom cleanup when cancelling
protected void onCancel() {
}
public void execute() {
if(cancelling) throw
IllegalStateException(“Forbidden call to execute()
from onCancel()”);
...
}
}

Slide 27

Agenda

 Keep it simple
 Make it safe

Slide 28

Anticipate evolution

 Maintain binary backwards compatibility
 Clients work without an explicit upgrade
 Technology-dependent compatibility rules
– Implemented Java interfaces not extensible
– Java constant values hard-coded in client code
– C++ has more compatibility issues than C
– Adding field or method breaks C++, not Java
 Not the same as source-compatibility!

 Maintain functional backwards compatibility
 Allowed changes
– Weakening preconditions
– Strengthening postconditions
– Strengthening invariants
 Testing is essential
 SPIs evolve very differently from APIs
Slide 29

Anticipate evolution

 API versioning cannot be entirely avoided
 major technology innovations
 unanticipated requirements
 quality degradation over time
 Incompatible API = major API upgrade
 Planned, not accidental
 Significant new functionality
 Cleanup and reorganization
 Removal of deprecated constructs

 Old API remains unchanged
 must co-exist with the new API
 Must be supported for years
 often re-implemented as an Adaptor

Slide 30

Agenda

 Keep it simple
 Make it safe

Slide 31

Write helpful documentation

 FALSE: APIs are self documenting
 Behavior
 Design concepts and abstractions
 Design patterns and conventions
 TRUE: Nobody reads documentation
 Just-in-time learning preferred
 Documentation is referenced
 Information can be hard to find
 FALSE: Nobody uses documentation
 Adobe Flex Online, July, 2008
 24,293 programmers, 101,289 queries

 TRUE: Users don’t want documentation
 They want assistance (help)

Slide 32


 Typical question from an online forum

 Question: “With java.sql.ResultSet is there a
way to get a column's name as a String by
using the column's index? I had a look
through the API doc but I can't find anything.”

 Answer: “See ResultSetMetaData:
ResultSet rs =
stmt.executeQuery("SELECT a, b, c
FROM TABLE2");
ResultSetMetaData rsmd =
rs.getMetaData();
String name =
rsmd.getColumnName(1);”

Slide 33


 Think like a friend providing assistance
 Write short sections (10 minutes or less)
 Answer specific questions
 Make it easy to find

 Forms of API documentation
 Developer’s Guide (overview)
 Reference manual (details)
 Cookbook (usage scenarios, code snippets)
 Working code (test drive)
 Tutorial (optional)
 FAQ or Knowledge Base (ease of update)

Slide 34

Summary

1) Consider the perspective of the caller
2) Keep it simple
3) Strive for consistency
4) Choose memorable names
5) Specify the behaviour
6) Make it safe
7) Anticipate evolution
8) Write helpful documentation

Slide 35

Further reading:

The Amiable API
http://theamiableapi.com

Slide 36

Developer Friendly API Design

More Related Content

What's hot (19)

Viewers also liked (20)

Similar to Developer Friendly API Design (20)

Recently uploaded (20)

Developer Friendly API Design