Prepare for Extensibility
There are various areas where future releases of the Places (Search) API will silently extend the volume and types of information provided.
- Code must check the type attribute of the hypermedia links to ensure that applications don't try to access media types that may be introduced in future releases.
- Clients should iterate over all contacts attributes of a place instead of picking specific ones to ensure that applications can display all available contact mechanisms to users.
- Developers should iterate over all extended attributes instead of picking specific ones to ensure that applications can display all available facts about a place to users.
- Developers should also iterate over all related places instead of picking specific ones to ensure that applications can display places of all related types to users.
The API contract with client applications allows for extensibility. In general, clients can rely on the fact that anything that is documented will remain valid at least within the major version of the API to which the documentation applies. Anything that is not documented may change at any time.
Clients should be prepared to find new elements (content and features) in new releases of the API. Developers are free either to ignore the new elements or – if the new elements are documented – use them by applying generic patterns, without adverse impact on existing applications.
Developers should not be surprised to find undocumented objects, attributes, or fields in our responses. The Places (Search) API offers feature parity to all users of the API; so even experimental features that we initially develop with certain pilot API users will be visible from the start. But we will only add them to the public documentation once the new feature has fully matured and proven to add value for our users.
Please note that we may change the implementation of such features at any time, or even decide to remove them from a future release. So unless you are fully aware of the application of these features (and how to manage potential changes), it is best to wait to use the new features until they are publicly documented. In other words, if a feature is not mentioned in this documentation we recommend that you do not use it.