With web services, documents are your public API. Once a service is public, there is a contract between you and the consumers of the API that it will not change until a new version comes out. This is why we see the /v1/ convention in REST services. /v1/ MUST not change on people. You wouldn't do that with a public C library, you shouldn't do that with web services. It is anti-social to change that API on developers.
These documents are very complex. Just take a look at a twitter timeline JSON response. Having a getter and setter for every field in that document would get ridiculous.
The problem with JSON is it is so easy to change that it takes self discipline to enforce your own social contract. We all know that when faced with deadlines some developers get a little fast and loose to meet that deadline.
But you should not even have a /v1/ in your URLs. mysite.com/v1/people/john is probably not a different person from mysite.com/v2/people/john. Instead, you should have versioned content types. The URLs of a REST service can change as much as they like, the client should not assume any other URLs than the entry point.
The form of the response, be it JSON or something else, is the thing that should not change. And you are right that even with a documented content type keeping the promise is hard.
/v1/people/john and /v2/people/john are different representations of the same internal state.
REST = Representational state transfer. While a URI is a unique identifier, it uniquely identifies a representation of internal state. The structure of the representation under a version should stay constant or else you void your social contract with consumers of your service.
The structure of the representation under a version should stay constant or else you void your social contract with consumers of your service.
Yes, but the version should be stated in the Content-Type header, not in the URI of the resource. URI identifies the resource and Content-Type identifies the representation.
These documents are very complex. Just take a look at a twitter timeline JSON response. Having a getter and setter for every field in that document would get ridiculous.
The problem with JSON is it is so easy to change that it takes self discipline to enforce your own social contract. We all know that when faced with deadlines some developers get a little fast and loose to meet that deadline.