api design done right: some guidelines which every programmer should probably know

7/26/2019 API Design Done Right: Some guidelines which every programmer should probably know

1/25

API Design Done RightSome guidelines which every programmer should probably know

Monday, September 12, 2011


2/25

API Design Done WRONG



3/25

Copyright Reaktor 2011

publicintcountBigCustomers() {

Connection connection = null;

try{

connection = DriverManager.getConnection("jdbc:h2:mem:");

PreparedStatement statement = connection

.prepareStatement("SELECT COUNT(*) FROM CUSTOMERS WHERE REVENUE > ?");

// Do indexes start from 0 or 1?

statement.setLong(1, 1000000L);

ResultSet resultSet = statement.executeQuery();

resultSet.next();


intresult = resultSet.getInt(1);

returnresult;

} catch(SQLException e) {

// Checked exception - ouch!

thrownewRuntimeException(e);

} finally{

try{

if(connection != null&& !connection.isClosed()) {

connection.close();

} } catch(SQLException e) {

// Checked exception - aargh


}

}

}



4/25




try{

connection = DriverManager.getConnection("jdbc:h2:mem:");

PreparedStatementstatement = connection

.prepareStatement("SELECT COUNT(*) FROM CUSTOMERS WHERE REVENUE > ?");


statement.setLong(1,1000000L);


resultSet.next();


intresult = resultSet.getInt(1);

returnresult;

} catch (SQLException e) {



} finally {

try{

if(connection != null && !connection.isClosed()) {

connection.close();

} } catch (SQLException e) {

// Checked exception - aargh


}

}

}



5/25

Copyright Reaktor 2011 Confidential


JdbcTemplate jdbc = newJdbcTemplate(newSingleConnectionDataSource(

"jdbc:h2:mem:", false));

returnjdbc.queryForInt(

"SELECT COUNT(*) FROM CUSTOMERS WHERE REVENUE > ?", 1000000L);

}

A bit better way



6/25


Why API Design Matters

Usually write-once,

read/learn many times

by many different people

Every piece of code has an API



7/25


Why API Design Matters

Bad API usually leads to bad client code

Bad API design tends to infect all abovelayers

http://www.flickr.com/photos/bamshad/1469713774/sizes/s/in/photostream/



8/25


API is a User Interface

The same principles apply



9/25



The purpose and usages must be known



10/25



Make correct usage easy

Make wrong usage hard

(or impossible)



11/25


Good API

Intuitive

Easy to learn from simple examples

Self explanatory

Effort minimizing



12/25


Levels of abstraction



try{

connection = DriverManager.getConnection

("jdbc:h2:mem:");

PreparedStatement statement = connection

.prepareStatement("SELECT COUNT(*)

FROM CUSTOMERS WHERE REVENUE > ?");


statement.setLong(1, 1000000L);


resultSet.next();

// Do indexes start from 0 or 1? intresult = resultSet.getInt(1);

returnresult;



thrownew RuntimeException(e);

} finally{

try{

if(connection != null&& !

connection.isClosed()) {

connection.close();

}


// Checked exception - aargh thrownewRuntimeException(e);

}

}

}


JdbcTemplate jdbc = newJdbcTemplate(newSingleConnectionDataSource(

"jdbc:h2:mem:", false));

returnjdbc.queryForInt(

"SELECT COUNT(*) FROM CUSTOMERS WHERE REVENUE > ?", 1000000L);

}

JDBC API Spring API

Good abstraction level for low-level library code, bad for

application code

Good abstraction level forapplication code



13/25


Levels of abstraction



14/25


Client perspective with TDD@RunWith(Enclosed.class)

publicclassOrderBuilderTest {

publicstaticclassWhenBuildingOrderWithTwoProducts {

privateOrder order;

@Before

publicvoidsetUp() {

// API as an user interface - how user of the API would

create an order order= newOrderBuilder(CustomerId.FANBOY_CUSTOMER)

.with(ProductId.JPHONE_6, 4)

.with(ProductId.CONSTELLATION_TABLET, 2)

.build();

}

@Test publicvoidorderHasTwoRows() {

assertThat(order.orderRows().size(), is(2));

}

}

}



15/25


Simplicity



16/25


Object initialization

An object should be in valid, usable stateimmediately.

Component c = newComponent();

// Here the component cannot be used

// yet, since it is not initialized,

// i.e. it is in an invalid state.

c.initialize(newConfiguration());

// Only now the component can be used.

BAD!!!

Component c = newComponent(new

Configuration());

// Now the component can be used

// immediately. BETTER



17/25


Object initialization

Use builders or factories for more complexinitializations

order= newOrderBuilder(CustomerId.FANBOY_CUSTOMER)

.with(ProductId.JPHONE_6, 4)

.with(ProductId.CONSTELLATION_TABLET, 2)

.build();

// default visibility

// we can only create objects with valid state

Order(CustomerId customerId, List orderRows) {

this.customerId= customerId;

this.orderRows= Collections.unmodifiableList(orderRows);

}

publicclassOrderBuilder {

publicOrderBuilder(CustomerId customerId) { ... }

publicOrderBuilder with(ProductId productId, intquantity) { ... }

publicOrder build() { ...}

}



18/25


Object state

It should be impossible to get an object in anillegal state.

Object should be in a valid state between

any method calls.

Fail fast if the method call would leave the

object in an invalid state.



19/25


Object state

Prefer immutability

publicclassOrder {

privatefinalCustomerId customerId;

privatefinalList orderRows;

Order(CustomerId customerId, List orderRows) {

this.customerId= customerId;

this.orderRows= Collections.unmodifiableList(orderRows);

}

}



20/25


Atomic operations

// User must explicitly begin transaction...c.beginTransaction();

// ...do their stuff...

c.doSomething();

// ...and remember to commit...

c.commit();

// ...but what if something fails in between?

c.doInTransaction(newCallback() {

@Override

publicvoidexecute(Component c) {

// Method doInTransaction() takes

// care oftransaction management

// and error handling

c.doSomething();

}

});

BAD!!!

BETTER



21/25


Visibility and packages in Java

Domain class name is the package name:packagemyapp.domain.order;

All services, interfaces and implementation

related to this domain class in the samepackage.



22/25


Visibility and packages in Java

Public visibility:domain class,

interfaces for services,

builders, ...

publicclassOrder { ...

public interface OrderRepository { ...

public class OrderBuilder { ...



23/25


Visibility and packages in JavaDefault visibility:

domain object constructors,

implementation classes

// domain object constructor

Order(CustomerId customerId, List orderRows) { ...

// repository implementation

classJdbcOrderRepository implementsOrderRepository { ...



24/25


Domain Specific Languages

Counting two weeks from a given date:

publicDate twoWeeksFrom(Date beginning) {

// You have to create a

// separate Calendar object...

Calendar calendar = Calendar.getInstance(); // And modify its state...

calendar.setTime(beginning);

// And modify its state a little more...

calendar.add(Calendar.DAY_OF_MONTH, 14);

// ...before you get the answer.

returncalendar.getTime();

}

publicDateTime twoWeeksFrom(DateTime beginning) {

returnbeginning.plusWeeks(2);

}

Standard Java Calendar API

Joda-Time



25/25


Thank you!

Jari Mkel

Ville Peurala
mailto:[email protected]:[email protected]:[email protected]:[email protected]

api design done right: some guidelines which every programmer should probably know

Documents