1. API design
best practice
Luca Ferrari
EMEA Solution Architect - Red Hat

2. Meetup objective
It is:
- A cheat sheet on API design
- A starting point for further investigation
- My first meetup as speaker
It is not:
- An explanation of the details of Swagger
- Revolutionary perspective on APIs
- The answer to all your questions about APIs (there
is a networking session for this)
2

3. Agenda
➔ API life & death
➔ API design phase
➔ API design principles
➔ OAS effect
➔ The blacksmith tools
➔ A tool chain
3

4. The (obvious) importance of Web APIs
01 Modern and powerful web browser.
02 The rise of minicomputers (also known as smartphone) and appification
03 The real world adoption of IoT device (Hey Google?)
Mashups:
https://wheelof.com/lunch/?zip=barcelona&query=lunch&radius=5
04 Simplification of protocols (HTTP rules)
05 New business models
the quality of a company’s API design provides a view into how the business truly values developers.
4

5. Lifecycle
5

6. One view
6

7. Another view
7

8. A simple view of it
8

9. A simple view of it
9
Determine API Business Strategy
● Natural extensions VS innovative model
● Operational efficiency VS company
vision and objectives
● Private APIs VS Partner APIs VS Public
APIs

10. A simple view of it
10
Prepare and Construct
technical requirements and development
plans:
● What operations
● How is it managed
● Which methods and protocols
● How big (now and then)
● Is it secure enough
● Is it usable enough
● Human VS Machine usability

11. A simple view of it
11
Promoting the Public API:
● Hackathons
● Documentation
● Omni-channel support
● Public events
● DX vs UX vs UI
Fix and Re-Fix:
● Analytics
● Users feedback
● Forums
● Documented and informed changes
● Fix →Feedback →Re-Fix

12. A simple view of it
12
Versioning & Deprecation
● limited usage
● lack of support
● lack of participation
● negative business effects
● privacy and security concern

13. API design phase
13

14. Which path will you take?
14

15. Which path will you take?
15
Design First approach:
● designing the API’s contract first
● new approach
● use of API description formats
Code First approach:
● traditional approach
● development of code happening after business requirements
● generating the documentation from the code

16. Which path will you take?
16
Design First advantages:
❏ better DX
❏ consistent design
❏ high re-usage
❏ business critical
❏ omni-channel
❏ better communication
Code First advantages:
❏ internal usage
❏ fast prototyping
❏ more automated
❏ agility (in the sense of fast,
wrong, retry)

17. API Design microscope
17
Service Description
Service Name
Domain Knowledge
Team-members
Organization
Schema of data
Repository
Assertions
Scenarios
OpenAPI
README
Tags
Definition

18. API Design microscope
18
Base Path
Path(s)
Verb(s)
Parameters
Headers
Body
Beyond Verbs With
Actions
Media Types
Status Codes
Filtering*
Pagination*
Sorting*
Response(s)
Errors
Design

19. API Design microscope
19
Major
Minor
Road Map
Communication
Versioning
Paths
Data
Virtualization

20. API Design microscope
20
Scenarios
Saved Requests
Responses
Playback
Results Archive
Reporting
Testing

21. API Design microscope
21
Hosting
Template
Discovery
Catalog
Portal
Blog
Github
Tickets
Internal / External
Email
Workshops
Communication
& Support

22. Design principles
22

23. 1. API as a Product
23
➔ Designate API from the beginning as separate project
➔ Even if it is just for internal usage
➔ Adopt the same action mandated for other products:
● Dedicated communication
● API product management
● API product lifecycle
● API product KPI
● API product sponsoring

24. 2. PoV of the Developer
24
Provider: Organization structure design flaw
Developer: The APIs are inconsistent, duplicated and full of
holes
Provider: Database structure design flaw
Developer: I don’t care about the data source structure or
technology, as long as you provide it reliably and consistently

25. 3. { ‘Document’: ‘document’ }
25
What makes for a great documentation:
1. Format:
a. Easy to read
b. Well designed
c. Easy to update
d. Easy to access
2. Completeness:
a. Remember it is a contract
b. Various levels of experience and situations
3. Interactive:
a. OpenAPI

26. 4. Learning curve
26
Make it easy:
1. Easy to access examples with data
2. Limited mandatory fields
3. Use hypermedia links to suggest actions
4. Offer one way to accomplish common scenarios
5. EXTRA POINTS: provide API based workflows (recipes)
and monitor usage

27. 5. consistent, consistent, consistent
27
Predictability here is a good sign:
1. Consistent naming and convention
2. Consistent camel case
3. Consistent resource URLs
4. Consistent payload format
5. Consistent errors format

28. 6. Wait for it … Security !
28
You don’t want to make the news (here, here) , security should
never be an afterthought:
1. Authentication (AuthN):
a. Basic Auth
b. API key
c. OAuth2
2. Authorization (AuthZ)
3. Data Leakage Protection
4. TLS is your friend
5. OWASP:
https://www.owasp.org/index.php/REST_Security_Cheat_S
heet

29. 7. Guided examples
29
Going beyond Read and Write:
1. Time To First Hello World
2. OnBoarding Total Effort
3. Workflow examples
4. Production ready guidelines

30. 8. EXTRA POINTS: little developer help
30
HTTP client libraries:
1. Right set of programming languages
2. Updated automatically
3. Updated frequently
4. Well explained

31. Some great examples
31
Adidas:
https://adidas.gitbook.io/api-guidelines/general-guidelines/gen
eral-guidelines
Zalando:
https://opensource.zalando.com/restful-api-guidelines/index.h
tml#principles

32. OAS effect
32

33. API specs formats
33
OAS or Swagger: WADL:
Bottom up construction W3C spec
Most popular Complex
Language agnostic
YAML or JSON Slate:
Minimal adoption
RAML:
More readable API Blueprint:
Less strict Markdown based
YAML Low adoption
Opinionated Can’t handle complex

34. API specs formats
34
OAS or Swagger: WADL:
Bottom up construction W3C spec
Most popular Complex
Language agnostic
YAML or JSON Slate:
Minimal adoption
RAML:
More readable API Blueprint:
Less strict Markdown based
YAML Low adoption
Opinionated Can’t handle complex

35. OAS v3.0
35

36. OAS v3.0
36
SERVERS:
● have multiple URLs are now allowed
● they can be used anywhere (even in PATH)
● PATH templates are now allowed
COMPONENTS:
● most of object are defined as components
● componentization (REST principle)
responses (existing) parameters (existing) examples (new)
requestBodies (new) headers (new) links (new) callbacks (new)
schemas (updated) securitySchemes (updated)

37. OAS v3.0
37
requestBody:
● added cookie parameter
● you can add an example (or array of examples)
● it now supports different media types
response:
● added wildcard response codes
callbacks:
● webhooks support

38. OAS v3.0
38
links:
● hypermedia support
● next action
● pagination support
SECURITY:
● multiple flows allowed
● OpenID Connect support

39. OAS v3.0 - links
39
The Link object represents a possible design-time link for a response. The
presence of a link does not guarantee the caller's ability to successfully
invoke it, rather it provides a known relationship and traversal mechanism
between responses and other operations.
Clients follow all links at their discretion. Neither permissions, nor the
capability to make a successful call to that link, is guaranteed solely by the
existence of a relationship.

40. OAS v3.0 - links (example)
40
https://gist.githubusercontent.com/lucamaf/c8c865077586b6291a
133f816ecc799f/raw/7d6254a8b154ef12ae03e5eb7a3717c81bb1
cade/gistfile1.txt

41. OAS v3.0 - callbacks
41
A map of possible out-of band callbacks related to the parent operation.
Each value in the map is a Path Item Object that describes a set of
requests that may be initiated by the API provider and the expected
responses. The key used to identify the callback object is an expression,
that identifies a URL to use for the callback operation.

42. OAS v3.0 - callbacks (example)
42
https://gist.githubusercontent.com/lucamaf/d210ae9b04358c3236
78aa5fbaf167a4/raw/323561a45cb156abf632409906da1fcac2e36
083/gistfile1.txt

43. Time for your opinion!
43
https://www.menti.com/

44. The tools
44

45. Stoplight
45
● Visual editor
● Integrated mock server
● Collaborative design
● Free Plan
● Non Open Source

46. Stoplight - DEMO
46
https://next.stoplight.io/

47. Restlet
47
● Visual editor
● Mocking possible
● Collaboration
● Generate server and client SDKs
● Free plan
● Partly open source

48. Restlet - DEMO
48
https://studio.restlet.com/

49. Apicurio
49
● Visual editor
● Generate API scaffolding
● Collaboration (real time)
● Support for OAS3
● Full Open Source

50. Apicurio - DEMO
50
https://studio.apicur.io/

51. 51
Test page

52. Time for your opinion!
52
https://www.menti.com/

53. A tool chain
53

54. Complementary tools
54
API Testing
Postman, JMeter3
API Mocking
Wiremock,
Mock-Server,
microcks
2
API Design
Stoplight, Restlet,
Apicurio
1

55. Acknowledgements
55
Adidas ProgrammableWeb Design great web APIs
NordicAPIs APIHandyman Zalando
Stoplight swaggerhub
Restlet apievangelist
Apicurio apis-guru (github)

56. Thank you for your time !
Let’s hear feedbacks
https://www.menti.com/
56