Talk Notes: "Designing APIs: Less Data is More" (RailsFonc 2021)

What is this post about: As a part of my professional growth, I make time to watch conference talks on Ruby, Rails, JS, React, tech writing, and tech trivia. Previously, I'd just watch them but now I will take and publish notes for future reference. This talk was a part of RailsConf 2021 that I'm participating in at the time of writing.

Talk: 'Designing APIs: Less Data is More' by Damir Svrtan

One-paragraph summary: Often developers design APIs that expose more than is needed - unnecessary fields, redundant relationships, and endpoints that no one asked for. These kinds of practices, later on, introduce communication overhead, extra maintenance costs, negative performance impacts, and waste time that could have been spent better otherwise.

Impression: I really loved this talk! So clear, well-organized, and concise. I loved Damir's calm way of presentation!

Table of contents:

• Notes
• Read more

Notes

• Main pain points when building/maintaining an API:
  • overly flexible APIs with queries no one asked for
  • unused endpoints
  • redundant functionality: extra fields, extra relationships, extra input fields
• 1st principle: Bloated API surface
  • redundant fields: don't expose redundant attributes
  • redundant relationships: don't expose redundant relationships because that increases the dev costs (testing, negative performance impacts, batch/eager loading because of data size)
  • redundant input fields: if the user can't interact with a field (for instance, update it), don't serve it to them
• deprecation cycle is costly: involves a lot of communication and coordination, breaking clients,
• delaying decisions is better as long as it doesn't impact our roadmaps -- adding later when we have more knowledge is better
  • it's easier to add a feature than to remove it in the future
• "You're supposed to build your API according to your business needs -- the logic should be on the server, not on the client"
• Ambiguity deteriorates DevEx - they'll wonder what happens if they play around with a field
• if YAGNI (you ain't gonna need it), don't include it
• 2nd principle: Strict to Loose
  • Avoid extra flexibility: APIs need to be ready to be flexible in the future but don't need to be flexible right now; build only what your client needs (because it's unneeded code and more code = more maintenance + more tests); it's easier to go from required to optional (clients will still be able to communicate just fine), not the other way round;
  • Breaks First! (or how to apply defensive programming in your APIs): add pagination with limits from the beginning because it's super hard to add retroactively but super easy to adjust in the future (if you want to increase the number)
• How to avoid these problems:
  • Adopt schema first: what's the product, for whom you're building it? Don't play guessing games
  • Talk to your clients: don't be speculative, be iterative;
• Exceptions: trying to get ahead of a competitor, constraints due to the release cycles,
• tl;dr: redundant work slows down progress on important features + "the road to hell is paved with good intentions"

Read more

• GraphQL Mutation Design: Anemic Mutations