Schnittstellen - Horror der Informatik

dotNET User Group Zentralschweiz, Oktober 2013

1.) Intro: Why Interfaces
2.) brief take on user interfaces. Many (mostly bad) examples.
3.) API, SPI and issues of component interfaces. Many examples.
4.) Documenting interfaces. Sounds boring, but is *really* important
(and does NOT hurt!)

Transcript

1. Interface Horror Issues of cooperating systems
3. © 2013 Dr. Gernot Starke member of:! (co) founder of:! Fellow
4. © 2013 Dr. Gernot Starke Why talk / think about „interfaces“?
5. © 2013 Dr. Gernot Starke Why? Systems fail at interfaces... http://www.city-data.com/forum/attachments/house/
6. © 2013 Dr. Gernot Starke price of good interface 100.000.000 $
7. © 2013 Dr. Gernot Starke Founded 2010. New „interface“ to Email. 13 employees. Dropbox paid approx. 100 Million $
8. © 2013 Dr. Gernot Starke 100.000.000 $ http://gigaom.com/2013/03/15/how-much-did-dropbox-pay-for-mailbox/
9. © 2013 Dr. Gernot Starke Why? Systems win at interfaces...
10. © 2013 Dr. Gernot Starke What to discuss about „interfaces“?
11. © 2013 Dr. Gernot Starke
12. © 2013 Dr. Gernot Starke
13. © 2013 Dr. Gernot Starke What‘s an „Interface“ Inter [latin]: „Between“
14. © 2013 Dr. Gernot Starke Interface: between what?
15. © 2013 Dr. Gernot Starke User Interfaces
16. © 2013 Dr. Gernot Starke User Interface 16 Layout Color Font Size Visual Style Ergonomics i18n Language Formatting Psycho & Soft Issues MVC MVP Observer Binding UI-Framework Swing JSP JavaFX Griffon Widgets HTML CSS
17. © 2013 Dr. Gernot Starke Golden Rules for Bad User Interfaces... http://www.sapdesignguild.org/community/design/golden_rules.asp •  Make usage a challenge •  Make it mouse-only •  Hide important functions •  Help them in technical language
18. © 2013 Dr. Gernot Starke BAD User Interface ... By expert
19. © 2013 Dr. Gernot Starke Underlying data structure de nes UI...
20. © 2013 Dr. Gernot Starke Golden Rules for Bad User Interfaces... http://www.sapdesignguild.org/community/design/golden_rules.asp •  Block user input o en •  Let application freeze from time to time
21. © 2013 Dr. Gernot Starke
22. © 2013 Dr. Gernot Starke TAB order madness ...
23. © 2013 Dr. Gernot Starke
24. © 2013 Dr. Gernot Starke Software Interfaces
25. © 2013 Dr. Gernot Starke Types of API UI Interfaces advanced Meta- Process basics describing designing
26. © 2013 Dr. Gernot Starke basic types.... Request-Response: classical with many variants (async) Messaging Shared database File Transfer EAI-Patterns: http://www.eaipatterns.com/toc.html
27. © 2013 Dr. Gernot Starke Request-Response… API: use Need Have SPI (Provider  Interface)   Provider SPI: implement <<implements>>
28. © 2013 Dr. Gernot Starke Intro (V1, API) Need   Have  
29. © 2013 Dr. Gernot Starke Interface „Metamodel“ Begriffe aus: Documenting Software Architectures, Chap. 7: Documenting Software Interfaces == „point of interaction“: •  Function, Method, (Web-)Service •  Data- or Event-Stream •  Shared-Memory Confusion-warning: REST-Resources
30. © 2013 Dr. Gernot Starke 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
31. © 2013 Dr. Gernot Starke how it works... Exchange of resources (data, service) between: ‣ client, consumer, caller, requester, subscriber, user ‣ server, supplier, host, (service-)provider, publisher Need Have
32. © 2013 Dr. Gernot Starke 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!
33. © 2013 Dr. Gernot Starke Request-Response… API: use Need Have SPI: implement SPI (Provider  Interface)   Provider <<implements>>
34. © 2013 Dr. Gernot Starke SPI example: Account-Number- Validation
35. © 2013 Dr. Gernot Starke 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
36. © 2013 Dr. Gernot Starke SPI (Provider Interface)... My implementation will work forever! Expectation of implementor!
37. © 2013 Dr. Gernot Starke SPI (Provider Interface)... My implementation will work forever! care for compatibility
38. © 2013 Dr. Gernot Starke SPI (Provider Interface)... care for compatibility •  Don‘t add methods (implementors are not compilable) •  Solution: new interfaces...
39. © 2013 Dr. Gernot Starke Intro (messaging, le-transfer) Message   push or pull Receiver   Sender   sync or async
40. © 2013 Dr. Gernot Starke UGYOC* * UGYOC = Urgently Get Your Own Copy
41. © 2013 Dr. Gernot Starke Envelope   Body   Prefix   Body   Suffix   payload Messages, Files
42. © 2013 Dr. Gernot Starke Sample: Chess Chess engine command" command"
43. © 2013 Dr. Gernot Starke 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)!
44. © 2013 Dr. Gernot Starke Sample: UCI & xboard Chess engine command" command" ‣  Evolution is easy (new commands) ‣  Simple, technology neutral ‣  But: ‣  Requires parser on both ends
45. © 2013 Dr. Gernot Starke Engine Tournament... Engine-1 Engine-3 Engine-2
46. © 2013 Dr. Gernot Starke Sampe...
47. © 2013 Dr. Gernot Starke Geocaching... ‣  Request Map ‣  Select „Cache“ ‣  Read description & other people remarks ‣  Find „treasure“ ‣  Send log-entry to central server
48. © 2013 Dr. Gernot Starke Geocaching... ‣  Requirements: ‣  Works o line ‣  Multiple device categories
49. © 2013 Dr. Gernot Starke Sample: Geocaching GPX
50. © 2013 Dr. Gernot Starke Prefix   Body   Suffix   Interfacing with Files ‣  Still widely used in practice, e.g. banking, insurance, government ‣  Technology-neutral ‣  Flexible ‣  Easy to use & test
51. © 2013 Dr. Gernot Starke Prefix   Body   Suffix   Interfacing with Files ‣  Requires speci c parser and generator ‣  REST-free ‣  Un-web, un-mobile ‣  Boring, old-fashioned
52. © 2013 Dr. Gernot Starke Prefix   Body   Suffix   Interfacing with Files ‣  Pre x / Su x can contain: ‣  Sender, Receiver info ‣  Processing instructions ‣  Accounting info ‣  Payload description ‣  Other „meta“ stu
53. Prefix   Interfacing with Files https://www.ksk-koeln.de/formatbeschreibung_datentraegeraustausch.pdfx
54. © 2013 Dr. Gernot Starke Interfaces advanced Meta- Process basics describing designing
55. © 2013 Dr. Gernot Starke Sample: Credit Card Scoring (1) eCommerce client Credit Card Scoring Server card-info" risk"
56. © 2013 Dr. Gernot Starke 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
57. © 2013 Dr. Gernot Starke Provider company Requester company (heavy) violence... eCommerce client Credit Card Scoring bill 1 2 META-PROCESS 0
58. © 2013 Dr. Gernot Starke Meta-Process... ‣ Human activities before and a er so ware interaction ‣ Consequences: ‣  Financial ‣  Legal ‣  Organizational
59. © 2013 Dr. Gernot Starke Meta-Process... ‣  Veri cation of usage: Legally valid logging ‣  Authorization ‣  Tari , pricing, contract
60. © 2013 Dr. Gernot Starke Meta-Process... ‣ Guarantees: Quality of Service ‣ Versioning ‣ Stakeholder inferno… ‣ <LOUS*> * LOUS: Lot‘s Of Ugly Stuff
61. © 2013 Dr. Gernot Starke 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
62. © 2013 Dr. Gernot Starke 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
63. © 2013 Dr. Gernot Starke Meta-Process requires... governance management
64. © 2013 Dr. Gernot Starke API Management is relevant... API Management is Distinct From SOA Governance API Management Platforms Will Continue To Develop
65. © 2013 Dr. Gernot Starke 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/
66. © 2013 Dr. Gernot Starke API Management is BIG... http://blog.programmableweb.com/2011/10/19/api-service-provider-roundup/
67. © 2013 Dr. Gernot Starke Interfaces advanced Meta- Process basics describing designing
68. © 2013 Dr. Gernot Starke Designing
69. © 2013 Dr. Gernot Starke 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
70. © 2013 Dr. Gernot Starke API == Matter of Taste
71. © 2013 Dr. Gernot Starke Tipps for API design (1) ‣  Beware of meta process ‣  If in doubt, remove it
72. © 2013 Dr. Gernot Starke 8 © 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
73. © 2013 Dr. Gernot Starke Why don‘t we all ... 8 © 2013innoQ Deutschland GmbH ‣ Use Groovy? Or Python? Named param lists are easy
74. © 2013 Dr. Gernot Starke Tipps for API design (2) ‣  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.
75. © 2013 Dr. Gernot Starke Tipps for API design (3) ‣  Start with examples: ‣  Write clients, using your interface ‣  Write tests (TDD philosophy) ‣  Show it to somebody ELSE
76. © 2013 Dr. Gernot Starke 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
77. © 2013 Dr. Gernot Starke e.g. habits, fashions, practices dd / mm / yyyy mm / dd / yyyy km/h, mph liter / 100 km miles / gallon order, unit
78. © 2013 Dr. Gernot Starke Improve Readability
79. © 2013 Dr. Gernot Starke in Practice... JOptSimple, Command Line Parsing Library 98
80. © 2013 Dr. Gernot Starke Interfaces advanced Meta- Process basics describing designing
81. © 2013 Dr. Gernot Starke Documenting
82. © 2013 Dr. Gernot Starke 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!
83. © 2013 Dr. Gernot Starke Options for documenting interfaces 1. RESTful (for web stu ) 2. Intra-app (your own stu ) Very hipp!
84. © 2013 Dr. Gernot Starke Documenting RESTful interfaces (4) ‣  Swagger: produce, visualize & consume RESTful services
85. 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.>
86. © 2013 Dr. Gernot Starke 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
87. © 2013 Dr. Gernot Starke Interfaces in UML
88. © 2013 Dr. Gernot Starke 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
89. © 2013 Dr. Gernot Starke Summary: Documenting interfaces Give small sample of a client. Give more samples. Provide reference... e.g. unit test!
90. © 2013 Dr. Gernot Starke THANX
91. © 2013 Dr. Gernot Starke 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
92. © 2013 Dr. Gernot Starke 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