The 42 of Software Interfaces (Part II, API, Meta-Process, Management)

Part II of my Interface-Session at Software-Architecture-Summit, June 2013 in Berlin.

* API vs SPI
* Meta-Process of Interfaces: Billing, Legal-issues, SLA etc.
* API Management
* (Some) rules for good API's: compatibility, usability etc

Transcript

1. © 2013 innoQ Deutschland GmbH 42 of So ware Interfaces The Horror of Information Technology Dr. Gernot Starke
2. © 2013 innoQ Deutschland GmbH Software Interfaces
3. © 2013 innoQ Deutschland GmbH Types of API UI Interfaces advanced Meta- Process basics describing designing
4. © 2013 innoQ Deutschland GmbH basic types.... Request-Response: classical with many variants (async) Messaging Shared database File Transfer EAI-Patterns: http://www.eaipatterns.com/toc.html
5. © 2013 innoQ Deutschland GmbH Request-Response… API: use Need Have SPI (Provider  Interface)   Provider SPI: implement <<implements>>
6. © 2013 innoQ Deutschland GmbH Intro (V1, API) Need   Have  
7. © 2013 innoQ Deutschland GmbH intro 1. Need requires something (data, service). 2. Somebody brokers •  determine provider •  establish physical connection •  transmit Need-request to Have 3. Have provides something 4. Somebody transmits result to Need. Need Have
8. © 2013 innoQ Deutschland GmbH how it works... Exchange of resources (data, service) between: ‣ client, consumer, caller, requester, subscriber, user ‣ server, supplier, host, (service-)provider, publisher Need Have
9. © 2013 innoQ Deutschland GmbH you need to care about... What to transmit? How does it look like • Resources • Methods/functions What does it mean? How Need nds Have Need Have At least!
10. © 2013 innoQ Deutschland GmbH Request-Response… API: use Need Have SPI: implement SPI (Provider  Interface)   Provider <<implements>>
11. © 2013 innoQ Deutschland GmbH SPI example: Account-Number- Validation
12. © 2013 innoQ Deutschland GmbH SPI example: Account-Number- Validation ‣ Central Bank publishes list of valid algorithms to calculate checksums for account-numbers ‣  May 2013: approx. 140 di erent! ‣ Companies implement those (or subset) Company checksum-
 calculation" algorithms" http://www.bundesbank.de/Navigation/DE/Kerngeschaeftsfelder/Unbarer_Zahlungsverkehr/ Pruefzifferberechnung/pruefzifferberechnung.html
13. © 2013 innoQ Deutschland GmbH SPI (Provider Interface)... My implementation will work forever! Expectation of implementor!
14. © 2013 innoQ Deutschland GmbH SPI (Provider Interface)... My implementation will work forever! care for compatibility
15. © 2013 innoQ Deutschland GmbH SPI (Provider Interface)... care for compatibility •  Don‘t add methods (implementors are not compilable) •  Solution: new interfaces...
16. © 2013 innoQ Deutschland GmbH Intro (messaging, le-transfer) Message   push or pull Receiver   Sender   sync or async
17. © 2013 innoQ Deutschland GmbH UGYOC* * UGYOC = Urgently Get Your Own Copy
18. © 2013 innoQ Deutschland GmbH Envelope   Body   Prefix   Body   Suffix   payload Messages, Files
19. © 2013 innoQ Deutschland GmbH Sample: Chess 1.  Display 2. Pieces, Rules... @Stefan Zörner: thx for this idea!"
20. © 2013 innoQ Deutschland GmbH Sample: Chess 1.  Display ‣  Moves ‣  Position ‣  Timer ‣  User Input ‣  ....
21. © 2013 innoQ Deutschland GmbH Sample: Chess 1.  Display 2. Pieces, Rules... ‣  Strength ‣  Color-to-Play ‣  Setup-Position ‣  Restart Game ‣  Selected-Move Chess engine
22. © 2013 innoQ Deutschland GmbH Sample: Chess Chess engine command" command"
23. © 2013 innoQ Deutschland GmbH Sample: UCI & xboard „commands“ as stdin/stdout text: ‣  ping, setboard, playother, usermove, san, time, draw, sigint, sigterm, myname, variants, colors, memory, smp, option, done ... ‣  UCI: http://www.shredderchess.de/schach-info/features/uci-universal-chess-interface.html ‣  xboard: http://www.gnu.org/so ware/xboard/engine-intf.html Chess engine command" command" STABLE since 2000 (UCI)!
24. © 2013 innoQ Deutschland GmbH Sample: UCI & xboard Chess engine command" command" ‣  Evolution is easy (new commands) ‣  Simple, technology neutral ‣  But: ‣  Requires parser on both ends
25. © 2013 innoQ Deutschland GmbH Engine Tournament... Engine-1 Engine-3 Engine-2
26. Another sample...
27. © 2013 innoQ Deutschland GmbH Sampe...
28. © 2013 innoQ Deutschland GmbH Geocaching... ‣  Request Map ‣  Select „Cache“ ‣  Read description & other people remarks ‣  Find „treasure“ ‣  Send log-entry to central server
29. © 2013 innoQ Deutschland GmbH Geocaching... ‣  Requirements: ‣  Works o line ‣  Multiple device categories
30. © 2013 innoQ Deutschland GmbH Sample: Geocaching GPX
31. © 2013 innoQ Deutschland GmbH Prefix   Body   Suffix   Interfacing with Files ‣  Still widely used in practice, e.g. banking, insurance, government ‣  Technology-neutral ‣  Flexible ‣  Easy to use & test
32. © 2013 innoQ Deutschland GmbH Prefix   Body   Suffix   Interfacing with Files ‣  Requires speci c parser and generator ‣  REST-free ‣  Un-web, un-mobile ‣  Boring, old-fashioned
33. © 2013 innoQ Deutschland GmbH Prefix   Body   Suffix   Interfacing with Files ‣  Pre x / Su x can contain: ‣  Sender, Receiver info ‣  Processing instructions ‣  Accounting info ‣  Payload description ‣  Other „meta“ stu
34. Prefix   Interfacing with Files https://www.ksk-koeln.de/formatbeschreibung_datentraegeraustausch.pdfx
35. © 2013 innoQ Deutschland GmbH Interfaces advanced Meta- Process basics describing designing
36. © 2013 innoQ Deutschland GmbH Sample: Credit Card Scoring (1) eCommerce client Credit Card Scoring Server card-info" risk"
37. © 2013 innoQ Deutschland GmbH Sample: Credit Card Scoring (2) From: http://www.mediafinanz.de/upload/soap/SOAP_Infoscore.pdf eCommerce client Credit Card Scoring Server cardinfo" risk" Function: getBasicScore() Description: Evaluates risks for speci c credit card (score). Errors are returned as ArrayOfError. Return: ScoringResult Parameter: Type Name Remark 1 Auth Auth Authencation-Parameter of Client 2 Suspect Suspect Card and holder 3 String Reason reason Optional 4 [String] Params Additional parameters
38. © 2013 innoQ Deutschland GmbH Provider company Requester company (heavy) violence... eCommerce client Credit Card Scoring bill 1 2 META-PROCESS 0
39. © 2013 innoQ Deutschland GmbH Meta-Process... ‣ Human activities before and a er so ware interaction ‣ Consequences: ‣  Financial ‣  Legal ‣  Organizational
40. © 2013 innoQ Deutschland GmbH Meta-Process... ‣  Veri cation of usage: Legally valid logging ‣  Authorization ‣  Tari , pricing, contract
41. © 2013 innoQ Deutschland GmbH Meta-Process... ‣ Guarantees: Quality of Service ‣ Versioning ‣ Stakeholder inferno… ‣ <LOUS*> * LOUS: Lot‘s Of Ugly Stuff
42. © 2013 innoQ Deutschland GmbH Another Example... ‣ „request“ contains meta info: requestCount: „How o en did you call me?“ ‣  E.g.: pension contributions corporation Very Official Agency request" response" ‣  Requires metadata management... ‣  Calls CAN NOT be independent
43. © 2013 innoQ Deutschland GmbH Meta-Horror Corporation (proxy) Very Official Agency Request" in behalf of
 others" response" Small Company 1 Small Company 2 with metadata Small Company 3 Small Company 280 ‣  Requires synchronization of otherwise independent entities
44. © 2013 innoQ Deutschland GmbH Meta-Process requires... governance management
45. © 2013 innoQ Deutschland GmbH API Management is relevant... API Management is Distinct From SOA Governance API Management Platforms Will Continue To Develop
46. © 2013 innoQ Deutschland GmbH API Management ? ‣  Access Control & Security ‣  Developer Portal ‣  Contracts, Rates ‣  Analytics ‣  Billing, Payment ‣  Deployment ‣  Support, SLA http://www.3scale.net/api-management/api-proxy-for-api-traffic-management-by-3scale/
47. © 2013 innoQ Deutschland GmbH API Management is BIG...
48. © 2013 innoQ Deutschland GmbH API Management is BIG... http://cloudsecurity.intel.com/api-management
49. © 2013 innoQ Deutschland GmbH API Management is BIG... API Management API Security API Analytics Developer Enablement Tools http://cloudsecurity.intel.com/api-management
50. © 2013 innoQ Deutschland GmbH API Management is BIG... http://www.layer7tech.com/products/api-proxy
51. © 2013 innoQ Deutschland GmbH API Management is BIG... API Analytics http://www.mashery.com/product/features/partner-portal
52. © 2013 innoQ Deutschland GmbH API Management is BIG... http://apiphany.com/#/product
53. © 2013 innoQ Deutschland GmbH API Management is BIG... http://apiphany.com/#/product
54. © 2013 innoQ Deutschland GmbH API Management is BIG... http://blog.programmableweb.com/2011/10/19/api-service-provider-roundup/
55. © 2013 innoQ Deutschland GmbH
56. © 2013 innoQ Deutschland GmbH Interfaces advanced Meta- Process basics describing designing
57. © 2013 innoQ Deutschland GmbH Designing
58. © 2013 innoQ Deutschland GmbH What makes a good API? ‣  Easy to learn and use ‣  Leads to readable code ‣  Complete ‣  Hard to misuse ‣  Easy to extend Josh Bloch / Jasmin Blanchette Comfortable
59. © 2013 innoQ Deutschland GmbH Design UI for pdf-stamper 0: some pdf les in source-dir 1: name source+ target dir 2: security: allow copy, allow print? 3: header, footer? http://openeuropeblog.blogspot.de/2013/03/the-triple-challenge-behind-eu-move-to.html
60. © 2013 innoQ Deutschland GmbH API == Matter of Taste
61. © 2013 innoQ Deutschland GmbH Tipps for API design (1) ‣  Beware of meta process ‣  If in doubt, remove it
62. © 2013 innoQ Deutschland GmbH Tipps for API design (2) ‣  Expect to evolve ‣  Compatibility counts ‣  Source vs Binary compatibility ‣  Develop versioning strategy
63. © 2013 innoQ Deutschland GmbH On Compatibility... ‣  Source ... ‣  Client compiles against new version ‣  Binary ... ‣  Client links with new version ‣  Functional ... ‣  Client executes against new version, behaves identical.
64. © 2013 innoQ Deutschland GmbH 6 © 2013innoQ Deutschland GmbH client new Date! valid Date new Date(…):! ! (1) Date( y, m, d)?! (2) Date( d, m, y)?! (3) Date( “23/5/13”)?! ! Param lists are dangerous
65. © 2013 innoQ Deutschland GmbH Why don‘t we all ... 6 © 2013innoQ Deutschland GmbH ‣ Use Groovy? Or Python? Named param lists are easy
66. © 2013 innoQ Deutschland GmbH
67. © 2013 innoQ Deutschland GmbH Tipps for API design (3) ‣  Know your clients: ‣  Perform „stakeholder analysis“ ‣  Be sure to understand client use-cases ‣  Create client-type speci c interfaces ‣  Use it yourself. Again and again.
68. © 2013 innoQ Deutschland GmbH Tipps for API design (3b) ‣  Start with examples: ‣  Write clients, using your interface ‣  Write tests (TDD philosophy) ‣  Show it to somebody ELSE
69. © 2013 innoQ Deutschland GmbH pdfutil  –e  –s  2  3  –f  „./_target“   ‣  Option? ‣  Parameter? ‣  Argument? ‣  List? ‣  Pre x?
70. © 2013 innoQ Deutschland GmbH Tipps for API design (4) ‣  Names are important ‣  API shall be understandable for clients ‣  Josh Bloch calls it „Little Language“ ‣  Use client-speci c terminology ‣  See: Domain-Driven-Design J
71. © 2013 innoQ Deutschland GmbH e.g. habits, fashions, practices dd / mm / yyyy mm / dd / yyyy km/h, mph liter / 100 km miles / gallon order, unit
72. © 2013 innoQ Deutschland GmbH Names should reveal intention activate() deactivate() isActive() registerUser() setActive() getActive() setUser() getUser() Use ubiquitous language
73. © 2013 innoQ Deutschland GmbH Tipps for API design (5) ‣  Users want to start fast ‣  J. Tulach calls it „Selective Cluelessness“ ‣  Design for consumption by ignorants ‣  Allow expert usage
74. © 2013 innoQ Deutschland GmbH Tipps for API design (6) ‣  Maximize privacy ‣  „Information hiding principle“ ‣  Allows modi cation of implementation ‣  Don‘t leak internal details ‣  File formats and structure, exceptions, wire formats
75. © 2013 innoQ Deutschland GmbH 7 © 2013innoQ Deutschland GmbH client Java.util. Date new Date(y, m, d)! valid Date
76. © 2013 innoQ Deutschland GmbH Improve Readability
77. © 2013 innoQ Deutschland GmbH Improve Readability (but write more code) public class MyFluentBuilder { public MyFluentBuilder addFoo(String s) { // do something return this; } public MyFluentBuilder withfluentInterface(String s) { // do something return this; } public MyFluentBuilder andBar(String s) { // do something return this; } } MyFluentBuilder mf = new MyFluentBuilder() .addFoo(„some“) .withFluentInterface(„42“) .andBar(„hipp“);
78. © 2013 innoQ Deutschland GmbH Fluent Interface / Method-Chaining @Lars-Erik Kindblad: thx!"
79. © 2013 innoQ Deutschland GmbH in Practice... JOptSimple, Command Line Parsing Library 79
80. © 2013 innoQ Deutschland GmbH When to use FluentInterface / Builder? •  Methods are o en used •  Many (>4-5) constructor arguments •  See Martin Fowler on FluentInterface: http://martinfowler.com/bliki/ FluentInterface.html 80
81. © 2013 innoQ Deutschland GmbH Interfaces advanced Meta- Process basics describing designing
82. © 2013 innoQ Deutschland GmbH Documenting
83. © 2013 innoQ Deutschland GmbH Reasons for documenting interfaces ‣  allow others to use your system ‣  Generate integration code from documentation ‣  show interactions between building blocks ‣  impact analysis ‣  assure long-term understandability Web / REST!
84. © 2013 innoQ Deutschland GmbH Options for documenting interfaces 1. RESTful (for web stu ) 2. Intra-app (your own stu ) Very hipp!
85. © 2013 innoQ Deutschland GmbH Documenting RESTful interfaces auto-generated, always up-to-date, stylish documentation
86. © 2013 innoQ Deutschland GmbH Documenting RESTful interfaces (2) ‣  SpringDoclet ‣  RestDoclet
87. © 2013 innoQ Deutschland GmbH Documenting RESTful interfaces (3) ‣  Apiary.io: API blueprint ‣  DSL for API description ‣  Generates documentation, mock-server . http://apiary.io/blueprint
88. © 2013 innoQ Deutschland GmbH Documenting RESTful interfaces (3b) ‣  Apiary.io: API blueprint http://apiary.io/blueprint
89. © 2013 innoQ Deutschland GmbH Documenting RESTful interfaces (4) ‣  Swagger: produce, visualize & consume RESTful services
90. Template for Documenting RESTful interfaces http://weblog.bocoup.com/documenting-your-api/ Title <The name of your API call> Example : Show All Users URL <The URL structure (path only, no root url)> /users or /users/:id or /users?id=:id Method The request type> : GET | POST | DELETE | PUT URL Params If URL params exist, specify them in accordance with name mentioned in URL section. Separate into optional and required.> Data Params <If making a post request, what should the body payload look like? This is a good time to document your various data constraints too.> Success Response <What should the status code be on success and is there any returned data? This is useful when people need to to know what their callbacks should expect!> Error Response <Most endpoints will have many ways they can fail. From unauthorized access, to wrongful parameters etc. All of those should be listed here. It might seem repetitive, but it helps prevent assumptions from being made where they shouldn't be.> Sample call <Just a sample call to your endpoint in a runnable format ($.ajax call or a curl request) - this makes life easier and more predictable.>
91. © 2013 innoQ Deutschland GmbH Documentation for Code Generation ‣  Apache Thri : RPC across languages ‣  Code-Gen Library ‣  Enable e cient & reliable communication across programming-languages ‣  C++, C# Cocoa, Delphi, Erlang, Haskell, Java, Perl, PHP, Python, Ruby and more ‣  Developed at Facebook ‣  Interface De nition Language http://thrift.apache.org/ Very geeky!
92. © 2013 innoQ Deutschland GmbH Documentation for Code Generation ‣  Franca IDL: Speci cation of APIs ‣  DSL (Eclipse/EMF) ‣  User-friendly editor ‣  Framework for transformation to/from e.g. Thri Also geeky! http://code.google.com/a/eclipselabs.org/p/franca/
93. © 2013 innoQ Deutschland GmbH UML for documentation ‣ O en mis-used ‣ o ers too MANY options ‣  Go for simplicity (selective lazyness) ‣  More precision / details => more e ort required ‣ Can ‣  help with overview ‣  explain context
94. © 2013 innoQ Deutschland GmbH Interfaces in UML
95. © 2013 innoQ Deutschland GmbH Template for Interface documentation Identifikation: Genaue Bezeichnung und Version der Schnittstelle. Bereitgestellte Ressource(n): Welche Ressourcen (Daten, Ereignisse) stellt diese Schnittstelle ihren Benutzern oder Aufrufern zur Verfügung? Syntax: Signatur von Methoden, Typen von Parametern, Daten-/Dateistrukturen Semantik: Welche Auswirkung hat die Nutzung/der Aufruf dieser Schnittstelle? Welche Daten oder Zustände ändern sich? Wahrnehmbare Nebenwirkungen? Protokoll: Detaillierter Ablauf bei Nutzung dieser Schnittstelle. Ggfs. Verweis auf Laufzeitsicht. Restriktionen: Einschränkungen bei der Nutzung (Rechte, zeitliche Einschränkungen o.ä.) Fehlerszenarien: Verhalten im Fehlerfall oder Ausnahmesituation Variabilität: Konfigurierbarkeit, Varianten oder Alternativen der Schnittstelle, hinsichtlich Syntax, Semantik, Protokoll oder anderen Eigenschaften. Qualitätseigenschaften: (neudeutsch: Service Level Agreements) Entwurfsentscheidungen oder Entwurfsalternativen Beispieldaten
96. © 2013 innoQ Deutschland GmbH Summary: Documenting interfaces Give small sample of a client. Give more samples. Provide reference... e.g. unit test!
97. © 2013 innoQ Deutschland GmbH THANX
98. © 2013 innoQ Deutschland GmbH References (1) ‣  Joshua Bloch: API Design and Why it matters? http://lcsd05.cs.tamu.edu/slides/keynote.pdf ‣  J. Tulach (Netbeans-Architect) Practical API Design ‣  Jasmin Blanchett: Little Manual of API Design http://www4.in.tum.de/~blanchet/api-design.pdf ‣  D.Jacobsen et. al: APIs – A Strategy Guide. ‣  Jaroslav Tulach: 20 API Paradoxes (kindle e-Book), 2012
99. © 2013 innoQ Deutschland GmbH References (2) ‣  Bernd Schi er (heise developer): Flexibel mit dem Fluent Interface http://heise.de/-227052 ‣  Martin Fowler, Eric Evans: Fluent Interface http://martinfowler.com/bliki/FluentInterface.html