Page History

...

• Annotations use in the API
• CloudStack general Coding conventions
• CloudStack IAM guidelines for API and Service Layer - refer to these to know how to use IAM for access control in your APIs
• CloudStack API Development - API as a Pluggable service
  
  

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:

1. In the Request: Don't change the parameter from optional to required.
2. DonIn the Request: Don't add a new parameter to an existing command with required=true option.
3. DonIn the Request: Don't reduce the command permission from being available to normal user to becoming available to Admin only.
4. DonIn the Request/Response: Don't rename existing parameters.
5. DonIn the Request/Response: Don't change the parameter type (from String to Map for example).
6. In the Response: Don't remove the parameter from the response as the third party software can rely on its presence. 

Other rules:

1. When a new parameter is added, it should be set with "since=release #" field in @Parameter annotation. 
2. 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.

...