I can't point to them because they're internal, but there are some good ones I've used. Pagination was one useful part, where we saw the API change but didn't have to change the client. A second was being able to explore parent relationships, so we could start somewhere in the tree and move up until we hit the level we were interested in.
There are always agreements between the API designers and client designers, because the code isn't intelligent, so it doesn't know what 'parent' means. If the name of that changes, then the client would have to change. What can be different is the url structure to get the 'parent'. Maybe there's a new token that has to be there, or the naming of something has been changed, or whatever. Those changes can be made without breaking the clients. Putting this in the responses means two things:
1) Small changes don't break everything (pagination is a great one, its a /pages/1 one day then ?page=1, then ?offset=25, then ?pageSize is optional, then it's required, etc.).
2) Fewer assumptions baked into the client. Getting the tweets for a user you've loaded would be nicer as load(user.tweets) than load("/tweets/"+user.id)
There are always agreements between the API designers and client designers, because the code isn't intelligent, so it doesn't know what 'parent' means. If the name of that changes, then the client would have to change. What can be different is the url structure to get the 'parent'. Maybe there's a new token that has to be there, or the naming of something has been changed, or whatever. Those changes can be made without breaking the clients. Putting this in the responses means two things:
1) Small changes don't break everything (pagination is a great one, its a /pages/1 one day then ?page=1, then ?offset=25, then ?pageSize is optional, then it's required, etc.).
2) Fewer assumptions baked into the client. Getting the tweets for a user you've loaded would be nicer as load(user.tweets) than load("/tweets/"+user.id)