REST API design and changing "contract"?

Question

I'm designing RESTful API. Result will be in form of JSON object. I don't need to send all fields from my POJO classes to the client, so I should define some kind of "contract".

Let's say I have a Property class, and I define id, name and address for it. Later, I might want to change address to geoData, without influencing clients.

Is there some elegant way (pattern) to do this?

Answer 1

Create versioning to your REST design. When you start to create new implementation, use new URI to define it. For example create new URI with the similar parameter, with difference in version:

• OLD implementation /ver1/retrieve/user ( still being maintained )
• NEW implementation /ver2/retrieve/user

By doing this, client will still able to retrieve user with old implementation without any issue. However when you decide to change the implementation again, it's better for you to freeze the old version of the API ( for example when implementing v3 API, you should notify client that the old version 1 API will no longer supported )

More information can be found here :

How to version REST URIs

Versioning restful services