The answer that I have found to avoiding problems such as the one you
describe is to be absolutely clear on intent. Once you understand why
you are including certain pieces of information, it makes it much
easier to change without impacting your clients.
Let me try and explain what I mean. You state:
"address is represented today as name, street, city, country"
This is standard practice, but why is that. Why are we delivering to
the client this information as distinct fields? What will the user do
with that information? Is the client going to display this address to
a user in an UI? Are they going to print a mailing address label?
Are they going to use some of that information as demographic
You suggest the API user may glue the fields together and make mailing
label out of it. Is this something that we want our users doing with
the address? If so then why not give it to them formatted? Do they
know how to format it properly? Do they know that German street
addresses are rendered very differently than Canadian ones. Do they
realize British addresses will often include two towns, the actual
town and a nearby major town? Why are we breaking this down just so
the client has to put it back together? Are we just offloading this
work to the client because we don't want to think to hard, under the
guise of "flexibility"?
On the other hand maybe they do want demographic information? Maybe
they want postal code, maybe they want country, but care_of is not
going to affect those demographics. Maybe there is other demographic
information that we could include in the representation that is far
more important that the information that can be gleaned from the
When we build a representation with information that has a specific
intent it becomes much easier to change that information in a way that
makes sense to the client. Adding care_of information into a textual,
completely formatted address means the client will naturally include
that information when it displays the address or prints a mailing
label. If address is included for demographic information, you know
the client doesn't care about care_of.
Great API's are designed with intent. They are not just a dump of
internal data. Once you understand the intent, you can design the API
to give the client just what they want even as change occurs, because
you know how that data is being used.
Personally, I don't believe in this attitude of "we'll expose our data
and see what people do with it". It's a fast food API, it's quick to
get going, you don't have to think hard, but it's not a long term
healthy choice. It will bring versioning issues, and it will bring
I do believe that client developers will find new uses for our APIs
that we had never considered, and it is critical that we have an
responsive process in place to be able to enhance our API to provide
new capabilities. But I believe those new features must be added in
reaction to an expressed demand and clear intent. HTTP based APIs
have a very interesting quality that it can be very cheap to add new
resources to satisfy new needs. These new resources can address new
completely new requirements, or they can provide enhanced versions of
existing resources. I'm not so convinced that we need to be so quick
at removing old resources that are non-optimal.
Anyway, just my 2c on the subject.