Intuitive APIs are critical success factors for modern software architectures. APIs should be easy to use, difficult to misuse, consumer friendly, easy to maintain and consistently designed. In order to achieve these goals, it is important to develop APIs before starting the actual development and in a collaborative approach involving various stakeholders. The API-first design approach is important when it comes to exposing existing functionality in the enterprise, e.g. implemented as microservices, to the outside world. But what role do APIs play in microservice architectures? How are APIs and microservices implementations combined and how do I integrate this with a DevOps approach? These questions will be answered in this session and explained on a consistent Microservice example. From a tooling perspective I leverage the power of Oracle Cloud with tools like Apiary, Oracle Kubernetes Engine (OKE), Wercker (aka Container Pipelines) and Oracle Container Registry.

1. © OPITZ CONSULTING 2018
s
¢¢¢ überraschend mehr Möglichkeiten!
© OPITZ CONSULTING 2018
Meaning for µService architectures
Sven Bernhardt
API design-first

2. © OPITZ CONSULTING 2018 API design-first Seite 2
About me
Sven Bernhardt
¢ Senior Solution Architect @OPITZ CONSULTING Deutschland GmbH
¢ Oracle ACE Director
@sbernhardt
https://svenbernhardt.wordpress.com/

3. © OPITZ CONSULTING 2018 Seite 3
Agenda
1
2
3
5
APIs today
µServices and APIs
API design-first
Summary
API design-first
4 API life cycle

4. © OPITZ CONSULTING 2018 Seite 4
Once upon a time
1
API design-first

5. © OPITZ CONSULTING 2018 API design-first Seite 5
Meaning of APIs today
¢ Today we have more than 22.000 APIs offered by different companies from
different industries
https://www.programmableweb.com/news/apis-show-faster-growth-rate-2019-previous-years/research/2019/07/17

6. © OPITZ CONSULTING 2018 API Management: Why it matters! Seite 6

7. © OPITZ CONSULTING 2018 API design-first Seite 7
Application architectures in traditional industries
¢ Contains a set of business functionality,
often implemented as modules
¢ Sharing infrastructure resources
¢ Database
¢ Storage
¢ CPU
¢ Memory
¢ Simple communication between the
modules
¢ Each module has access to all data
ERP
HR
PPM
SCM
Financials
Monolithic application architecture
Business
Capabilities

8. © OPITZ CONSULTING 2018 API design-first Seite 8
Bi-modal IT – Two speed IT to further innovation
Agility
Innovation
Effectivity
Competitive advantages
Compliance
Efficiency
Standardization
Differentiation
Innovation
New ideas
Better ideas
Tipical ideas
Customer-specific solutions
Standard Software solutions
Systems of Innovation
Systems of Differentiation
Systems of Record
Based on Pace Layered Application Strategy, Gartner 2012
Non-linear IT
§ Not sequential
§ Agile
§ Fast
§ Innovation
§ Disturbance
Traditional IT
§ Security
§ Efficiency
§ Accuracy
§ Tranquility

9. © OPITZ CONSULTING 2018 Seite 11
µServices and APIs
2
API design-first

10. © OPITZ CONSULTING 2018 API design-first Seite 12
APIs as a central architecture element
Seite 12
User Experience
Service Implementation
Persistence
Web Mobile DeviceMonitoring
BusinessAnalytics
Security
Management
Monolithic System RegistryEvent StoreShared Storage
Non-shared
Storage
Semi-decoupled Fully-decoupled
http://omesa.io
API

11. © OPITZ CONSULTING 2018 API design-first Seite 13
Microservices - Organize applications into Business capabilities
¢ Flexibility
¢ Independently releasable
¢ Technologies
¢ Platform
¢ Scalable
¢ Fault tolerant & robust
¢ Decoupled development
¢ Dedicated responsibility and ownership
Microservices are no silver bullets!
IMPORTANT
ERP
HR
PPM
SCM
Financials
µEmployees

12. © OPITZ CONSULTING 2018 API design-first Seite 14
APIs - Access business capabilities in a secure way
¢ Describes how consumers can use a business capability
¢ Provides a standard-based interface for accessing the
functionality
¢ Decouples Consumer and Provider
¢ Implements cross-cutting concerns, declared as policies
¢ AuthN/AuthZ
¢ Throttling/Rate Limit
¢ Routing
¢ Caching
¢ …
¢ Policy enforcement done by a specific runtime component
µEmployees
API
API Gateway

13. © OPITZ CONSULTING 2018 API design-first Seite 15
Focus on API Consumers
¢ Main goal: Build consistent and easy-to-use APIs!
¢ Support of different types of consumers (i.a.
introduce Single Purpose APIs)
¢ Development approach needed to support
collaboration already in an early stage:
¢ Decoupled development
¢ Quick feedback cycles
¢ API Mocking
Employees
Storage
µEmployees
µEmployees
Backoffice
API
API Gateway

14. © OPITZ CONSULTING 2018 API design-first Seite 16
Focus on API Consumers
¢ Main goal: Build consistent and easy-to-use APIs!
¢ Support of different types of consumers (i.a.
introduce Single Purpose APIs)
¢ Development approach needed to support
collaboration already in an early stage:
¢ Decoupled development
¢ Quick feedback cycles
¢ API Mocking
Employees
Storage
µEmployees
µEmployees
Backoffice
API
µEmployees
Mobile
BFF
API
µEmployees
SelfService
App
API Gateway

15. © OPITZ CONSULTING 2018 Seite 17
API design-first
3
API design-first

16. © OPITZ CONSULTING 2018 API design-first Seite 18
What is design?
Design is a collaborative process!
Source: https://ytiffanie.wordpress.com/danish-design/what-is-design/

17. © OPITZ CONSULTING 2018 API design-first Seite 19
API design-first approach
Feedback
Feedback
Intuitive, consistent API design is
key for API acceptance!
IMPORTANT

18. © OPITZ CONSULTING 2018 API design-first Seite 20
API life cycle
Design
Mock
Try
Create/configureDeploy
Promote,
deprecate, retire
Observe
API ideation &
planning
API life cycle as proposed by Luis Weir
(@luisw19) in his book „Enterprise API
Management“

19. © OPITZ CONSULTING 2018 Seite 21
API life cycle
4
API design-first

20. © OPITZ CONSULTING 2018 API design-first Seite 22
Tools supporting an API first design approach
Design Try
Create/
Configure
Deploy Observe
Feedback
Oracle API
Platform
Mock

21. © OPITZ CONSULTING 2018 API design-first Seite 23
API design-first
¢ Define your API specification collaboratively
¢ Approach helps to ensure usable API Design (UX)
¢ API spec is for API what Wireframes are for UIs!
¢ Tooling should support collaboration (e.g. by providing Git integration)
¢ Support for at least Open API specification; alternatives:
¢ API Blueprint
¢ RAML
¢ WADL

22. © OPITZ CONSULTING 2018 API design-first Seite 25
API description dialects: How to decide?
¢ Different specifications available with different focus,
representational styles
¢ As always: It depends!
¢ Which use case?
¢ What is the intention?
¢ Team skills?
¢ BUT: You‘re not trapped, if you decide for a dialect!
¢ APIMATIC helps with converting between the dialects
¢ Alternatives: Local tools like „api-spec-converter“ (Node-based)

23. © OPITZ CONSULTING 2018 API design-first Seite 26
Mock, try and collect for feedback
¢ Provide an API mock very early and without lots of effort
¢ Ideally without coding and deployment
¢ Mock should be easily adjustable in case of feedback and respective changes
¢ Always try to provide representative Mock data, so that API consumers can test it accordingly
¢ Exposing an API Mock with an API Gateway, can help to understand API usage
¢ Share information about the Service Mock with potential API consumers and
developers
¢ Ask for feedback
¢ Take the feedback serious

24. © OPITZ CONSULTING 2018 Seite 27
Demo – Design with Apiary
API design-first

25. © OPITZ CONSULTING 2018 API design-first Seite 28
Create and configure the API
¢ Scaffold Client/Server code, e.g by generating Code based on the IDL
¢ Create APIs metadata and documentation (API page)
¢ Define API version
¢ Create API policies
¢ AuthN/AuthZ
¢ Throttling/Rate limit
¢ Key validation
¢ etc.

26. © OPITZ CONSULTING 2018 API design-first Seite 30
Automate as much as possible
¢ Automate as much as as possible (Build, test, deployment, infrastructure)
¢ Define a consistent Build/Deployment process
¢ Make use of respective automation tools like Jenkins or Wercker
Pull Inspect
Build &
Package
QA Deploy Rollback
1 2 3 4 5 6
1) Checkout Sourcecode
2) Inspect Code and it‘s dependencies
3) Compile, package the Code and publish into an Artefact
repository
4) Quality assurance by conducting tests (Interface,
Functional, Performance, etc.)
5) Deploy to target environment (e.g. Production)
6) Rollback a previous deployment in case of issues with
certain components

27. © OPITZ CONSULTING 2018 API design-first Seite 31
API Interface testing is key to ensure consistency
¢ Ensure that the implementation adheres to the API design
¢ Correct payload information
¢ Correct HTTP responce codes
¢ Defined HTTP ressources available
¢ Dredd is a lightweight Open-Source HTTP testing framework
¢ Runs against a Backend service
¢ Test are based on the definitions in the API design (Swagger or API Blueprint)

28. © OPITZ CONSULTING 2018 API design-first Seite 32
View Dredd test results in Apiary

29. © OPITZ CONSULTING 2018 Seite 33
Demo – Interface testing with Dredd
API design-first

30. © OPITZ CONSULTING 2018 API design-first Seite 34
Functional and Performance testing
¢ Post-deployment tests of the integrated solution needs to be done ideally using
(semi) automated tests
¢ Run predefined tests from a tests, which describes the expected behaviour of a
certain operation
¢ Run more complex workflow tests
¢ Run performance & stress tests

31. © OPITZ CONSULTING 2018 API design-first Seite 35
Torch the light - See what‘s going on
¢ Observability is key in modern, distributed IT system landscapes
¢ Important to identify potential issues or bottlenecks
¢ Absolutely necessary to ensure SLA conformity
¢ Try to get as much insights as possible by externalizing as much information as
possible
¢ Different levels to track:
¢ API monitoring
¢ Service monitoring
¢ End-to-end monitoring
¢ Log analytics
¢ Application Performance monitoring
¢ Distributed Tracing

32. © OPITZ CONSULTING 2018 Seite 36
Summary
5
API design-first

33. © OPITZ CONSULTING 2018 API design-first Seite 37
Summary
¢ Consistent DevOps approach is key to succeed with µServices & APIs
¢ It’s not just about technology and tools
¢ Strives culture, organization and people
¢ Mindshift change is needed, to successfully implement the approach
¢ Attitude: “From suit to hoodie wearer”
¢ Mentality: “Be ready to fail, adjust and try again”
¢ API design-first approach is essential to implement usable APIs
¢ Not limited to REST; also valid to other Interface definition languages (IDL)
¢ Integrates with existing CI/CD approaches
¢ Prerequisite to grow and further innovation

34. © OPITZ CONSULTING 2018 API design-first Seite 38
Links & Resources
¢ Apiary: https://apiary.io
¢ API conversions: https://apimatic.io
¢ Dredd HTTP testing: http://dredd.readthedocs.io/en/latest/
¢ Wercker: http://www.wercker.com
¢ API Fortress: https://apifortress.com
¢ API Fortress Data sheet: https://bit.ly/2OQNjVP
¢ Book: Enterprise API Management (Luis Weir, 2019)

35. © OPITZ CONSULTING 2018 Seite 39API design-first
Q & A

36. © OPITZ CONSULTING 2018
¢¢¢ überraschend mehr Möglichkeiten!
@OC_WIRE OPITZCONSULTING opitzconsultingWWW.OPITZ-CONSULTING.COM
Seite 40
Thanks for your attention!
Sven Bernhardt
Senior 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 design-first