FluidVM API
From The FluidVM Wiki
Contents |
Introduction
The FluidVM management server presents an XML-RPC interface for clients. There is support for HTTP and HTTS carrier protocols. Most calls to the FluidVM Management Server requires a “cookie” argument. This is a random, 32-bit number returned to the user on being successfully authenticated. The “authenticate” method is used to authenticate users.
The Tasks Framework
The FluidVM Management Server is multi-threaded where every user logged in can have multiple task sets executing. All calls that return some information return immediately with the information in question. There are many calls that get a job done. Like for example creating a user, creating a resource plan, creating virtual servers, setting the memory for a virtual server, etc. These calls will return immediately. But the work they are supposed to do will commence only when the client calls the “commit_tasks” method. This method returns an integer called the Execution Context(EC). A client/user can make multiple calls before calling the “commit_tasks” method. All the tasks made are queued in the execution context and executed one after another. Clients don't have to do anything to create execution contexts, they are automatically created on calling the “commit_tasks” method. All tasks between this call to commit_tasks() and the previous one are queued for execution.
The client can retrieve the status of the executing tasks using 4 functions:
get_task_state()
This function returns the status of each task in the EC as a list. For example, if there are 4 tasks in an EC, a status returned as [0, 0, 1, 1] would mean that task 0 and task 1 are complete, while task 2 and task 3 are being executed or are queued for execution.
get_task_progress()
This function returns a list of task progress values. Progress values are between 1 and 100. Taking the previous example, if there are 4 tasks in an EC, a return value of [100, 100, 34, 0] would mean that task 0 and task 1 have completed 100% execution, while task 3 is complete 34%. Finally, task 4 is yet to start execution.
get_status()
This function returns a string that provides clients some insight into what is happening as far as the tasks are concerned. An empty string is returned if the tasks did not set any status message, which may be true for tasks that are short running.
get_errors()
This function returns an array of error messages set by each task executing in an EC. If the task executed without errors, the error string corresponding to that task will be empty. For example, 3 tasks out of 4 tasks in an EC may have failed. Error messages returned by those 3 will be set, while there will be an empty string for a successful task.
Other Notes
To keep connected clients updated of events happening in the management server, the server returns the list of objects updated recently when the clients call the “ping” method. If there are no updates, an empty list is returned. Clients can then update the user interface (if any) if the objects in question are being displayed currently. For example, if details about a virtual server are being displayed and that object is being mention in the dirty list returned in the “ping” method, the client retrieves information about that virtual server and updates the display. The “ping” method needs to be called at least once every 30 seconds if the user continues to remain logged-in. For one-off tasks, where a user is authenticated, then calls various methods to get a few jobs done and then logs-off, calls to “ping” can be ignored. If user who remain logged in do not make calls to the “ping” method once in at least every 30 seconds, the user will be automatically logged out.
API Tutorials
Please see Category: FluidVM API Tutorials
