Page History

...

CUD (create/update/delete commands):

R (read-list) commands:

Important IMPORTANT - starting 2.x, new CUD API command can no longer extend BaseCmd class; they should come as Async command, and extend either BaseAsyncCmd, or BaseAsyncCreateCmd.

...

4. Implement execute() for RUD commands, and execute()/create() for C commands.

5. Add s_name - the response name. Should be specified in lower case.

6. When thinking about the command name, prepend it with create/delete/update/list depending on a context. Only if none of those prependers fit your logic, use your own (assign for example)

Writing CS API Response class

...

1. Make your class extend BaseResponse
2. Annotate the class with @EntityReference set with the CloudStack interface representing the object you are returning to the API user. For example, VolumeResponse has @EntityReference set with Volume.
3. Annotate each parameter with @SerializedName and @Param annotations. See more details on these annotations in Annotations use in the API 
4. Parameter names should be lower case
5. Make sure that you don't expose actual DB ids by setting them to your Ids fields. Use UUID value instead.

API placement and registration

...

• Location: The request/response code should be placed in cloud-api package (src/org/apache/cloudstack/api)/cloud-engine-api packages
• Access permissions: The command's access control permissions (who is eligible to call  should be registered in commands.properties.in file
• Command registration: The command should be added to the list of all APIs CS supports, returned by ManagementServerImpl. getCommands()

...

The commands defined in the plugin, should reference only interfaces located in cloud-api/cloud-utils/<your plugin> packages

Rules when modify an existing APIs

The main rule is - all APIs should remain backwards compatible. It means that:

1. Don't change the parameter from optional to required
2. Don't add a new parameter to existing command with required=true option
3. Don't reduce the command permission from being available to normal user, to becoming available to Admin only
4. Don't rename existing parameters.
5. Don't change the parameter type (from String to Map for example)

Other rules:

1. When 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 its documented for the n release. Once its 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.