1.
Generating Open APIs
from Business Models
High productivity and consistency
A global business approach

2.
2023 SERIES OF EVENT
New York
May 16&17
Australia
October 11&12
Singapore
April 12&13
Helsinki & North
June 5&6
Paris
SEPTEMBER
London
November
15&16
June 28-30
SILICON VALLEY
March 14&15
Dubai & Middle East
February 22&23

3.
Business and technical stakeholders  GAP
APIs: issues on ‘traditionnal’ design
Complexity of http rules, patterns and API conventions
Lack of diagrams to discuss about the business concepts
Lack of consistency of the
entity definitions

4.
3
The API design
approach

5.
4
Which way for a business approach?
Provided operations
Whishing that …
Business requirements
Exposed resources
Customer journey

6.
5
‘’We need 50 business analysts
knowing HTTP
or
50 API designers knowing business’’
subsidiary
Product owners and API designers gap

7.
6
Increase abstraction
Increasing automation and
consistency at the entreprise level
involves
increasing abstraction
(formal models / grammars)

8.
 Provides diagrams
 Allows Object Oriented Design
 Very good feed-back and involvements from business
stakeholders
 Provides METADATA
 UML is a standard
 Matches many of the API design requirements
7
UML Model as a (business) formal model

9.
8
UML coverage of OAS (v3.x)
Features
Schemas
Objects concepts (polymorphism, inheritance…)
Operations
Servers
Paths (endpoints) -
Parameters / request body / header parameters
Responses
Links
Callbacks
Examples
Security -

10.
Technical design
HTTP specifications
Security
Infra
Business Requirements
Scenarios
(narrative use cases)
Business requirements
Use cases identification Formal Models
Contracts
Definitions
(structural
schémas)
Functional design
APIs: a Business and Enterprise approach
Totally API first approach

11.
From the use cases to the model
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

12.
11
Manage
the consistency

13.
12
Need of consistency
50 API designers (no automatisation, a dedicated
reviewer team)
2 API designers, no reviewer team

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

15.
14
API FinancialProduct
API Mobility quotation API Retail quotation
API Context sharing
A business data entity is designed once for all APIs (enterprise level)
Then, the relative schema(s) is(are) taylored for each API
Consistency on schemas
Diagrams are intentionally blurred

16.
15
Consistency issues
API
API
API
API
API
API
API
API

17.
16
Tayloring a schema
Select the properties for an API
Take into account … or not
…the new properties
Text is intentionally blurred

18.
17
API #2
API #4
API #3
API #1
A business data entity is designed once for all APIs (enterprise level)
Then, the relative schema(s) is(are) taylored for each API
Update / add / remove a property

19.
Examples updated automatically
Data model
(UML)
Instances
(UML)
API #2
API #4
API #3
API #1
Examples
(Json)

20.
Consistency on links
Links definition is managed

21.
Versions comparator

22.
21
APIs are monitored by a linter
HTTP rules engine (linter)

23.
22
Increase
the productivity

24.
UML Model: Operations

25.
24
Productivity: creating operations and parameters
Functional design
Operations from a
business view
Technical design
http and security design
YAML

26.
25
Productivity: generating schemas
Business entities
(Enterprise level)
Fitting the business
entity to the API
YAML

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

28.
27
Conclusion
 Think business … not technical design
 Increase abstraction  models (UML, specific DSL)
 Apply patterns
 Automate the transformation from the models to the APIs
 Tools:
 Any UML Modeler (based on EMF)


29.
28
Contact
Frederic FONTANET
○ https://www.linkedin.com/in/frederic-fontanet/
○ swapi@umltech.fr
is coming in 2023
Searching for commercial partner & investors!

30.
Annexes
29

31.
30
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

32.
Use cases: Identification

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

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

35.
UML Model: schemas, inheritance
Same schema nature

36.
UML Model: polymorphism
Different schema natures

37.
36
Swapi: a powerful versions comparator

38.
APIs: from requirements to code … (personal) actual observations
37
Business
requirements
Functional
design
Technical design
REST/HTTP
Coding
Consistent code
Rich generated code
Shared libraries
API, µ-services: principles and
patterns applied
Strong interactions with
business stakeholders
Object Oriented Design
requirements
Automatic / guided design
APIs editors
paths:
/customers:
get:
summary: ""
description: ""
operationId: "getCustomer"
parameters:
- in: "body"
name: "customer"
description: ""
required: true
schema:
$ref: "#/definitions/Customer"
responses:
201:
description: ""
schema:
type: "integer"
format: "int32"
Manual design
low consistency
‘Simple’ code
Low consistency
Methods in
enterprises
X ‘Simple’ code
Low consistency
paths:
/customers:
get:
summary: ""
description: ""
operationId: "getCustomer"
parameters:
- in: "body"
name: "customer"
description: ""
required: true
schema:
$ref: "#/definitions/Customer"
responses:
201:
description: ""
schema:
type: "integer"
format: "int32"
Manual design
low consistency
Low interactions with
business stakeholders
requirements

39.
Avro schema Designer: from model to Java
38
Schema
Avro
Schema
Avro Java
Designing the specific message
Many different schemas from the same model
Schema Avro
Serializer
Data
Schema Avro
Deserializer
Data
Data model