Share
Embed
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
Dr. Gernot Starke
June 06, 2013
Transcript
99 slides
-
© 2013 innoQ Deutschland GmbH 42 of So ware Interfaces
The Horror of Information Technology Dr. Gernot Starke -
© 2013 innoQ Deutschland GmbH Types of API UI Interfaces
advanced Meta- Process basics describing designing -
© 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 -
© 2013 innoQ Deutschland GmbH Request-Response… API: use Need Have
SPI (Provider Interface) Provider SPI: implement <<implements>> -
© 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 -
© 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 -
© 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! -
© 2013 innoQ Deutschland GmbH Request-Response… API: use Need Have
SPI: implement SPI (Provider Interface) Provider <<implements>> -
© 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 -
© 2013 innoQ Deutschland GmbH SPI (Provider Interface)... My implementation
will work forever! Expectation of implementor! -
© 2013 innoQ Deutschland GmbH SPI (Provider Interface)... My implementation
will work forever! care for compatibility -
© 2013 innoQ Deutschland GmbH SPI (Provider Interface)... care for
compatibility • Don‘t add methods (implementors are not compilable) • Solution: new interfaces... -
© 2013 innoQ Deutschland GmbH Intro (messaging, le-transfer) Message
push or pull Receiver Sender sync or async -
© 2013 innoQ Deutschland GmbH UGYOC* * UGYOC = Urgently
Get Your Own Copy -
© 2013 innoQ Deutschland GmbH Envelope Body Prefix
Body Suffix payload Messages, Files -
© 2013 innoQ Deutschland GmbH Sample: Chess 1. Display 2. Pieces,
Rules... @Stefan Zörner: thx for this idea!" -
© 2013 innoQ Deutschland GmbH Sample: Chess 1. Display ‣
Moves ‣ Position ‣ Timer ‣ User Input ‣ .... -
© 2013 innoQ Deutschland GmbH Sample: Chess 1. Display 2. Pieces,
Rules... ‣ Strength ‣ Color-to-Play ‣ Setup-Position ‣ Restart Game ‣ Selected-Move Chess engine -
© 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)! -
© 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 -
© 2013 innoQ Deutschland GmbH Geocaching... ‣ Request Map ‣
Select „Cache“ ‣ Read description & other people remarks ‣ Find „treasure“ ‣ Send log-entry to central server -
© 2013 innoQ Deutschland GmbH Geocaching... ‣ Requirements: ‣ Works
o line ‣ Multiple device categories -
© 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 -
© 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 -
© 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 -
© 2013 innoQ Deutschland GmbH Interfaces advanced Meta- Process basics
describing designing -
© 2013 innoQ Deutschland GmbH Sample: Credit Card Scoring (1)
eCommerce client Credit Card Scoring Server card-info" risk" -
© 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 -
© 2013 innoQ Deutschland GmbH Provider company Requester company (heavy)
violence... eCommerce client Credit Card Scoring bill 1 2 META-PROCESS 0 -
© 2013 innoQ Deutschland GmbH Meta-Process... ‣ Human activities before and
a er so ware interaction ‣ Consequences: ‣ Financial ‣ Legal ‣ Organizational -
© 2013 innoQ Deutschland GmbH Meta-Process... ‣ Veri cation of
usage: Legally valid logging ‣ Authorization ‣ Tari , pricing, contract -
© 2013 innoQ Deutschland GmbH Meta-Process... ‣ Guarantees: Quality of Service
‣ Versioning ‣ Stakeholder inferno… ‣ <LOUS*> * LOUS: Lot‘s Of Ugly Stuff -
© 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 -
© 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 -
© 2013 innoQ Deutschland GmbH API Management is relevant... API
Management is Distinct From SOA Governance API Management Platforms Will Continue To Develop -
© 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/ -
© 2013 innoQ Deutschland GmbH API Management is BIG... API
Management API Security API Analytics Developer Enablement Tools http://cloudsecurity.intel.com/api-management -
© 2013 innoQ Deutschland GmbH API Management is BIG... API
Analytics http://www.mashery.com/product/features/partner-portal -
© 2013 innoQ Deutschland GmbH Interfaces advanced Meta- Process basics
describing designing -
© 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 -
© 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 -
© 2013 innoQ Deutschland GmbH Tipps for API design (1)
‣ Beware of meta process ‣ If in doubt, remove it -
© 2013 innoQ Deutschland GmbH Tipps for API design (2)
‣ Expect to evolve ‣ Compatibility counts ‣ Source vs Binary compatibility ‣ Develop versioning strategy -
© 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. -
© 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 -
© 2013 innoQ Deutschland GmbH Why don‘t we all ...
6 © 2013innoQ Deutschland GmbH ‣ Use Groovy? Or Python? Named param lists are easy -
© 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. -
© 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 -
© 2013 innoQ Deutschland GmbH pdfutil –e –s 2 3
–f „./_target“ ‣ Option? ‣ Parameter? ‣ Argument? ‣ List? ‣ Pre x? -
© 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 -
© 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 -
© 2013 innoQ Deutschland GmbH Names should reveal intention activate()
deactivate() isActive() registerUser() setActive() getActive() setUser() getUser() Use ubiquitous language -
© 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 -
© 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 -
© 2013 innoQ Deutschland GmbH 7 © 2013innoQ Deutschland GmbH
client Java.util. Date new Date(y, m, d)! valid Date -
© 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“); -
© 2013 innoQ Deutschland GmbH in Practice... JOptSimple, Command Line
Parsing Library 79 -
© 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 -
© 2013 innoQ Deutschland GmbH Interfaces advanced Meta- Process basics
describing designing -
© 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! -
© 2013 innoQ Deutschland GmbH Options for documenting interfaces 1. RESTful
(for web stu ) 2. Intra-app (your own stu ) Very hipp! -
© 2013 innoQ Deutschland GmbH Documenting RESTful interfaces auto-generated, always
up-to-date, stylish documentation -
© 2013 innoQ Deutschland GmbH Documenting RESTful interfaces (2) ‣
SpringDoclet ‣ RestDoclet -
© 2013 innoQ Deutschland GmbH Documenting RESTful interfaces (3) ‣
Apiary.io: API blueprint ‣ DSL for API description ‣ Generates documentation, mock-server . http://apiary.io/blueprint -
© 2013 innoQ Deutschland GmbH Documenting RESTful interfaces (3b) ‣
Apiary.io: API blueprint http://apiary.io/blueprint -
© 2013 innoQ Deutschland GmbH Documenting RESTful interfaces (4) ‣
Swagger: produce, visualize & consume RESTful services -
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.> -
© 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! -
© 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/ -
© 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 -
© 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 -
© 2013 innoQ Deutschland GmbH Summary: Documenting interfaces Give small
sample of a client. Give more samples. Provide reference... e.g. unit test! -
© 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 -
© 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