Your API is language agnostic, but your API consumers are not. When Developers Integrate with an API, they do so in their favourite programming language. With the help of an API specification, you can automatically generate up to 90% of the integration code (as SDKs and Code Samples) and save them heaps of time. The problem is, OpenAPI and other API specification formats are not built with code generation requirements in mind, thus we often see Code Generators creating unusable code for syntactically correct API specifications. This talk will demonstrate how you can carefully craft an API specification to generate production-quality SDKs and API portals. It will help you understand how trivial issues like inline anonymous schemas and naming conventions can have a big impact on the generated output. And how the right kind of validation and linting process can help you overcome all of these issues efficiently in order to help you build a world-class Developer Experience.

1. OpenAPI Secrets
For Generating Code & Docs
Which Work!

2. Which Machine Readable API Definition
Format Do You Use?
2
OpenAPI?
RAML?
Postman?
Insomnia?
API Blueprint, WADL, WSDL, IODocs, HAR, Google
Discovery?

3. 3
0"
700"
1400"
2100"
2800"
3500"
A
P
I
M
A
T
I
C
'
I
O
D
o
c
s
'
R
A
M
L
'
W
A
D
L
'
S
w
a
g
g
e
r
Y
a
m
l
'
G
o
o
g
l
e
D
i
s
c
o
v
e
r
y
'
M
a
s
h
a
p
e
'
S
w
a
g
g
e
r
'
A
P
I
B
l
u
e
P
r
i
n
t
'
71' 104'
390'
525' 550'
3039'
962'
3041'
2834'
68' 104'
200'
''''''''295' '''''''322'
'''476'
962'
1948'
2614'
All'IDFs' Unique'IDFs'
Analysis of 11516 API Definitions
From APIDays, 2016

4. 4

5. 01,041,706
APIs Transformed and counting …
5

6. 6
apimatic.io/blog

7. 7

8. 8

9. 9

10. WHY
Do we are about this data?
10

11. 11
APIMatic

12. 12

13. Common Mistakes Developers Make In Their OpenAPI 3 Files (2018)
13

14. Common Mistakes Developers Make In Their API Blueprint Files (2018)
14

15. Common Mistakes Developers Make In Their RAML Files (2018)
15

16. 16

17. The Real Problem
A Valid Definition Producing Bad Code
17

18. 18
A Real-World Example

19. 19

20. 20
apimatic.io/blog/2021/12/million-mile-views-via-a-nasa-api

21. 21
3 Errors
6 Warnings
22 Linting Issues

22. 22
Spectral Found It Ok

23. Say No to Inline Schemas
OpenAPI Secret # 1
23

24. 24

25. 25

26. 26

27. 27

28. Don’t Miss Operation IDs
OpenAPI Secret # 2
28

29. 29

30. 30

31. 31

32. Mind The Characters in
Operation IDs
OpenAPI Secret # 3
32

33. 33

34. 34

35. 35

36. 36

37. Avoid Schema Key Confusions
OpenAPI Secret # 4
37

38. 38

39. 39

40. 40

41. Some Minor, yet
Important Considerations
41

42. Keep the Parameters in
Order
42
OpenAPI Secret # 5

43. 43

44. 44

45. 45

46. Very Long Names Hurt
User Friendliness
OpenAPI Secret # 6
46

47. 47

48. 48

49. Operation Tags Are Helpful
OpenAPI Secret # 7
49

50. 50

51. 51

52. SDKs beyond API Wrappers? 52

53. How to Validate Specs for
Generating Code?
53

54. 54
apimatic.io/solution/fix-my-spec

55. 55

56. 56
Thanks!
Any questions?
You can find me: adeel@apimatic.io
Resources:
Validator: apimatic.io/solution/fix-my-spec
API Trends: apimatic.io/blog
NASA API: apimatic.io/blog/2021/12/million-mile-views-via-a-nasa-api
SDK Advantage Book: apimatic.io/resource/modern-guide-to-building-sdks

57. Credits
Special thanks to all the people who made and
released these awesome resources for free:
Presentation template by SlidesCarnival
Photographs by Unsplash
57