Over a million developers have joined DZone.
{{announcement.body}}
{{announcement.title}}

Rules for Extending Your API With Each Version

DZone's Guide to

Rules for Extending Your API With Each Version

In this article, we examine some rules for extending APIs that the Adidas Group has outlined in their API guidelines, and how these could help devs.

· Integration Zone ·
Free Resource

How to Transform Your Business in the Digital Age: Learn how organizations are re-architecting their integration strategy with data-driven app integration for true digital transformation.

I’m spending time learning from the API design guides of other leading API providers, absorbing their healthy practices, and assimilating them into my own consulting and storytelling. One API design guide I am learning a lot from is out of the Adidas Group, which contains a wealth of wisdom regarding not just the design of your API, but also the deployment and evolution of the API resources we are publishing.

One particularly interesting piece of advice I found within Adidas API design guidance were their rules for extending an API, which I think is pretty healthy advice for an API developer to think about.

Any modification to an existing API MUST avoid breaking changes and MUST maintain backward compatibility.

In particular, any change to an API MUST follow the following Rules for Extending:

  • You MUST NOT take anything away (related: Minimal Surface Principle, Robustness Principle).
  • You MUST NOT change processing rules.
  • You MUST NOT make optional things required.
  • Anything you add MUST be optional (related Robustness Principle).

NOTE: These rules also cover renaming and change to identifiers (URIs). Names and identifiers should be stable over the time including their semantics.

First of all, I think many API developers aren’t even thinking about what constitutes a breaking change most of the time. So having any guidance that makes them pause and think about this topic is a good thing. Second, I think we should be sharing more stories about when things break, helping folks think more about these elements – the problem is that many folks are embarrassed they introduced a breaking change, and would rather not talk about it, let alone make it publicly known.

I am working my way through the API Stylebook, learning from all the API design guides it has aggregated. There is a wealth of knowledge in there to learn from and contains topics that make for great stories here on the blog. I wish more API providers would actively publish their API governance strategy so that we can keep aggregating, and learning from each other. Making the wider API space more consistent, and hopefully more reliable along the way.

Make your mark on the industry’s leading annual report. Fill out the State of API Integration 2019 Survey and receive $25 to the Cloud Elements store.

Topics:
integration ,apis ,api design

Published at DZone with permission of

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}