apidays LIVE Paris 2021 - APIs and the Future of Software December 7, 8 & 9, 2021 Generating OpenAPIs from business models Frederic Fontanet, Architect & API Designer at UMLTech

1. Generating Open API specifications
from Business Models
A global business approach

2. 2
Frederic FONTANET - BIO
o Architect, API Designer (freelance)
o > 25 years of experiences
o Certified (UML advanced, µ-services, IREB…)
o Author, designer, developper of
o Architect, API designer and API evangelist for bank and finance companies

3. o (Big) Gap between business and technical stakeholders
o Too much time on API details, too little on business
o Complexity of http rules, patterns and API conventions
o Need of diagrams to discuss about the business concepts
o Lack of an efficient tool to produce Open API
o Lack of consistency
APIs: actual observed facts

4. Concepts, principles and expectation
Design principles
Increase the abstraction
Increase the re-usability
Improve business and IT agility
to respond changing
marketplace opportunities
Delivering agility to business
Enabling a globalWholesale
Connectivity ecosystem
The Open API manifesto
Improve the IT alignment on
the business

5. OpenAPI: the eco-system
5
Code generation
• Swagger.io
• specific
API Gateways
API security /
conformity
API tests

6. A magic trick
User story
(user needs)
API specifications
• Pro
• No constraint with other APIs
• Con
• Ambiguous
• User needs are not the business solution
• Focus on project requirements
• Focus more on technical details than the business goals
• Low consistency
• Resources definition, links, callbacks…

7. 7
Which way for a business approach?
… using that!
Provided operations
Business requirements
Whishing that …
Exposed resources
Customer journey

8. Deployment (gateways)
Implementation (automated code generation)
Security / conformity
Tests
Technical design
HTTP specifications
Security
Infra
Business Requirements
Scenarios
(narrative use cases)
Business requirements
Use cases identification
APIs: a Business and Enterprise approach
Formal Models
Contracts
Definitions
(structural
schémas)
Functional design

9. 9
o Matches many of the API design requirements
o Provides diagrams
o Allows Object Oriented Design
o Very Good feed-back from business stakeholders
o Many free or commercial UML modelers
o UML is a standard
UML Model as a formal model

10. Use cases: Identification

11. Use cases: Narrative use case  writing the functional solution
◎ One nominal scenario
◎ A set of alternatives
◎ A set of extensions

12. Use cases: Narrative use case
1) Decompose the business process
2) Remove irrelevante steps
…
12) Valid the operations
Candidates ‘services’
Business use case
From the requirements
and business
processes…
… services items are
identified (operations,
entities, properties, rules)
… then derived into concrete
‘APIs’ (UML models)
APIs in the model

13. Applying patterns
• A pattern provides a proven solution to a common problem
o API and µ-services patterns  https://patterns.arcitura.com/
CQRS pattern

14. UML: Common vocabulary (sharing data entities)
A business data entity is
designed once
for all APIs of the enterprise

15. UML Model: schemas (structural definitions)

16. UML Model: schemas, inheritance
Same schema nature

17. UML Model: schemas, using interface
Different schema natures

18. UML Model: Operations

19. One model to rule them all
Schema
Avro
One global enterprise
business model
To be coming

20. 20
Governance: roles (analysis to design)
Sponsor Business experts
Product owner
Business experts
functional designers
API Designers
UML models
30 to 35% 1 to 5%
60 to 65%

21. Generating Open APIs
from Business models
demo
21

22. 22
Swapi in a nutshell
o Designed for designing at the enterprise level, and to focus on business
o Help to improve the abstraction and the reusability+
o X30 to x50 faster than regular tools, with less errors and higher consistency
(intra and inter apis)
o HTTP Rules engine (fix errors)
o Versioning + comparator of versions
o Full coverage of the OpenAPI specifications
o Schemas / security / HATEOAS / Callbacks / Headers…
o Still in development (> 200 000 lines of codes) but already operational in a major french bank

23. 23
Swapi: a powerful versions comparator

24. 24
Users feedback of the approach
Anne RIVET VERJAT (BNP PF)
Antoine HOUDAILLE (Business & decision)
Mathieu MONTEIRO (Beijaflore)
Have to learn to NOT think as designing a database
Data objects are designed once, run everywhere
Decrease ambiguity, TOP approach!!!
Innovative approach
Requires an adjustment period
Provides a clear vision of the APIs at the enterprise level
Using visual models not only enables us to design for multiple countries
and all business lines and partners but we can also both understand and
visualize the whole model instead of parsing thousands of YAML lines
specification

25. 25
Next steps for
Improve functionalities
Schema
Avro
Improve the
‘Avro Schema designer’
Create the
‘gRPC / Protobuf Schema designer’
Improve ‘codegen’

26. 26
Contact
◎Frederic FONTANET
○ https://www.linkedin.com/in/frederic-fontanet/
○ swapi@umltech.fr
◎Sponsorships / investors are welcome!
○ Financial
○ Commercial