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. This 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 API and Microservice implementations combined and how do I integrate them with a DevOps approach? Questions answered in this session. A holistic development approach starting with API development up to the deployment of a microservice is considered. Tools such as Oracle Apiary, which support an API-first design approach or Oracle Wercker for the automation of build and deployment, will be presented.

1. © OPITZ CONSULTING 2018
s
¢¢¢ überraschend mehr Möglichkeiten!
© OPITZ CONSULTING 2018
Significance for µServices Architectures
Sven Bernhardt, Danilo Schmiedel
API-First-Design

2. © OPITZ CONSULTING 2018 API-First-Design Seite 2
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
¢ 450+ consultants
¢ 11 locations in Germany and Poland
Danilo Schmiedel
¢
¢ Senior Managing Consultant
¢ Business Development and Innovation
About us
Sven Bernhardt
¢ Senior Solution Architect
¢ Technical Lead for API Management

3. © OPITZ CONSULTING 2018 Seite 3
Agenda
1
2
3
5
Use Case introduction
µServices and APIs
API first Design
Summary
API-First-Design
4 Continuous Software delivery

4. © OPITZ CONSULTING 2018 Seite 4
Use Case introduction
1
API-First-Design

5. © OPITZ CONSULTING 2018 API-First-Design Seite 5
Example µService Architecture: Webshop
¢ Requirements:
¢ Agility: Quickly respond to changing/new market requirements
¢ Extensibility: Easily evolve the platform with new functionality
¢ Scalability: Flexible handling of increasing workloads
¢ Availibility: Zero-downtime tolerance with respect to the complete webshop platform
µ
Customers
µ
Orders
µ
Products
µ
Loyalty
µ
Finance
µ
Logistics
Web Shop Portal
Micro-UIs
µ
Customers
µ
Orders
µ
Products
µ
Loyalty
µ
Finance

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

7. © OPITZ CONSULTING 2018 Seite 7
µServices and APIs
2
API-First-Design

8. © OPITZ CONSULTING 2018 API-First-Design Seite 8
Why µServices?
¢ Flexibility
¢ Independently releasable
¢ Technologies
¢ Platform
¢ Scalable
¢ Fault tolerant & robust
¢ Decoupled development
¢ Dedicated responsibility and
ownership
Microservices are no silver bullets!
IMPORTANT

9. © OPITZ CONSULTING 2018 API-First-Design Seite 9
What service granularity to choose?
¢ It doesn’t matter in a first step, because there is no definitive solution,
because of changes in
¢ Organizations
¢ Business objectives
¢ Technology Frameworks
¢ Regulations
¢ Get started quickly with a first idea of Bounded Context, APIs, etc.
¢ Service cut is not carved in stone and needs revision in every iteration
#doneisbetterthanperfect
#stopdiscussingstartdoing
#embracechange

10. © OPITZ CONSULTING 2018 API-First-Design Seite 10
Which technology platform to use?
¢ Technology platform is not significant, even though it‘s important to
keep it flexible and exchangeable
¢ Focus should be on the Business challenges that should be solved
¢ More instances is better than bigger instances (Horizontal scaling)
¢ More resiliency
¢ Better elasticity
Main objective µServices:
Sustainable manageable agility in functionality and non-functionality (scale, performance,
location, availability, ..) - with optimal cost (low), speed (high), risk (low) of running and
evolving our business application landscape. The evolution of the underlying technology
and architecture is very much to be included. (Quote: Lucas Jellema, CTO, AMIS NL)

11. © OPITZ CONSULTING 2018 API-First-Design Seite 11
Use of APIs in µService interactions
µ
Customers
µ
Orders
µ
Products
µ
Loyalty
µ
Finance
µ
Logistics
Web Shop Portal
Micro-UIs
µ
Customers
µ
Orders
µ
Products
µ
Loyalty
µ
Finance
Horizontal level
Verticallevel
APIs
Events

12. © OPITZ CONSULTING 2018 API-First-Design Seite 12
Two-layered API approach to increase agility
Seite 12
User Experience
Service Implementation
Persistence
Web Mobile Device
Single Purpose API
Multi-Purpose API
Monitoring
BusinessAnalytics
Security
Management
Monolithic
System
RegistryEvent StoreShared Storage
Non-shared
Storage
Semi-decoupled Fully-decoupled
http://omesa.io
µServices
APIs

13. © OPITZ CONSULTING 2018 API-First-Design Seite 13
Meaning of APIs for µServices
¢ Single access point to a µServices Bounded Context
¢ Decoupling of frontend and backend logic (vertical level)
¢ Implementation of cross-cutting concerns
¢ Security (Authentication, Encryption, etc.)
¢ Monitoring (Number of calls, Number of errors, etc.)
¢ Quality of Service (Rate limits, Caching, etc.)
¢ Increased flexibility and agility with respect to changes
¢ API composition (MS Pattern C. Richardson)
¢ BFF (specific backends for a certain frontend)

14. © OPITZ CONSULTING 2018 API-First-Design Seite 14
Example: Financials µService
¢ Encapsulates everything with respect to financials:
¢ Business functionalities
¢ Manage Invoices
¢ Query Customer Account information
¢ Process Payments
¢ Data relevant to the financials domain
¢ Invoices
¢ Customer account information
¢ Payments
¢ Efficient development approach needs to:
¢ Support collaboration
¢ Decoupled development
¢ Quick feedback cycles
µ
Finance
µ
Finance UI
Finance
Finance Context
API

15. © OPITZ CONSULTING 2018 Seite 15
API first Design
3
API-First-Design

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

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

18. © OPITZ CONSULTING 2018 API-First-Design Seite 18
Tools supporting an API first design approach
Design Use Build Deploy Test
Feedback
Oracle API
Platform

19. © OPITZ CONSULTING 2018 API-First-Design Seite 19
API first Design with Apiary
¢ Supports API first design approach
¢ Collaboration through Github integration
¢ Ensures consistent API Design
¢ Support for API Blueprint and Swagger 2.0 (Open API)
API as a by-
product of
building apps
API
documentation
generated
from code
Design-first
API
Development
API Design
Consistency

20. © OPITZ CONSULTING 2018 Seite 20
Demo – Design with Apiary
API-First-Design

21. © OPITZ CONSULTING 2018 API-First-Design Seite 21
Comparison Swagger and API Blueprint
Swagger API Blueprint
Purpose Development framework:
Document, Implement (Code gen),
Testing
API Documentation
Representation JSON and YAML Markdown
Focus Streamline the update workflow Create consistent and better API
designs collaborativelly
Code Generation Yes; Client and Server code No code generation possible

22. © OPITZ CONSULTING 2018 API-First-Design Seite 22
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
¢ Alternatively: NPM-based tool

23. © OPITZ CONSULTING 2018 API-First-Design Seite 23
Implement the API
¢ Generate Sourcecode artifacts from Swagger definition
¢ Plugin can generate
¢ Client and Server artifacts
¢ Domain objects
¢ Service interface
¢ Different implementation technologies

24. © OPITZ CONSULTING 2018 API-First-Design Seite 24
Implement the API policy
¢ API policy consists of different assertions
¢ API policy is (often) implemented in a declarative fashion
¢ In Oracle API Platform Cloud Service:
¢ Management Service for:
¢ Implement the API policy
¢ Deploy the API policy to the Gateways
¢ Manage and monitor the API
¢ Developer Portal for:
¢ API discovery
¢ App registration

25. © OPITZ CONSULTING 2018

26. © OPITZ CONSULTING 2018
(1) Subscribe application to API
(2) Issued API key for this application

27. © OPITZ CONSULTING 2018 API-First-Design Seite 28
Testing API Design against the implementation
¢ Ensure that the implementation adheres to the API design
¢ Correct payload information
¢ Correct HTTP responce codes
¢ Defined HTTP ressources available
¢ Dredd is an 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-First-Design Seite 29
View Dredd test results in Apiary

29. © OPITZ CONSULTING 2018 Seite 30
Demo – Dredd API test
API-First-Design

30. © OPITZ CONSULTING 2018 Seite 31
Continuous Software delivery
3
API-First-Design

31. © OPITZ CONSULTING 2018 API-First-Design Seite 32
Automate as much as possible
¢ Build and deployment steps should be automated as much as possible
¢ Wercker is a cloud-based platform for building and deploying
containerized applications
¢ Build is defined as a so called workflows, which consists of pipelines
¢ Wercker provides a step store for sharing and exchanging templates
Pipeline
Definition in „wercker.yml“
<
Step

32. © OPITZ CONSULTING 2018 Seite 33
Demo – Wercker build pipeline
API-First-Design

33. © OPITZ CONSULTING 2018 API-First-Design Seite 34
K8s deployment using Helm charts
¢ ‘Package manager’ for Kubernetes apps
¢ Official Kubernetes project and part of Cloud Native Computing
Foundation (CNCF)
¢ Packages called charts stored in repositories
¢ Install/upgrade software
¢ Automatically install software dependencies
¢ Charts contain templatized Kubernetes configuration
¢ Helm chart repository: https://hub.kubeapps.com

34. © OPITZ CONSULTING 2018 API-First-Design Seite 35
Infrastructure-as-code
¢ CI/CD is more than just build, test and deploy your application code
¢ Infrastructure should be expressed by code and treated like that
¢ Dockerfiles
¢ K8s Resources (e.g. Deployment Configs, etc.)
¢ Cloud infrastructure management (e.g. provisioning of new compute nodes)
¢ Infrastructure code should describe desired target state
¢ Infrstructure-as-code helps to consistently manage your system
configurations

35. © OPITZ CONSULTING 2018 API-First-Design Seite 36
Test the integrated API solution
¢ 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

36. © OPITZ CONSULTING 2018 API-First-Design Seite 37
API Fortress
¢ Complete API platform solution for testing and developing
¢ Availabe in the Cloud or On-premises
¢ Support developers and testers in
¢ Functional testing
¢ Automation (for CI/CD)
¢ Mocking / Virtualization
¢ Load Testing
¢ Monitoring
Source: https://events.apifortress.com/end-to-end-automated-api-testing-qa-datasheet

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

38. © OPITZ CONSULTING 2018 API-First-Design Seite 40
Summary
¢ µServices are no silver bullet!
¢ Make use of an API first design approach to consistently design &
implement your APIs!
¢ Consistent, intuitive APIs are essential for API acceptance
¢ An API that is not used, is useless
¢ API design is as important as for µServices, as UI design (UX) is for User interfaces
¢ Especially when APIs are exposed to 3rd parties, like business partners and when it comes
to monetization
¢ APIs help to further transparency with respect µService usage
¢ Who is using a specific µService?
¢ How many requests are sent to this specific µService resp. to certain resources?

39. © OPITZ CONSULTING 2018 API-First-Design Seite 41
Links & Resources
¢ Financials µService Source: https://bit.ly/2qTQp1s
¢ Apiary: https://apiary.io
¢ API conversions: https://apimatic.io
¢ Dredd HTTP testing: http://dredd.readthedocs.io/en/latest/
¢ Wercker: http://www.wercker.com
¢ Helm: https://helm.sh
¢ Kubeapps: https://hub.kubeapps.com
¢ API Fortress: https://apifortress.com
¢ API Fortress Data sheet: https://bit.ly/2OQNjVP

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

41. © OPITZ CONSULTING 2018
¢¢¢ überraschend mehr Möglichkeiten!
@OC_WIRE OPITZCONSULTING opitzconsultingWWW.OPITZ-CONSULTING.COM
Seite 43
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
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-First-Design