[mfenniak]

Hi Alex,

I never advocated breaking compatibility by adding, removing, or renaming fields in this article. Would you please let me know what gave you that impression so that I can clarify it?

I also did not state that having a versioned API is a bad thing. GitHub's API was a great example because it's both well-designed and versioned. Good design is going to make your API less fragile and far less prone to version changes, but I'm strongly in favour of versioning your API.

Mathieu

[al3xdm]

Hi Matthew,

You suggested that the FBI could re-write the API request to be: http://api.fbi.gov/wanted/most

Which would return a set of known fields. You then go on to say:

"After complaints that “notoriety” is a made-up number, the FBI can hide the field; the intent-driven design is unchanged."

This suggests that the API author is free to add, remove or rename fields in the response without bumping version as it's part of the "intent-driven design".

In response to your second point, I then don't understand what the real purpose of intent-driven API design is. The only different appears to be that you given more RESTful URLs than using loads of query parameters?

[mfenniak]

Ah, thank-you for pointing that out. That's definitely a mistake in the article. I've amended point #4 with another possible approach.

Intent-driven design reduces the fragility of your API, gives you a wider variety of changes that you can make to your API that are backwards compatible.

If it's done perfectly, and your software solves the same business problem tomorrow as it does today, then you will never need to increment your API version number. The reality is that it will never be designed perfectly, and requirements are never that stable, so having a versioned API is a practical and prudent choice.