...
Instructions
When you need to introduce a new API command to CS, you will need to create a Request Class and a Response class (or re-use an existing API Response class, if you are extending CS API functionality for which the API response is already defined)
...
The main rule is - all APIs should remain backwards compatible. It means that:
- In the Request: Don't change the parameter from optional to required.
- DonIn the Request: Don't add a new parameter to an existing command with required=true option.
- DonIn the Request: Don't reduce the command permission from being available to normal user to becoming available to Admin only.
- DonIn the Request/Response: Don't rename existing parameters.
- DonIn the Request/Response: Don't change the parameter type (from String to Map for example).
- In the Response: Don't remove the parameter from the response as the third party software can rely on its presence.
Other rules:
- When a new parameter is added, it should be set with "since=release #" field in @Parameter annotation.
- If you think that some parameter should be removed in the future, mark it with @Deprecated and make sure it's documented for the n release. Once it's released, the customers will get a chance to review/change their code to get rid of this parameter, so it can be removed in the n+1 release.
...