API Design with Java 8

13 November 2017 @ 10:42pm by erik

In this blog post, Per-Åke Minborg talks about the fundamentals of good API design. His inspiration for writing this article is a blog post by Ference Mihaly which is essentially a check-list for good Java API design.

“API combines the best of two worlds, a firm and precise commitment combined with a high degree of implementation flexibility, eventually benefiting both the API designers and the API users.”

Do not Return Null to Indicate the Absence of a Value

Using the Optional class that was introduced in Java 8 can alleviate Javas problem with handling nulls. An example below shows the implementation of the Optional class.

Without Optional class

public String getComment() {

    return comment; // comment is nullable


With Optional class

public Optional getComment() {

    return Optional.ofNullable(comment);


Do not Use Arrays to Pass Values to and From the API

“In the general case, consider exposing a Stream, if the API is to return a collection of elements. This clearly states that the result is read-only (as opposed to a List which has a set() method).”

Not exposing a Stream

public String[] comments() {

    return comments; // Exposes the backing array!


Exposing a Stream

public Optional getComment() {

    return Optional.ofNullable(comment);


Consider Adding Static Interface Methods to Provide a Single Entry Point for Object Creation

Adding static interface methods allows the client code to create onjects that implement the interface. “For example, if we have an interface Point with two methods int x() and int y(), then we can expose a static method Point.of(int x, int y) that produces a (hidden) implementation of the interface.”

Not using static interface methods

Point point = new PointImpl(1,2);

Using static interface methods

Point point = Point.of(1,2);

I selected this resource because it relates to design principles, and it’s something that I do not know well. I would like to learn more about APIs and good practices for designing them using Java. The article had useful information and topics that I didn’t know well. A few more pointers from the article I learned:

  • Favor Composition With Functional Interfaces and Lambdas Over Inheritence – Avoid API inheritance, instead use static interface methods that take “one or several lambda parameters and apply those given lambdas to a default internal API implementation class.”
  • Ensure That You Add the @FunctionalInterface Annotation to Functional Interfaces – signals that API users may use lambdas to implement the interface
  • Avoid Overloading Methods With Functional Interfaces as Parameters – Can cause lambda ambiguity on the client side.

I would like to learn more about using AWS Lambdas, and learning more about APIs in general. I plan to use this information if I am ever to work on Java APIs which is possible. I want to make sure I have the best practices and the check list mentioned in the start of the article seems like a good starting point.

Leave a Reply