Hacker News Reader

Comment by al3xdm | Hacker News Reader

I'm not sure this works once other people start building on top of your API though. I would rather bump the API version than break API compatibility by adding/removing/renaming fields.

Github (which you used in your example of good design) do change fields returned in their API responses but only between API version not inside of versions. The link you gave [1] is to Version 3 of their API which is different to Version 2 and will be different to Version 4. I don't really want to be programming against APIs where identical requests can return varying responses based on supposed intent.

1. http://developer.github.com/v3/repos/statuses/

View on HN

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

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?

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.

Reply on news.ycombinator.com