When designing a library interface, what are some strategies to keep the API flexible, such that as it evolves it can avoid breaking changes as much as possible. I am asking specifically about Java library APIs, but I'm sure this translates into other languages and possibly even web APIs (e.g. REST APIs).

An example of such a strategy would be using the builder pattern for constructing objects which will likely require new optional properties in the future. If optional properties are passed to a constructor as nullable parameters, adding new ones is a breaking change.

What other strategies are best practice for creating a flexible and stable API?

  • 2
    I think this is a fascinating question, but likely way too broad. Any useful answer would likely be a list of specific techniques, or would just say something like “stick to the Open/Closed principle, see all the object-oriented design patterns for strategies to do that”. And the design patterns are so broad, there have been multiple books written about the topic. – amon Jul 31 at 11:33
  • Though this seems to be a broad question, I would recommend to wait if someone may be able to give a comprehensive answer before overhastily vote for closing it. Community, don't forget this site was created to allow broader, conceptual questions than Stackoverflow. – Doc Brown Jul 31 at 18:40
  • Obligatory cartoon: geek-and-poke.com/geekandpoke/2012/6/6/… ;-) – Doc Brown Jul 31 at 18:42

There are two strategies: One, the API returns some properties of items, and newer versions may return newer properties. The client checks which properties were returned and ignores anything it doesn’t know. You make sure that older clients work wIth newer API versions, and clients make sure they can live with older API versions.

Two, you put a version number into any request to the API. If possible, the API returns data for that API version, including the API version number. If the exact version number is not available, it returns data for the newest available older version number, or the oldest available newer version number. Then we proceed as in case 1.

This assumes that both different versions of the API and of the client can exist at the same time.

Interestingly any patterns didn’t even cross my mind. I was more thinking along the lines of a dictionary, or JSON, focussing more on the actual problem.

| improve this answer | |

Not the answer you're looking for? Browse other questions tagged or ask your own question.