Designing an API

Presented at TU Delft

Transcript

1. Designing an API Arjen Poutsma Pivotal
2. About Arjen • University of Amsterdam • Philosophy • Artificial Intelligence • Twenty years of experience in Enterprise Software Development • Ten years of Spring • Spring Web Services • Spring REST • Spring Scala • Spring Reactive
3. About Spring • Started in 2003, based on Rod Johnson’s book • Dowloaded million times per month • @MVC is most popular Java Web Framework • Upcoming 5.0 is going “Reactive”
5. Agenda • Consistency • Simplicity • Compatibility • Flexibility
6. Consistency “Doing things the same way”
7. Principle of Least Astonishment “The result of performing some operation should be obvious, consistent, and predictable, based upon the name of the operation and other clues.” http://c2.com/cgi/wiki?PrincipleOfLeastAstonishment
8. Consistency • Naming • Types, methods, documentation, parameters, packages, … • Usage patterns • Thread-safety, immutability, parameter order, … • Similar to other popular APIs
9. Templates in Spring • JdbcTemplate • JmsTemplate • HibernateTemplate • RestTemplate • … • but: JpaTemplate
10. XML APIs • SAX void startElement(String namespaceURI, String localName, String qualifiedName, ...) • DOM Element createElementNS(String namespaceURI, String qualifiedName) • StAX void writeStartElement(String prefix, String localName, String namespaceURI)
11. Dos and Don’ts ✓Take inspiration from other popular APIs ✗Consistent for consistency’s sake
12. Simplicity “Doing things the easiest way”
13. Simplicity • “Everything should be made as simple as possible, but no simpler” – Albert Einstein • “Make simple things simple, and complex things possible” – Alan Kay • “The simplest thing that could possibly work” – Kent Beck • “The first thing I could possibly think of”
14. Hiding Complexity • The goal of any API is to hide complexity behind abstractions • Create multiple implementations to see if your abstractions are correct • The simplest thing that works! • You don’t have to ship them
15. Cyclomatic Complexity • Number of linearly independent code paths • Trend is more important than absolute number https://en.wikipedia.org/wiki/Cyclomatic_complexity
16. Dos and Don’ts ✓Focus outside ✓Use your own API ✓Multiple implementations of interfaces ✓Decrease Cyclomatic Complexity ✗Focus inside ✗Expose internal complexity
17. Compatibility “Doing things the old way”
18. Backward Compatibility • Source level • Existing source code compiles against new version • Binary level • Code compiled against old version will still run on new version • Java & Spring vs. Semantic Versioning
19. What breaks compatibility? • Removing a public type • Adding abstract method • Removing an inherited method • Changing parameter • Change return type • Changing superclass
20. Public vs Published • Published Interface is a class interface used outside the code base that it's defined in. http://martinfowler.com/bliki/PublishedInterface.html
21. When in doubt, leave it out • You can always add a feature, but you can never take it out • So: do not add features you are unsure about http://www.artima.com/intv/blochP.html
22. Change Event Horizon • Amount of time before you can undo the effect of a decision • Huge for programming languages • Small for Agile projects • APIs are more like languages https://dannorth.net/2006/05/28/how-simple-is-too-simple
23. Dos and Don’ts ✓Backward compatibility ✓Leave out unclear features ✓Determine published interface ✗Add features prematurely ✗Remove code users depend on
24. Flexibility “Doing things in new ways”
25. Flexibility • “Make simple things simple, and complex things possible” – Alan Kay • Ability to do things which you didn’t expect
26. Strategy Interfaces • Allow people to customize inner workings • Use these strategies yourself • No hidden API!
27. Circular Dependencies • Package A requires B, and B requires A • For example: java.lang and java.io • Spring has none • Tooling: IntelliJ, Structure 101 and SonarJ
28. Dos and Don’ts ✓Create strategies to change default behavior ✓Use these strategies ✗Hidden APIs ✗Circular dependencies
29. Q & A