REST

The Rightscale API follows the REST (REpresentational State Transfer) paradigm, and all its common verbs and actions.  The API places great importance on consistency and organization of requests and response types. Emphasis has been placed on making resource relationships and available actions discoverable on the fly.

Every resource response includes three sections of information:

1. A list of resource attributes - Includes the name, state, and the created_at for an Instance resource. Sometimes a resource will also include the contents of a related resource to avoid having to perform an extra request to retrieve more contents. For example, some responses for an instance might include the complete contents of its inputs, instead of just a URL pointing to them. (See "views" for more details on this.) There are some attributes that can override contents inherited from other related resources. (For example an instance can override the user_data inherited from its template.)  For these inheritable attributes, the resource body will have a special section that will indicate the source of its contents.
2. A list of links - Specifies the relationships that the resource has. Each link will have a well-known relationship name, and the URI to get its relationship contents. Every resource will have at least the "self" relationship, with a URL pointing to itself. This is effectively the unique ID for the resource that will be immutable throughout the lifetime of the resource and beyond.

3. A list of actions to execute - These actions are contextual, for example, there can be a "launch" action for an instance that is stopped, but there will not be one if the instance is already running. For the moment, these actions are limited to a list of well-known names, but expect to provide more information (metadata) about them later (verb to use, URL, etc.).

Each response will return a specific RightScale "Content-Type" header specifying a MediaType structure. For example: servers will return "application/vnd.rightscale.server". The format of each resource media type is documented in the API Online Reference documentation. A MediaType is a human-readable schema definition for a given resource . There is no validator or similar concept like there could be in some XML formats. In other words a media type will define everything that could appear in a response of that type of resource. For calls that return a collection of items of a given MediaType, the content type will include a "type=collection" parameter (i.e., "application/vnd.rightscale.server; type=collection").