Version Control
Keeping several versions of the API makes it possible to improve the service without detriment to the backward compatibility. On the one hand, new requirements that demand changes appear all the time, on the other hand, any change in the program interface may impair the operation of existing plugins. To tackle this issue, the API has several versions: at some point, a version is no longer developed, the interface is frozen, and the development continues within the next version. Whatever changes are introduced at a later time, a plugin developed for a frozen version will be functioning properly while this version is supported.
Version Life Cycle
Most of the LTS versions (Long-Term Support) are released approximately once in two years and are supported for about four years. Intermediate preview versions are released between such versions once in three months and are supported for a half of the year. Thus, at each point of time, we support two most recent LTS versions, two most recent preview versions (or one if an LTS version was released in the previous quarter), and an LTS version under development is available for your reference.
LTS versions are whole numbers given successively — V1, V2, V3, V4, V5, V6, and so on. Preview versions are intermediate LTS versions under development, therefore, they have a number of the LTS version with the Preview prefix, for example, V8Preview1, V7Preview2, and so on until V8Preview7, following which the V8 LTS version will be released.
Release Schedule
Once a new LTS version is released, the roles are reassigned the following way:
- outdated version is no longer supported;
- stable version becomes outdated;
- develop version is frozen and becomes stable;
- new develop version appears.
The cycle of preview versions is a bit simpler.
- outdated preview version is not supported;
- current preview version is announced outdated;
- copy of the current state of the LTS version being developed is issued as a new current preview version.
Choosing Versions
By default, it is recommended that a stable LTS version is used; this allows to minimize migration efforts when new API versions are released. If some new functions that are not yet available in LTS versions are required, it is recommended that a current preview version is used; in this case, the migration between preview versions is required every 3-6 months until a new LTS version is out. There is no point in starting the development process for outdated versions as such versions are supported only for the backward compatibility purposes for the period when a new API version is already out but plugins are not yet switched over to it. The develop version is not recommended to be used as its interface is not yet frozen, the backward compatibility is not provided, and it is subject to change. This version is made available so that new functions could be studied and the plugin could be developed ahead of time for the upcoming API version so that by the time it is released, the plugin is ready (or almost ready) to make new functions available.
The API version, for which the plugin is developed, can be determined by the IFrontPlugininterface version. For example, if a plugin refers to the Resto.Front.Api.V6.dll build and implements the IFrontPlugin interface from this build, it is a V6 plugin.
It is assumed that V6 plugin uses the V6 program interface.
However, if so required, the plugin may concurrently use all supported API versions.
Considering that starting from V6, namespaces do not contain the API version number, in order to avoid collisions between the same-named types from different assemblies, you will have to use extern alias.
For example, to get access to the operation that becomes available only in V7Preview2 using the V6 plugin, it’s enough to add a link to the Resto.Front.Api.V7Preview2.dll build and retrieve the Resto.Front.Api.V7Preview2.IOperationService service from PluginContext.Services.
Important: it is not recommended to implement IFrontPlugin interfaces of different versions—such plugin will not be loaded.
API Version Status and Correspondence to Syrve Instance Versions
| Version | Status | Release | Deletion |
|---|---|---|---|
| V1 | Not supported | 3.1 | 3.8 |
| V2 | Not supported | 3.3 | 4.3 |
| V3 | Not supported | 3.8 | 5.4 |
| V4 | Not supported | 4.3 | 7.0 |
| V5 | Not supported | 5.4 | 8.0 |
| V6Preview4 | Not supported | 6.41 | 7.0 |
| V6Preview5 | Not supported | 6.4 | 7.1 |
| V6 | Outdated | 7.0 | |
| V7Preview1 | Not supported | 7.1 | 7.4 |
| V7Preview2 | Not supported | 7.3.52 | 7.4 |
| V7Preview3 | Not supported | 7.3 | 7.5 |
| V7Preview4 | Not supported | 7.4 | 7.6 |
| V7Preview5 | Not supported | 7.5 | 7.7 |
| V7Preview6 | Not supported | 7.6 | 7.9 |
| V7Preview7 | Outdated | 7.7 | 8.53 |
| V7 | Stable | 7.9 | 9.5 |
| V8Preview1 | Not supported | 8.0 | 8.2 |
| V8Preview2 | Not supported | 8.1 | 8.3 |
| V8Preview3 | Not supported | 8.2 | 8.4 |
| V8Preview44 | Current | 8.3 | 8.6 |
| V8Preview5 | Current | 8.4 | 8.7 |
| V8Preview6 | Current | 8.5 | 8.8 |
| V8Preview7 | Develop | 8.6 | 8.9 |
| V8 | Develop | 8.7 | 10.3 |
| V9Preview1 | 8.8 | 9.1 | |
| V9Preview2 | 8.9 | 9.2 | |
| V9Preview3 | 9.0 | 9.3 | |
| V9Preview4 | 9.1 | 9.4 | |
| V9Preview5 | 9.2 | 9.5 | |
| V9Preview6 | 9.3 | 9.6 | |
| V9Preview7 | 9.4 | 9.7 | |
| V9 | 9.5 | ||
| V10Preview1 | 9.6 | 9.9 | |
| V10Preview2 | 9.7 | 10.0 | |
| V10Preview3 | 9.8 | 10.1 | |
| V10Preview4 | 9.9 | 10.2 | |
| V10Preview5 | 10.0 | 10.3 | |
| V10Preview6 | 10.1 | 10.4 | |
| V10Preview7 | 10.2 | 10.5 | |
| V10 | 10.3 |
1 V6Preview4 was an experimental version, it was released at the beginning of the Syrve Office 6.4 development cycle. Besides, V6Preview6 and V6Preview7 were skipped—V6 LTS version was released instead.
2 Version V7Preview2 was released late at 7.3.5 (instead of 7.2).
3 Support for V7Preview7 has been extended to 8.4 inclusive due to problems with auto-updating plugins from V7Preview7 to V7.
4 The lifespan of Preview versions starting from V8Preview4 has been increased by one version of Syrve Instance.
Starting from version Syrve Instance 8.5, the support cycle for Preview versions increases: version V8Preview4, which was released in 8.3, will be removed only in 8.6, i.e. supported in 8.3, 8.4, 8.5.
Backward Compatibility
The backward compatibility ensures that the plugin developed for a particular API version will work the same with any Syrve Office versions that support this API version.
Program Compatibility
The program compatibility forbids any changes in the public interface: data structures, method signatures, and so on must be frozen. It is clear that if any public class or method is removed, the plugin will stop compiling with the new SDK, whereas the plugin compiled for the previous SDK will crash during the operation (TypeLoadException, MissingMethodException, and so forth). There might be other less obvious malfunction of the backward compatibility. However, if we disregard some uncommon cases, adding a new class, feature, or method might go quite smoothly. But it makes it possible to use new functions without waiting for a new release. With regard to this point, a new policy is adopted:
- No change should be made in LTS versions once they are released as every public change is a breaking change,
- Preview versions imply possibly backward-compatible changes in the public interface.
Behavior Changes
As a general rule, behavior changes of released API versions are not allowed. If a function works in certain conditions, it will continue working, otherwise, it won’t. API destructive use cases, when certain consequences cause more damage than the backward compatibility malfunction, might be an exception to that rule. For example, if API vulnerabilities make some plugin errors to cause data damage or Syrve POS crashes, the API will have a corresponding protection established. This will not be considered a behavior change as properly functioning plugins will not make any difference.
Term of Support
The term of support of any API version means a period of time during which Syrve Office updates that support this API version are released. Syrve RMS products have no calendar limits on the use of any API version. All API versions that are supported by a particular Syrve RMS build are supported permanently. Therefore, if an Syrve RMS user does not update the system, he or she may continue using the plugins as long as possible. However, in practice, a user has to update Syrve RMS to comply with changes in law, to use new functions, or to have some bugs fixed, which means that a plugin developer has to release updates compatible with new API versions in good time.