Versioning¶
The apiVersion field¶
Your plugin declares which API version it was built against in GetInfo:
HydroSym checks this value when loading the plugin:
- If
apiVersionmatches or is lower than the version HydroSym supports, the plugin loads. - If
apiVersionis higher than HydroSym supports (plugin is newer than HydroSym), HydroSym refuses to load it and logs an error.
The current API version is 1.
Additive-only changes within a version¶
Within a major API version, only additive changes are made:
- New optional request fields may be added.
- New optional response fields may be added.
- New optional methods may be added.
- New optional capability strings may be added.
Nothing is removed, renamed, or made more restrictive within a version.
Implication for plugins: Always ignore unknown fields in responses (the SDK does this by default). Always tolerate missing optional fields.
What is breaking vs non-breaking¶
| Change | Breaking? | Notes |
|---|---|---|
| New optional request field | No | Plugin ignores it |
| New optional response field | No | HydroSym ignores it |
| New method | No | Plugin returns NOT_SUPPORTED |
| New capability string | No | Plugin simply doesn't list it |
| Rename a field | Yes | Old plugins send wrong field name |
| Remove a field | Yes | Old plugins may depend on it |
| Change a field type | Yes | Breaks serialization |
| Change a result code meaning | Yes | Old plugins behave incorrectly |
| Remove a method | Yes | Old plugins may have listed the capability |
Breaking changes require a new major API version (e.g., apiVersion: 2).
Compatibility matrix¶
| Plugin apiVersion | HydroSym supports | Result |
|---|---|---|
| 1 | 1 | ✅ Loads normally |
| 1 | 2 | ✅ Loads (HydroSym is backward compatible) |
| 2 | 1 | ❌ HydroSym refuses to load (plugin too new) |
HydroSym is always backward compatible with older plugins. Plugins should not be deployed to a HydroSym version older than the apiVersion they were built against.
The capabilities array as feature detection¶
New methods introduced in a minor update of API v1 are always optional and controlled by capabilities. HydroSym checks the capabilities array before calling any non-lifecycle method.
This means: - Old plugins (missing new capabilities) work on new HydroSym — HydroSym just won't call the new methods. - New plugins that declare new capabilities don't break on old HydroSym — old HydroSym simply never calls those methods (it doesn't know about them).
Capabilities are the extension mechanism within a major version. You do not need a new apiVersion to add new optional methods.
Plugin version vs API version¶
These are separate:
apiVersion— the version of the HydroSym Plugin API protocol. Currently1.version— your plugin's own version (semver recommended, e.g.,"2.3.1").
HydroSym only uses apiVersion for compatibility checks. version is displayed in the Plugin menu for informational purposes.