apidays LIVE Australia 2021 - Accelerating Digital September 15 & 16, 2021 Designing APIs: Just Enough is Perfect! Damir Svrtan, Senior Software Engineer at Netflix

1. Designing APIs
Damir Svrtan
Less Data is More

2. Damir Svrtan
He/him
Senior Software Engineer @ Netflix
Twitter: @DamirSvrtan

3. San Francisco 🇺🇸

4. Zagreb 🇭🇷

5. New York
JULY
Australia
SEPTEMBER
Singapore
APRIL
Helsinki & North
MARCH
Paris
DECEMBER
London
OCTOBER
Jakarta
FEBRUARY
Hong Kong
AUGUST
JUNE
India
MAY
Check out our API Conferences here
50+ events since 2012, 14 countries, 2,000+ speakers, 50,000+ attendees,
300k+ online community
Want to talk at one of our conferences?
Apply to speak here

6. Designing APIs
Less Data is More

7. Avoiding overhead when
designing APIs

8. Bloated overly flexible APIs

9. What kind of APIs?
• HTTP based APIs
• REST APIs, JSON APIs, GraphQL etc

10. API technology agnostic
Applicable for all kinds of APIs

11. Blogging Platform

12. Blogging Platform:
• Authors can release posts
• Posts can have comments

13. Two principles for
building APIs
• Designing the minimal API surface
• Designing from Strict to Loose

14. 1st Principal
Design the minimal API surface

15. Bloated API surface:
- redundant fields
- redundant relationships
- redundant input fields

16. Don’t Expose Redundant
Fields

17. Requirement:
“Show the author of the blogpost”

18. CREATE TABLE authors (
id
first_name
last_name
email
avatar_url
);

20. Friendly API developer:
“Let’s expose the email, someone might find it
useful in the future”

21. type Author {
id
firstName
lastName
avatarUrl
email
}

22. 6 months later:
Privacy reasons: stop exposing the email

23. ..deprecation cycle..

24. ..extreme amounts of communication..

25. ..breaking clients..

26. ..extreme amounts redundant cycles..

27. Don’t Expose Redundant
Relationships

28. Requirement:
“Indicate whether a post was reviewed”

29. type Post {
title:String
body:String
}

30. type Post {
title:String
body:String
reviewed:Boolean
}

31. Friendly API developer:
“Let’s expose the reviewer for future use
cases”

32. type Post {
title:String
text:String
reviewed:Boolean
reviewer: Reviewer
}

33. Development costs are growing;
- batch/eager loading
- testing
- performance impacts

34. type Post {
title:String
text:String
reviewed:Boolean
reviewers: [Reviewer]
}
type Post {
title:String
text:String
reviewed:Boolean
reviewer: Reviewer
}

35. ..deprecation cycle..

36. ..breaking clients..

37. Delaying Decisions
Adding later when we have more knowledge is better

38. It’s easier to add in the future than to
remove

39. Don’t Expose Redundant
Input Fields

40. Requirement:
“Readers need to be able to create and
update comments”

41. input CreateComment {
postId: ID
body: String
}

42. The friendly API developer:
“Let’s have parity between inputs”

43. input UpdateComment {
id: ID
postId: ID
body: String
}

44. The blogging platform doesn’t support
comment transitions from one post to another

45. input UpdateComment {
id: ID
postId: ID
body: String
}

46. Avoid anemic data modeling

48. Ambiguity deteriorates
Developer Experience

49. YAGNI
You Ain’t Gonna Need It

50. 2nd Principal
Strict to Loose

51. - Avoid extra flexibility
- Breaks First!

52. Avoid extra flexibility

53. Requirement:
“The users need to be able to see comments
on a post”

54. comments(postId: ID @required)

55. The friendly API developer:
“Our clients might want to fetch all comments
in the future”

56. comments(postId: ID @optional)

57. Unneeded application logic

58. If postId.present?
…
else
…
end

59. More code = More maintenance

60. More code = More tests

61. On inputs, it’s easy to go from required to
optional, not the other way around

62. Strict to Loose gives you more
control

63. Loose to Strict
is a breaking change

64. Breaks First!

65. Requirement:
“Ability to fetch comments for a post”

66. The friendly API developer:
“Let’s just give them an array of comments,
we don’t need pagination!”

67. The friendly API developer:
“Let’s just give them an array of comments,
we don’t need pagination yet!”

68. comments(postId: ID): [Comment]

69. The friendly API developer:
“We won’t have more than 5 comments per
post!”

70. 6 months after:
“There’s posts with 100’s of comments”

71. Developer:
“Let’s add pagination”

72. comments(postId: ID): PaginatedComments

73. Work is done, let’s go home!

74. comments(postId: 1, first: 1000)

75. The Friendly API Developer didn’t
add limits to pagination

76. Add pagination limitations from the
beginning

77. Error Message:
Requesting 1000 records exceeds the `first`
limit of 100 records.

78. Super hard to add retroactively, but super
easy to adjust in the future.

79. How to avoid these overheads?

80. Adopt Schema First Design

81. Talk to your clients

82. Be responsive to your clients
requests

83. There’s always exceptions

84. Platform APIs

85. Constraints due to release
cycles

86. Conclusion

87. Redundant work slows down
progress on important features

88. “The road to hell is paved with good
intentions”

89. Thank you! 👋
Twitter: @DamirSvrtan

90. New York
JULY
Australia
SEPTEMBER
Singapore
APRIL
Helsinki & North
MARCH
Paris
DECEMBER
London
OCTOBER
Jakarta
FEBRUARY
Hong Kong
AUGUST
JUNE
India
MAY
Check out our API Conferences here
50+ events since 2012, 14 countries, 2,000+ speakers, 50,000+ attendees,
300k+ online community
Want to talk at one of our conferences?
Apply to speak here