This document explains what conventions and coding guidelines to follow when writing new API(s) for CloudStack or updating the existing ones.
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)
1. Pick up the *Cmd abstract class to be extended by the request.
CUD (create/update/delete commands):
R (read-list) commands:
IMPORTANT - starting 2.x, new CUD API commands can no longer extend BaseCmd class; they should come as Async commands and extend either BaseAsyncCmd, or BaseAsyncCreateCmd.
When to extend BaseAsyncCmd vs BaseAsyncCreateCmd? Use BaseAsyncCreate for commands creating a new CS entry. For UD commands extend BaseAsyncCmd.
2. The command class you add should end with *Cmd and be annotated with @ApiCommand. Read more about @ parameters in Annotations use in the API ref.
3. Define all request parameters. Annotate them all with @Parameter.
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 the context. Only if none of those prependers fit your logic, use your own (assign for example).
The command placement depends on whether the command is coming as a part of a plugin that can be enabled/disabled, or the CloudStack core base.
Note that the calls done from the command, should reference only interfaces from cloud-api or cloud-util packages.
Command Registration: Make your plugin manager extend PluggableService interface. Add the new API command to the list of commands returned by getCommands().
The commands defined in the plugin should reference only interfaces located in cloud-api/cloud-utils/<your plugin> packages.
The main rule is - all APIs should remain backwards compatible. It means that:
Other rules: