Let's make a contract: The art of designing a Java API | DevNation Tech Talk

Let's make a contract:
the art of designing a
Java API
by Mario Fusco
mario.fusco@gmail.com
@mariofusco

An API is what a
developer uses to
achieve some task
What is an API?

What is an API?
An API is a contract between
its implementors and its users

And why should I care?
We are all API designers
Our software doesn't work in
isolation, but becomes
useful only when it interacts
with other software written
by other developers

Basic Principles
●
Intuitive
●
Understandable
●
Learnable
●
Discoverable
●
Consistent
●
Self-defensive
●
Concise
●
Easy to use
●
Minimal
●
Orthogonal
●
Idiomatic
●
Flexible
●
Evolvable
●
Well documented
●
Right level of abstraction
●
Correct use of the type system
●
Limited number of entry-points
●
Respect the principle of least astonishment

Best Practices
&
Practical Hints

Convenience methods
Use overloading judiciously
and sparingly

Convenience methods
and sparingly
Primitives often cause
methods proliferation
{

Convenience methods
and sparingly
Are these all
necessary?
Primitives often cause
methods proliferation
{

Convenience methods
public interface StockOrder {
void sell(String symbol, double price, int quantity);
void buy(String symbol, int quantity, double price);
void buy(String symbol, int quantity, double price, double commission);
void buy(String symbol, int quantity, double minPrice, double maxPrice, double commission);
}
What’s wrong with this?

Convenience methods
}
Too many overloads

Convenience methods
}
Too many overloads
Inconsistent argument order

Convenience methods
Long arguments lists (especially of same type)
}
Too many overloads

Convenience methods
Long arguments lists (especially of same type)
}
void sell(String symbol, int quantity, Price price);
void buy(String symbol, int quantity, Price price);
}
Too many overloads
How to do better

Consider static
factories
public interface Price {
static Price price( double price ) {
if (price < 0) return Malformed.INSTANCE;
return new Fixed(price);
}
static Price price( double minPrice, double maxPrice ) {
if (minPrice > maxPrice) return Malformed.INSTANCE;
return new Range(minPrice, maxPrice);
}
class Fixed implements Price {
private final double price;
private Fixed( double price ) {
this.price = price;
}
}
class Range implements Price {
private final double minPrice;
private final double maxPrice;
private Range( double minPrice, double maxPrice ) {
this.minPrice = minPrice;
this.maxPrice = maxPrice;
}
}
enum Malformed implements Price { INSTANCE }
}
➢
nicer syntax for users
(no need of new
keyword)

Consider static
factories
}
}
this.price = price;
}
}
}
}
}
➢
(no need of new
keyword)
➢
can return different
subclasses

Consider static
factories
}
}
this.price = price;
}
}
}
}
}
➢
(no need of new
keyword)
➢
can return different
subclasses
➢
can check
preconditions and
edge cases returning
different
implementations
accordingly

Promote fluent API
Price withCommission(double commission);
Price gross();
}
void setCommission(double commission);
void setGross();
}

Promote fluent API
Price gross();
}
stockOrder.buy( "IBM", 100, price(150.0).withCommission(0.7).gross() );
void setGross();
}
Price price = price(150.0);
price.setCommission(0.7);
price.setGross();
stockOrder.buy( "IBM", 100, price );

Promote fluent API
Price gross();
}
stockOrder.buy( "IBM", 100, price(150.0).withCommission(0.7).gross() );
void setGross();
}
Price price = price(150.0);
price.setCommission(0.7);
price.setGross();
stockOrder.buy( "IBM", 100, price );
Concatenate multiple invocations
Use result directly

Promote fluent API
Streams are a very
nice and convenient
example of fluent API

Promote fluent API
Name consistency???
Streams are a very
nice and convenient
example of fluent API

Use the weakest possible type
public String concatenate( ArrayList<String> strings ) {
StringBuilder sb = new StringBuilder();
for (String s : strings) {
sb.append( s );
}
return sb.toString();
}

public String concatenate( ArrayList<String> strings ) {
sb.append( s );
}
}
Do I care of the actual
List implementation?

public String concatenate( List<String> strings ) {
sb.append( s );
}
}

public String concatenate( List<String> strings ) {
sb.append( s );
}
}
Do I care of the
elements’ order?

public String concatenate( Collection<String> strings ) {
sb.append( s );
}
}

public String concatenate( Collection<String> strings ) {
sb.append( s );
}
}
Do I care of the
Collection’s size?

public String concatenate( Iterable<String> strings ) {
sb.append( s );
}
}

Using the weakest possible type...
public String concatenate( Iterable<String> strings ) {
sb.append( s );
}
}
… enlarges the applicability of your method, avoiding to restrict your client
to a particular implementation or forcing it to perform an unnecessary and
potentially expensive copy operation if the input data exists in other forms

also for returned value
public List<Address> getFamilyAddresses( Person person ) {
List<Address> addresses = new ArrayList<>();
addresses.add(person.getAddress());
for (Person sibling : person.getSiblings()) {
addresses.add(sibling.getAddress());
}
return addresses;
}

}
return addresses;
}
Is the order of this List
meaningful for client?

}
return addresses;
}
Is the order of this List
meaningful for client?
… and shouldn’t we maybe return only
the distinct addresses?
Yeah, that will be easy let’s do this!

Set<Address> addresses = new HashSet<>();
}
return addresses;
}
It should be enough to
change this List into a Set

}
return addresses;
}
But this doesn’t
compile :(

}
return addresses;
}
But this doesn’t
compile :(
and I cannot change the returned type to
avoid breaking backward compatibility :(((

}
return new ArrayList<>( addresses );
}
I’m obliged to uselessly create an expensive
copy of data before returning them

public Collection<Address> getFamilyAddresses( Person person ) {
}
return addresses;
}
Returning a more generic type (if this is acceptable
for your client) provides better flexibility in future

Support lambdas
public interface Listener {
void beforeEvent(Event e);
void afterEvent(Event e);
}
class EventProducer {
public void registerListener(Listener listener) {
// register listener
}
}
}
}
EventProducer producer = new EventProducer();
producer.registerListener( new Listener() {
@Override
public void beforeEvent( Event e ) {
// ignore
}
@Override
public void afterEvent( Event e ) {
System.out.println(e);
}
} );

Support lambdas
public void registerBefore(BeforeListener before) {
}
public void registerAfter(AfterListener after) {
}
}
@FunctionalInterface
interface BeforeListener {
void beforeEvent( Event e );
}
interface AfterListener {
void afterEvent( Event e );
}
producer.registerAfter( System.out::println );
Taking functional interfaces as
argument of your API enables
clients to use lambdas

Support lambdas
public void registerBefore(Consumer<Event> before) {
}
public void registerAfter(Consumer<Event> after) {
}
}
interface BeforeListener {
void beforeEvent( Event e );
}
interface AfterListener {
void afterEvent( Event e );
}
producer.registerAfter( System.out::println );
Taking functional interfaces as
argument of your API enables
clients to use lambdas
In many cases you don’t need
to define your own functional
interfaces and use Java’s one

Optional – the mother of all bikeshedding

Principle of least
astonishment???
"If a necessary feature has a high
astonishment factor, it may be
necessary to redesign the feature."
- Cowlishaw, M. F. (1984). "The
design of the REXX language"

Principle of least
astonishment???
Wrong default

Principle of least
astonishment???
Wrong default
This could be removed if
the other was correctly
implemented

API design is an
iterative process
and there could
be different points
of view ...

… that could be
driven by the fact
that different
people may
weigh possible
use cases
differently...

… or even see
use cases to
which you didn’t
think at all

Also a good API
has many
different
characteristics ...

… and they
could be
conflicting so you
may need to
trade off one to
privilege another

What should
always drive the
final decision is
the intent of the
API … but even
there it could be
hard to find an
agreement

●
Write lots of tests and examples against your API
●
Discuss it with colleagues and end users
●
Iterates multiple times to eliminate
➢
Unclear intentions
➢
Duplicated or redundant code
➢
Leaky abstraction
API design is an
iterative process

●
Write lots of tests and examples against your API
●
Discuss it with colleagues and end users
●
Iterates multiple times to eliminate
➢
Unclear intentions
➢
Duplicated or redundant code
➢
Leaky abstraction
Practice Dogfeeding
API design is an
iterative process

And that’s all
what you were
getting wrong :)
… questions?
Mario Fusco
Red Hat – Principal Software Engineer
mario.fusco@gmail.com
twitter: @mariofusco

Let's make a contract: The art of designing a Java API | DevNation Tech Talk

Recommandé

Recommandé

Contenu connexe

Tendances

Tendances (20)

Similaire à Let's make a contract: The art of designing a Java API | DevNation Tech Talk

Similaire à Let's make a contract: The art of designing a Java API | DevNation Tech Talk (20)

Plus de Red Hat Developers

Plus de Red Hat Developers (20)

Dernier

Dernier (20)

Let's make a contract: The art of designing a Java API | DevNation Tech Talk