Intuitive API design is a critical success factor for APIs. API-First propagates a collaborative approach, where API development starts with the design and brings various stakeholders together, which dramatically increases efficiency and consistency while defining APIs. Questions that that come up in this area are about quality requirements APIs have to meet nowadays, in order to deliver the desired business value. In this session we want to present an approach how APIs can be defined and implemented consistently using tools like Apiary and Apimatic and the design artifacts can be incorporated in existing CI/CD pipelines, using tools like Dredd, since APIs are a first-class citizen which need to be maintained appropriately.

1. © OPITZ CONSULTING 2018
s
¢¢¢ überraschend mehr Möglichkeiten!
© OPITZ CONSULTING 2018
Basis for an consistent API-Management
approach
Sven Bernhardt, Danilo Schmiedel
API-First-Design

2. © OPITZ CONSULTING 2018 Seite 2
Agenda
1
2
3
5
API Management - Why?
API-First
Design Considerations
Summary
API-First-Design
4 API-First tools support

3. © OPITZ CONSULTING 2018 API-First-Design Seite 3
OPITZ CONSULTING - A success story since 1990
¢ Our Mission: Help organizations to leverage the possibilities of
digitalization to be different, better and faster than their competitors
¢ Owner-led company with
¢ 400+ consultants
¢ 11 locations in Germany and Poland
Danilo Schmiedel
¢
¢ Senior Managing Consultant
¢ Business Development and Innovation
¢ Lead for Competence Center Cloud
About us
Sven Bernhardt
¢ Solution Architect
¢ Technical Lead for API Management

4. © OPITZ CONSULTING 2018 Seite 4
API Management - Why?
1
API-First-Design

5. © OPITZ CONSULTING 2018 API-First-Design Seite 5
This is why APIs do really matter today!
¢ Today there are more than 12.000 APIs offered by companies
Generate 90% of its revenue
through APIs
APIs allow people to use third-
party websites to tap Expedias
functionality in order to book
flights, cars, and hotels
Generate 60% of its revenue with
APIs
APIs allow eBay to list its auctions
on other websites, get bidder
information about sold items,
collect feedback on transactions,
and list new items for sale
Generate 50% of its revenue with
APIs
Salesforce.com has a
marketplace (AppExchange) for
apps created by its partners that
work on its platform; they now
number more than 300
Source: https://hbr.org/2015/01/the-strategic-value-of-apis

6. © OPITZ CONSULTING 2018 Seite 6
APIs are the doors of the digital tomorrow
¢ Providing access to an enterprises services and data
¢ Support Key Business Goals
¢ Revenue Growth
¢ Customer Satisfaction & Engagement
¢ Operational Efficiency
¢ Partner Contribution & Ecosystem
Source: Pinterest
APIs are used to discover new business models
and to evolve new digital economies!
IMPORTANT
API-First-Design
Source: www.programmableweb.com

7. © OPITZ CONSULTING 2018 API-First-Design Seite 7
Unleash the power of APIs with consistent
API Management
¢ Avoid uncontrolled usage
¢ Improve agility & quickly meet customer
demand with innovative services
¢ Ensure security of digital assets
¢ Gain visibility & define the right metrics to
meet business goals
¢ Dimensions of API Management
¢ Community Management
¢ API Lifecycle Management
¢ API Operations
¢ API Security
Planning
Design
Implementation
Publication
Operation
Consumption
Maintenance
Retirement
API
Lifecycle
API-First supports
especially those
lifecycle phases!

8. © OPITZ CONSULTING 2018 Seite 8
API-First
2
API-First-Design

9. © OPITZ CONSULTING 2018 API-First-Design Seite 9
Is API-First not just simply Contract-First?
¢ No, because API-First is a methodology and kind of a culture
¢ API-First means:
¢ Define the APIs before you start coding
¢ What are the business goals resp. capabilities your API supports?
¢ Who are your API consumers and how will they use the API (API UX)?
¢ Create the APIs collaborativelly
¢ Bring different API stakeholders together
¢ Shared responsibility for API definitions
¢ Decouple development
¢ Frontend from backend
¢ API from backend
¢ API from from frontend
¢ Rapid development result and short feedback cycles
Significant mindset change:
Technical API focus to
Business focus!
Significant cultural change:
Individual responsibility to
collabrative approach

10. © OPITZ CONSULTING 2018 API-First-Design Seite 10

11. © OPITZ CONSULTING 2018 API-First-Design Seite 11
Questions before you start to design your API
¢ How can we
¢ discover and explore APIs?
¢ access APIs?
¢ build software on top of APIs?
¢ test APIs?
¢ monitor APIs (SLAs)?
¢ switch to a new version of an API?
Consumer Provider
¢ What is the purpose / value add?
¢ single-purpose vs. multi-purpose
¢ backend or frontend
¢ pass-through or new facade
¢ Who is our consumer (today and in
the future)?
¢ How can we
¢ document and describe APIs?
¢ make sure that consistent style guides
are considered and applied?
¢ publish & expose APIs?
¢ implement APIs?
¢ operate APIs?
¢ provide new versions of an API?

12. © OPITZ CONSULTING 2018
Strategies for Efficient Delivery with APIs, Containers,
Microservices, DevOps
Seite 12
OPITZ CONSULTING - A success story since 1990
¢ Mission: Help organizations leverage the possibilities of digitalization to be
different, better and faster than their competitors
¢ Owner-Managed company with
¢ 400+ consultants at 11 locations in DE and PL
¢ Revenue 2016: 47 Mill. €
Danilo Schmiedel
¢
¢ Managing Consultant
¢ Lead for Competence Center Cloud
About us
Sven Bernhardt
¢ Solution Architect
¢ Technical Lead for API Management

13. © OPITZ CONSULTING 2018 API-First-Design Seite 13
Use Case 1:
API-First Design allows rapid development results
Phase 1 Phase 2
ü Finalized definition of the single-purpose APIs on day two in a
collaborative way with Apiary
ü Independent development of Mobile app, Mobile Backend, Backend
Service and API
ü Problem: Connectivity to the backend system, because Firewall
changes took too long (4 weeks project duration, connectivity was
available in week 3)
ü Development team was not blocked because implementation of the
mobile app was done against the Mock Server functionality in Apiary
Integration
CS
Mobile CS

14. © OPITZ CONSULTING 2018 API-First-Design Seite 14
Use Case 2:
API-First Design decouples frontend and backend dev

15. © OPITZ CONSULTING 2018 API-First-Design Seite 15
Use Case 3: API-First and Microservices Persistence
(PVS)
Service Implementation
(fully-decoupled)
APIs
Service
Implementation
(semi-decoupled)
CRM
Project
Managem
ent
HR
Financials
Controllin
g
Validation
Authentication
Throttling
Routing
Transform
Orchestrate
{json}
{json}
{json}
<<Microservice>>
Time
Management
Filtering
{json}
<<Microservice>>
Canteen
Management Connect
{json}
{json}
{jdbc}
Security
API
PlatformCS

16. © OPITZ CONSULTING 2018 Seite 16
Design Considerations
3
API-First-Design

17. © OPITZ CONSULTING 2018 API-First-Design Seite 17
No APIs without an API-First Design approach
¢ How will consumers use the API?
¢ Business APIs need to be easily understandable and appropriate for the
respective use case, e.g. don’t use SOAP interfaces for Mobile
¢ API Design rules allow the creation of consistent APIs, which improves
Developer Experience (DX) and results
¢ Build early, lightweight prototypes to verify your API
¢ Design assumptions can be validated based on the target persona
¢ Changes can be made easily, because the API is not bound to real data
¢ Short Feedback cycles
¢ From App Developers to API Designers
¢ From API Owners to App Developers

18. © OPITZ CONSULTING 2018 API-First-Design Seite 18
No APIs without an API-First Design approach (2)
ü Keep it short: Start with a very short spec (One-Pager)
ü Names matter: Good Names drive Development
ü Agility before completeness: send spec to as many people as possible get the
feedback and learn
ü Many APIs are over-constrained: API should do one thing and do it well
ü Start coding as early as possible use mockups and establish a continuous
testing approach (before you implement the API completely)
ü Improve and finalize as soon as you are confident
ü Implementation should not impact the API (e.g. Exception details should be on
the same level of abstraction as the rest of the API)
ü Consider performance impact (bad decisions can limit performance)

19. © OPITZ CONSULTING 2018 API-First-Design Seite 19
API Style Guides
¢ APIs should be…
ü easy to use (even without documentation)
ü hard to misuse (force to do the right thing)
ü easy to use and maintain code that uses it
ü satisfy the requirements (common is good, avoid over-engineering)
ü easy to evolve
ü appropriate to the consumers
ü designed consistently

20. © OPITZ CONSULTING 2018 API-First-Design Seite 20
API Style Guides * Documentation matters
¢ Learn from others: https://www.gitbook.com/book/adidas-group/api-
guidelines/details
¢ Define your API Guidelines
¢ Core Principles
¢ Protocol (protocol-level semantics and guidelines)
¢ Message (message format governance)
¢ Application (Data Model & Types)
¢ Evolution (testability, maintainability, extensibility, and scalability)
¢ Execution (security and usability, which are observable at run time)
¢ Clients (practices for API consumers–clients)
¢ Examples

21. © OPITZ CONSULTING 2018 API-First-Design Seite 21
API description dialects
¢ WADL
¢ RAML
¢ Swagger
¢ Open API
¢ API Blueprint

22. © OPITZ CONSULTING 2018 Seite 22
API-First tools support
4
API-First-Design

23. © OPITZ CONSULTING 2018 API-First-Design Seite 23
API Tools & Platforms (just an extract…)
Source: https://techcrunch.com/2016/05/21/the-rise-of-apis/

24. © OPITZ CONSULTING 2018 API-First-Design Seite 24
Classes of tools that support API-First
¢ API Catalog (or Developer Portal)
¢ Central place for all APIs
¢ Consolidated Authentication / Authorization Handling hiding your internal complexity
¢ Central Traffic Management
¢ Monitoring, Alerts and Insights into API Consumption
¢ a consolidated way to register and onboard Consumers
¢ API Versioning Strategys
¢ Support, Helpdesk for Consumers
¢ API Design Platform
¢ ....

25. © OPITZ CONSULTING 2018 API-First-Design Seite 25
API Catalog: Apigee

26. © OPITZ CONSULTING 2018 API-First-Design Seite 26
API Catalog: Oracle

27. © OPITZ CONSULTING 2018 API-First-Design Seite 27
API Design Platforms: Apiary
¢ Apiary supports Design First approach
¢ Github integration
¢ Supported different API description dialects:
¢ API Blueprint
¢ Swagger
API as a by-
product of
building apps
API
documentation
generated
from code
Design-first
API
Development
API Design
Consistency

28. © OPITZ CONSULTING 2018 API-First-Design Seite 28
API Design Platforms: Apiary

29. © OPITZ CONSULTING 2018 API-First-Design Seite 29
API Design Platforms: SwaggerHub
¢ Online platform, but can also be hosted locally
¢ Supports different Swagger versions (Swagger 2.0, Open API (Swagger 3.0)
¢ Direct API mocking
¢ Generator for Client and Server Code, supporting different programming
languages

30. © OPITZ CONSULTING 2018 API-First-Design Seite 30
API Design Platforms: SwaggerHub

31. © OPITZ CONSULTING 2018 Seite 31
Summary
5
API-First-Design

32. © OPITZ CONSULTING 2018 API-First-Design Seite 32
Closing remarks
¢ API management is important because
¢ it is crucial to the success of the digital transformation
¢ it enables new digital business models
¢ it helps to develop the new digital economy
¢ No APIs without
¢ proper API Management
¢ proper Business Alignment
¢ proper API-first design approach
¢ API Management does not replace an integration platform
¢ Provide your API implementations using the most appropriate
technologies
¢ So, the question shouldn‘t be if, but when to start!

33. © OPITZ CONSULTING 2018 API-First-Design Seite 33
API Management is essential for modern IT architectures
¢ Accelerating innovation by building up next-gen apps based on modern
concepts like Mircoservices, DevOps, Cloud and APIs
¢ Thrive new digital economies and enable new business models
Future-oriented Architectures
for Human-Machine-Interaction
Holistic End2End Integration
Architectures
Analytical Applications &
Business Insights
Reactive, hybrid Infrastructure
Architectures

34. © OPITZ CONSULTING 2018 API-First-Design Seite 34
Download: http://tinyurl.com/ydfdyqq9

35. © OPITZ CONSULTING 2018 Seite 35API-First-Design
Q & A

36. © OPITZ CONSULTING 2018
¢¢¢ überraschend mehr Möglichkeiten!
@OC_WIRE OPITZCONSULTING opitzconsultingWWW.OPITZ-CONSULTING.COM
Seite 36
Contact us!
Danilo Schmiedel
Senior Managing Consultant Solutions | Oracle ACE Director
OPITZ CONSULTING Deutschland GmbH
Tempelhofer Weg 64, 12347 Berlin, Germany
Phone: +49 173 7279001
Mail: danilo.schmiedel@opitz-consulting.com
@dschmied
http://inside-bpm-and-soa.blogspot.com
Sven Bernhardt
Solution Architect | Oracle ACE
OPITZ CONSULTING Deutschland GmbH
Kirchstrasse 6, 51647 Gummersbach, Germany
Phone: +49 172 2193529
Mail: sven.bernhardt@opitz-consulting.com
@sbernhardt
https://svenbernhardt.wordpress.com
API-First-Design