Versioning of the OData Domains
A domain version refers to a specific version of a domain model within an OData service. A domain version signifies a particular snapshot of this domain model. WRS follows the rules set by the OData specifications regarding model versioning. For more information, see Model Versioning.
It is recommended that the server and the client follow the rules set by the OData specifications.
When an OData service evolves, its domain model may also change. These changes can include:
• Addition of entities—New entities might be introduced to represent additional data types or concepts.
• Modification of properties—Properties of existing entities might be added, removed, or changed.
• Changes in relationships—Relationships between entities might be modified or extended.
• Behavioral changes—The behavior of certain entities or operations might change.
A new version of the domain model is created to support backward compatibility with existing clients while introducing changes for new clients.
 |
As domains have dependencies on other domains (indicated by edmx:Reference in $metadata), versioning of one domain can lead to versioning of other dependent domains. If a client uses multiple domains, it is recommended that it uses a consistent set of domain versions (as described in $metadata).
|
Breaking changes are the changes to the API that could potentially break clients that rely on the existing API. These changes may include modifications to the data model, URI structure, or behavior of the service. For handling breaking changes, PTC versions the API. For every breaking change, a new version of the API is created, allowing existing clients to continue using the previous version. This enables PTC to introduce changes without affecting the existing consumers. As the effective communication is crucial, PTC notifies consumers about upcoming changes, deprecations, and new versions.
Non-breaking changes are the changes that can be made to the service provider without requiring clients to be updated or causing them to break. For example:
• Adding new resources or properties does not break existing clients. Clients can ignore or be unaware of these additions if they do not need or use them.
• Adding new query parameters to endpoints to support additional filtering, sorting, or other functionality is generally non-breaking. Existing clients can continue to function without modification.
• Fixing bugs, making improvements or optimizations, such as enhancing performance or efficiency, is usually non-breaking. Clients should benefit from these improvements without needing to be updated.
|
|
There could be a case where the service is not compliant with the specifications due to a bug. Fixing the bug may break existing clients. This is typically done without domain versioning because it is a compliance issue. However, PTC understands that what constitutes a breaking or non-breaking change can vary based on the specific context and the needs of the clients. Therefore, PTC provides effective communication to customers and partners and clear documentation to better understand how changes may impact their use of the service.
|
|
|
To handle the non-breaking changes, the client must follow the rules set by the OData specifications.
|