Just implementing an RESTful API is not enough, to build a sustainable API. You will need a corresponding API Design Strategy.

1. #WISSENTEILEN
Lars Röwekamp | CIO New Technologies | open knowledge GmbH
@_openknowledge
@mobilelarson
API Design
Der ultimative Survivial Guide

2. ÜBER OPEN KNOWLEDGE
Branchenneutrale Softwareentwicklung & IT-Beratung

3. ÜBER MICH
Wer bin ich - und wenn ja, wie viele?
• CIO New Technologies
• Enterprise & Mobile
• Autor, Speaker, Coach & Mentor
• Snowboard & MTB Enthusiast (a.k.a. “stets bemüht“)
Lars Röwekamp (a.k.a. @mobileLarson)

4. #WISSENTEILEN
APIs create new opportunities
APIs sind der Schlüssel zur Erschließung neuer
digitaler Kanäle.
APIs ermöglichen die interne/externe Bereitstellung
von Daten, die Anbindung mobiler Anwendungen
und das Generieren neuer Geschäftsmodell.
“

5. #WISSENTEILEN
It‘s all about Money
Expedia generiert $2 Milliarden jährlich
durch seine Affilliate Networks APIs.
$7 Milliarden der eBay Transaktionen
werden via APIs realisiert.
“

6. #WISSENTEILEN
DX is the new UX
Eine gut designte API ist für den Entwickler
genauso wichtig, wie eine Smart UI für den
Web User.
Eine API sollte intuitive zu verstehen, einfach
zu nutzen und in sich konsistent sein.
“

7. #WISSENTEILEN
Agenda
In 7 Schritten zum
erfolgreichen API Design

8. #WISSENTEILEN
API Design Strategie

9. #WISSENTEILEN
define your
business
objectives
Step #4
Step #7
Step #3Step #2
Step #6
Step #1
Step #5
? ? ?
? ? ?

10. #WISSENTEILEN
define your
business
objectives
Step #1Why do i need an API?
In diesem Schritt betrachtet man das eigene
Business ganzheitlich und nicht nur durch
die Brille einer API.
“

11. #WISSENTEILEN
define your
business
objectives
Step #1Business holistically lens
„Wie lässt sich die Bindung der Kunden zu meinem
Unternehmen verbessern/erhöhen?“
„Wie kann ich meine Partner dabei unterstützen
das Nutzenversprechen gegenüber den Kunden zu
verbessern/auzubauen?“
“Welche internen Prozesse können von dem
vereinfachten Datenzugriff partizipieren?“
“

12. #WISSENTEILEN
define your
business
objectives
Step #1APIs business objectivies
Definiere deine Business Objectives für die API.
Das WARUM deines API Programms.
Stelle sicher, dass diese Business Objectives
messbar sind, um so durch fortlaufende
Optimierung der API langfristigen Erfolg zu
garantieren.
“

13. #WISSENTEILEN
define your
business
objectives
Step #1Answer the WHY
Interner Datenzugriff und Agilität
Interne APIs sind nicht so „sexy“ wie Open APIs -
aber extrem wertvoll.
Verbesserte Kollaboration und Kommunikation kann
die Produktivität um 20-25% erhöhen.*
“
*(Source: by McKinsey)

14. #WISSENTEILEN
define your
business
objectives
Step #1Answer the WHY
B2B / Partner Connectivity
Bereits 2020 wird 40% des Umsatzes der IT
Industrie und 98% des Wachstums durch Dritte
getrieben werden.
“
(Source: Annahme der International Data Cooperation [IDC])

15. #WISSENTEILEN
define your
business
objectives
Step #1Answer the WHY
Mobile Initiativen
Bis 2020 werden Mobile Apps $189 Milliarden
Umsatz generieren ($88 Milliarden in 2016).
Just for the record: Mobile User stellen freiwillig
persönliche Daten via Apps zur Verfügung!
“

16. #WISSENTEILEN
define your
business
objectives
Step #1Answer the WHY
Monetarisierung digitaler Assets
Im digitalen Zeitalter geht der Wert digitaler Daten weit
über den internen Wert hinaus.
Daten sind zu einem Produkt geworden*, das via
APIs zur Verfügung gestellt werden kann.
“
*(65% der CEOs glauben daran, dass Digital Assets ihr Unternehmensergebnis in den kommenden 3 Jahren verbessern werden.)

17. Step #4
?
#WISSENTEILEN
define your
business
objectives
define your
business
model
Step #7
Step #3Step #2
Step #6
Step #1
Step #5
?
? ? ?

18. #WISSENTEILEN
define your
business
model
Step #2I need a business model
Ein passendes Business Model ist extrem wichtig.
Das gewählte Business Modell entscheidet
darüber, ob und wie sich Entwickler auf die API
einlassen und wie sich damit Geld verdienen lässt.
“

19. #WISSENTEILEN
define your
business
model
Step #2I want you money
Entwickler zahlen
Entwickler zahlen für den Service. Typische Modelle:
“pay as you go“, „tiered“ oder „freemium“ (z.B.
Google Maps API - freemium).
“

20. #WISSENTEILEN
define your
business
model
Step #2You want some money?
Entwickler werden bezahlt
Du als API Provider animierst Entwickler Apps oder
Anwendungen auf Basis der eigenen API zu bauen.
Z.B. in Form von Umsatzbeteiligung (z.B.
Amazon‘s Affiliate Program).
“

21. #WISSENTEILEN
define your
business
model
Step #2Come in, it‘s free
Indirekte Monetarisierung
Bei einer indirekten Monetarisierung, dienen die APIs
als Mittelsmann zur Umsatzgenerierung. Die
Nutzung der API wird nicht direkt in Rechnung
gestellt, generiert aber indirekt Umsatz (z.B. eBay
API).
“

22. #WISSENTEILEN
define your
business
model
Step #2Come in, it‘s realy free
Free
Ein freies API Business Modell erlaubt Dritten die
Nutzung der APIs ohne jegliche Kosten. Die
Möglichkeit zur inidirekten Monetarisierung ergibt
sich durch die Generierung von Mehrwerten (z.B
Twitter und Facebook).
“

23. Step #4
?
#WISSENTEILEN
define your
business
objectives
define your
business
model
design your
application
interface
Step #7
Step #3Step #2
Step #6
Step #1
Step #5
? ? ?

24. #WISSENTEILEN
design your
application
interface
Step #3API Design
Beim API Design geht es nicht darum, welche Form
von (Backend) Daten ich zur Verfügung stellen
möchte.
Frage an die potentiellen Nutzer: „Welche Aktionen
möchtest du mit Hilfe der API ausführen /
erreichen können?“
“

25. #WISSENTEILEN
design your
application
interface
Step #3Developer Experience
Designe die API in der Art, dass sie für ihre Zielgruppe
- die Entwickler - einfach und intuitive zu
verstehen, zu nutzen und zu testen ist.
Die wichtigste Frage, die es in dieser Phase zu klären
gilt, ist: „Für wen designe ich die API eigentlich?“
“

26. #WISSENTEILEN
design your
application
interface
Step #3API First
Denke an dieser Phase nicht an die Implementierung der
API. Fokussiere dich ausschließlich auf das Design einer
großartigen API User Experience!
Hole dir Feedback der potentiellen API User während
der Design Phase ein, z.B. via Mock Services.
“

27. #WISSENTEILEN
design your
application
interface
Step #3Iterate on your design
Einmal veröffentlicht wird jede Änderung an der API
direkte Auswirkungen auf die Nutzer haben und ggf
ihre Apps beeinträchtigen.
Gehe erst zur nächsten Phase des Lifecycles über,
wenn du wirklich zufrieden bist und glaubst, du hast das
richtige API Design gefunden.*
“
*API Change Management von Anfang an in das Design mit einbeziehen!

28. #WISSENTEILEN
design your
application
interface
Step #3API Design insides
Führe so früh wie möglich verbindliche API Design
Rules* ein und etabliere diese bei den API Entwicklern.
… später mehr in „Best practices & pitfalls“
“
* Erfinde das Rad nicht neu. Es gibt sehr gute Beispiel in der API Community..

29. #WISSENTEILEN
define your
business
objectives
define your
business
model
design your
application
interface
build and
deploy
your API
Step #4
Step #7
Step #3Step #2
Step #6
Step #1
Step #5
? ? ?

30. #WISSENTEILEN
build and
deploy
your API
Step #4
Connect to the backend
Einmal desinged, muss die API gebaut und mit dem
Backend verbunden werden.
Simple Version: Proxy für existierenden Web Service
Real-Life Version: komplexe Integration / Orchestrierung
“

31. #WISSENTEILEN
build and
deploy
your API
Step #4
Complex integration
Platziere keinen „Custom Code“ innerhalb des
API Layers zur Integration, Orchestrierung oder
Transformation.
Nutze stattdessen „Fit-to-Purpose“ Lösung oder
verwende ein API Gateway, dass die gewünschten
Funktionalitäten von Haus aus liefert.
“

32. #WISSENTEILEN
build and
deploy
your API
Step #4
Policy management
Bevor eine API deployed werden kann, müssen
Policies zu deren Nutzung etabliert werden:
• Security / Authentication
• Rate Limiting / Throtteling
• Customer SLAs
• XML / JSON Threat Protection
“

33. #WISSENTEILEN
build and
deploy
your API
Step #4
Security
Ohne entsprechende Sicherheitsmechanismen sind
die API und die von ihre zur Verfügung gestellten
Daten angreifbar für unerlaubte Zugriffe.
Authentication: präferiere Tokens über Credentials
Authorization: bewillige spezielle Permission-Levels
“

34. #WISSENTEILEN
define your
business
objectives
define your
business
model
design your
application
interface
build and
deploy
your API
Step #4
Step #7
Step #3Step #2
Step #6
Step #1
engage
developers
with your API
Step #5
??

35. #WISSENTEILEN
engage
developers
with your API
Step #5Engage developers
Das Einbinden von Entwicklern und der damit
verbundene erfolgreiche Aufbau einer Entwickler-
Community Ist wahrscheinlich der wichtigste
Erfolgsfaktor des eigenen API Programms.
“

36. #WISSENTEILEN
engage
developers
with your API
Step #5Provide easy access
Der Aufbau einer Entwickler Community beginnt
damit, ein Portal für Entwickler bereitzustellen, dass
ihnen ein „Entdecken“ der API ermöglicht.
Entwickler können die API so für ihre Use Cases und
Anwendungswelt evaluieren.
“

37. #WISSENTEILEN
engage
developers
with your API
Step #5
Self-Service Support Hub
Trust Signal
Communication Nexus
Documentation Database
DevRel Tool
Product und Implementation Showroom
API
API
API
…
Stakeholder
Stakeholder
Stakeholder
Stakeholder
…
What is a Dev Portal?
“

38. #WISSENTEILEN
engage
developers
with your API
Step #5
I have a question
„Was genau ist der Zweck der API?“
„Wie starte ich am besten mit der API?“
„Was muss ich bzgl. der API verstanden haben?“
„Wie erledige ich Aufgabe X mit Hilfe der API?“
„Wie komme ich an die Details der API ran “
„Wie nutze ich die API im Falle von Y?“
„Arbeitet überhaupt jemand mit der API?“
„An wen wende ich mich im Falle von Fragen/Problemen?“
„Wie erhalte ich Zugriff auf die API?“
„Kann ich mir die API leisten und ihr trauen?“
“

39. #WISSENTEILEN
engage
developers
with your API
Step #5
We have the answers*
Getting Started
Dokumentation
Code Beispiele
Interaktive Dokumentation
Error Codes und Responses
Forums
FAQs
API Status
“
*(ProgrammableWeb: nur 1% von 11,000 APIs bieten die gesamte Namdnreits)

40. #WISSENTEILEN
Step #5
Developers journey
“ #1: discover & research
#2: evaluate API features
#3: get started with dev
#4: dev/troubleshoot
#5: celebrate
#6: maintain
engage
developers
with your API

41. #WISSENTEILEN
Step #5
How do I get started?
“ engage
developers
with your API
Tutorials
Tutorials helfen den
Entwicklern dabei,
erfolgreich die ersten
Schritte mit der API
zu gehen
„Reading to learn to do“
Prinzip.

42. #WISSENTEILEN
Step #5
How do I get X done?
“ engage
developers
with your API
Guides
Guides erklären anhand
von Use Cases, Rezepten
oder Cookbooks, wie
konkrete Probleme und
Herausforderung zu lösen
sind.

43. #WISSENTEILEN
Step #5
Still working on it?
“ engage
developers
with your API
Blogs
Blogs können regelmäßig
(neue) Lösungen
kommunizieren und dabei
helfen neuen Content zu
verproben.

44. #WISSENTEILEN
Step #5
Dev Portal v0.1 (MVP)
“ engage
developers
with your API

45. #WISSENTEILEN
Step #5
Dev Portal v0.1 (MVP)
“ engage
developers
with your API

46. #WISSENTEILEN
Step #5
Dev Portal v0.5
“ engage
developers
with your API

47. #WISSENTEILEN
Step #5
Dev Portal v0.5
“ engage
developers
with your API

48. #WISSENTEILEN
Step #5
Dev Portal v1.0
“ engage
developers
with your API

49. #WISSENTEILEN
Step #5
Dev Portal v1.0
“ engage
developers
with your API

50. engage
developers
with your API
#WISSENTEILEN
Step #5
inspired by findings of
Peter Greenbaum
and Kata Nagygyörgy
Overview
What is the API about?
How does the API work?
Getting started
How can i start integrating?
Sample code
How can i start integrating?
Help & Support
Trust signal
Can I trust this API?
References
How can is start …?
Search function
Where can i find …?
Menu / in-links
Where can i find …?
The Landing Page
“

51. #WISSENTEILEN
engage
developers
with your API
Step #5From Dev to Dev
Promote deine API zielgruppengerecht und
glaubwürdig via Developer Evangelists.
Organisiere Hackathons*, um die Starthürde(n)
zu minimieren und interessierte Entwickler
zusammenzubringen.
“
*Salesforce Hackathon mit 1 Mio $ Preisgeld

52. #WISSENTEILEN
engage
developers
with your API
Step #5Eat your own dog food
Das Verständnis und die Akzeptanz für (d)eine API
beginnt in den eigenen Reihen.
Jeff Bezos: “Every application leveraging enterprise
data or services must go through an API – no back
doors are available.“
“
*Jeff Bezos, Amazon.com:

53. #WISSENTEILEN
define your
business
objectives
define your
business
model
design your
application
interface
build and
deploy
your API
Step #4
Step #7
Step #3Step #2
manage and
monitor
your API
Step #6
Step #1
engage
developers
with your API
Step #5
?

54. #WISSENTEILEN
manage and
monitor
your API
Step #6What‘s going on?
Sobald eine API zur Verfügung gestellt wird, wird auch
Managing und Monitoring notwendig, so dass …
… Fehler schnell identifiziert werden können
… potentielle Probleme antizipiert werden können
… Nutzung und Performanz gemessen werden können
“

55. #WISSENTEILEN
manage and
monitor
your API
Step #6
What to look at?
Operational Level Metrics als „Lebenszeichen“ der
API: z.B. API Status, Response Times, Up-/Downtimes.
Functional Level Metrics für einen tiefen Einblick in die
Verwendung der API als Basis zur Optimierung: z.B.
Consumption by Region / by Platform, Traffic by
Consumer, …
“

56. #WISSENTEILEN
manage and
monitor
your API
Step #6
Abstraction layer
Ein API Gateway erlaubt es der API Runtime sich
mit den Backend Services zu verbinden und dient
als Abstraction Layer.
Durch Nutzung von Caching und Routing Features,
können API Publisher hohe Verfügbarkeit und
schnelle Response-Zeiten garantieren.
“

57. #WISSENTEILEN
define your
business
objectives
define your
business
model
design your
application
interface
build and
deploy
your API
Step #4
measure
the impact
of your API
Step #7
Step #3Step #2
manage and
monitor
your API
Step #6
Step #1
engage
developers
with your API
Step #5

58. #WISSENTEILEN
measure
the impact
of your API
Step #7Are we successful?
Deine API lebt und atmet als Teil deines Business;
und sollte daher permanent verbessert werden.
API Publisher sollten in regelmäßigen Abständen den
„Erfolg“ des eigenen API Programms kritisch
hinterfragen und ggf das Programm korrigieren.
“

59. #WISSENTEILEN
measure
the impact
of your API
Step #7Review the success
Wird das Programm angenommen, wie
erwartet / erhofft? Liefert das Programm den
erwarteten Umsatzzuwachs / Mehrwert?
Wenn nicht, ist es Zeit zu hinterfragen, was die API
liefert/bietet, wie sie designed ist, wie sie beworben
wird oder ob das Business Modell evtl nicht passt.
“

60. #WISSENTEILEN
measure
the impact
of your API
Step #7Goals and needs change
Ziele und Bedürfnisse ändern sich. Daher muss
permanent hinterfragt werden, ob die API nach wie
vor das liefert, was mein Business ausmacht!
“

61. #WISSENTEILEN
define your
business
objectives
define your
business
model
design your
application
interface
build and
deploy
your API
Step #4
measure
the impact
of your API
Step #7
Step #3Step #2
manage and
monitor
your API
Step #6
Step #1
engage
developers
with your API
Step #5

62. API Design ohne Stress?
Halte dich an die goldenen Regeln!

63. #WISSENTEILEN
Golden Rules of API DESIGN (business)
#1: definiere deine Business Objectives
#2: designe für eine herausragende User Experience
#3: ermögliche einen einfachen Zugriff
#4: baue eine Community auf und pflege diese
“

64. #WISSENTEILEN
Golden Rules of DESIGN (tech)
#1: sei konsistent
#2: sei flexibel
#3: sei erweiterbar
#4: vermeide Versionierung
“

65. #WISSENTEILEN
Pro Tipp of the Day
„The web and it‘s standards are your friends.
Do not reinvent the wheel!“
“

66. #WISSENTEILEN
? ? ?

67. Lars Röwekamp, @mobileLarson
Kontakt:
lars.roewekamp@openknowledge.de
kontakt@openknowledge.de
Besten Dank! #WISSENTEILEN

68. Kontakt
LARS RÖWEKAMP
CIO NEW TECHNOLOGIES
lars.roewekamp@openknowledge.de
+49 (0)441 4082 – 101
@mobileLarson
@_openknowledge
OFFENKUNDIGGUT
#WISSENTEILEN