You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 6 Next »

Introduction

This document explains what conventions and coding guidelines to follow when writing new API(s) for CloudStack or updating the existing ones.

References

Instructions

When you need to introduce a new API command to the CS, you will need to create a Request Class and a Response class (or re-use existing API Response class, if you are extending CS API functionality for which API response is already defined)

Writing CS API Request class

  1. Pick up the *Cmd abstract class to extend by the request. 

CUD (create/update/delete commands):

 

R (read-list) commands:

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.

When to extend BaseAsyncCmd vs BaseAsyncCreateCmd? Use BaseAsyncCreate for the commands creating a new CS entry. For UD commands extend BaseAsyncCmd.

2. Command class that you add, should end with *Cmd, and 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.

Writing CS API Response class

 

API placement and registration

Command placement depends on whether is command is coming as a part of plugin that can be enabled/disabled, or CloudStack core base.

When command comes as a part of CS core base
  • Location: The request/response code should be placed in cloud-api package (src/org/apache/cloudstack/api)
  • 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()

Note that the calls done from the command, should reference only interfaces from cloud-api or cloud-util packages



When command comes as a part of plugin/service
  • Location: Define the command (request/response) in the plugin package
  • Access Permissions: Define the permissions in the Cmd file, @APICommand annotation, "authorized" field. Example: authorized = {RoleType.Admin}) 
  • Command Registration: Make your plugin manager to extent PluggableService interface. Add 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

 

 

 

  • No labels