Last updated March 21, 2009 19:49, by Tim Bray
Feedicon  
<h1>RESTful Cloud Specification - Common Behaviors</h1> '''Version''': 0.1 '''Last Updated''': 9 February 2009 This document specifies constraints that apply to all the requests and responses that occur in the RESTful APIs supported by the Sun Cloud Computing Platform, hereinafter referred to as "The Platform". __TOC__ = Imperative Terms In Specifications = The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document, and all other documents that comprise the specification of The Platform RESTful API, are to be interpreted as described in "Key words for use in RFCs to Indicate Requirement Levels" (RFC 2119). = Transport Protocol = All of The Platform APIs are based on the Hypertext Transfer Protocol, version 1.1 (RFC 2616). Each request will be authenticated using HTTP Basic Authentication (RFC 2617). Therefore, requests sent from clients on the public Internet (and not on a secure channel such as a VPN) '''MUST''' use the ''https'' protocol. = URI Space = The resources in the system are Spaces, Virtual Data Centers (VDCs), Virtual Machines (VMs), VM Templates, and Networks. All are identified by URIs. To begin operations, a client must know the URI for a Space. Dereferencing it will yield a representation of the space containing links to the VDCs, Templates, and Networks in that space. Similarly, dereferencing a VDC will yield a representation that identifies the VMs in the VDC. Clients MUST NOT make assumptions about the layout of the URIs within a Space. = Media Types = In The Platform API, resource representations and request bodies are normally encoded in JSON, as specified in RFC4267. Each type of resource has its own media-type, which matches the pattern ''application/vnd.com.sun.cloud.xxxxx+json'', where "xxxxx" represents the portion of the identifier unique to a particular representation format for each service. The Platform '''MUST''' provide representations of all resources available in JSON. The Platform '''MAY''' also provide resource represenations in HTML when interacting with a human-oriented User-Agent. The Platform '''MUST''' accept requests from clients encoded in JSON. The Platform '''MAY''' also accept ''application/x-www-form-urlencoded'' (i.e. simple HTML forms) for request entities that only need simple name/value pairs. = Request Headers = In requests made to services implementing Sun Cloud Computing Platform APIs, several specific HTTP headers are used as described in the following table: {|- border="1" width="100%" ! Header ! Supported Values ! Description of Use ! Required |- | Accept | Comma-delimited list of media types or media type patterns. | Indicates to the server what media type(s) this client is prepared to accept. | Recommended, on requests that will produce a response message body. |- | Authorization | "Basic " plus username and password (per RFC 2617). | Identifies the authorized user making this request. | Yes, on all requests. |- | Content-Length | Length (in bytes) of the request message body. | Describes the size of the message body. | Yes, on requests that contain a message body.(1) |- | Content-Type | Media type describing the request message body. | Describes the representation and syntax of the request message body. | Yes, on requests that contain a message body. |- | Host | Identifies the origin host receiving the message. | Required to allow support of multiple origin hosts at a single IP address. | All requests. Note that since a single Space may spread its URIs across multiple hosts, this may need to be re-set for each request. |- | X-YYYYY-Client-Specification-Version | String containing a specification version number. | Declares the specification version of the YYYYY API that this client was programmed against. | No (current version is assumed if this header is not present). |} (1) Some APIs '''MAY''' require a "Content-Length: 0" header to be included on a POST request that contains no request message body. Note that, since all interactions with RESTful Sun Cloud Computing Platform APIs are stateless, no ''Cookie'' header (or any other mechanism to provide a session identifier) is used. = Request Parameters = Since the URI space is controlled by the server, client programs MUST not make any assumptions about the meanings of request parameters. = Response Headers = In responses returned by The Platform, several specific HTTP headers are used as described in the following table: {|- border="1" width="100%" ! Header ! Supported Values ! Description of Use ! Required |- | Content-Length | Length (in bytes) of the response message body. | Describes the size of the message body. | Yes, on responses that contain a message body. |- | Content-Type | Media type describing the response message body. | Describes the representation and syntax of the response message body. | Yes, on responses that contain a message body. |- | Location | Canonical URI of a newly created resource. | Returns a new URI that can be used to request a representation of the newly created resource. | Yes, on responses to requests that create new server side resources accessible via a URI. |} FIXME - Document cache control headers and behavior somewhere. = Standard HTTP Status Codes = Sun Cloud Computing Platform APIs will return standard HTTP response codes as described in the following table, under the conditions listed in the description. {|- border="1" width="100%" ! HTTP Status ! Description |- | 200 OK | The request was successfully completed. If this request created a new resource that is addressable with a URI, and a response body is returned containing a representation of the new resource, a 200 status will be returned with a ''Location'' header containing the canonical URI for the newly created resource. |- | 201 Created | A request that created a new resource was completed, and no response body containing a representation of the new resource is being returned. A ''Location'' header containing the canonical URI for the newly created resource should also be returned. |- | 202 Accepted | The request has been accepted for processing, but the processing has not been completed. Per the HTTP/1.1 specification, the returned entity (if any) '''SHOULD''' include an indication of the request's current status, and either a pointer to a status monitor or some estimate of when the user can expect the request to be fulfilled. |- | 204 No Content | The server fulfilled the request, but does not need to return a response message body. |- | 400 Bad Request | The request could not be processed because it contains missing or invalid information (such as validation error on an input field, a missing required value, and so on). |- | 401 Unauthorized | The authentication credentials included with this request are missing or invalid. FIXME - talk about ''WWW-Authenticate'' header in the response. |- | 403 Forbidden | The server recognized your credentials, but you do not possess authorization to perform this request. |- | 404 Not Found | The request specified a URI of a resource that does not exist. |- | 405 Method Not Allowed | The HTTP verb specified in the request (DELETE, GET, HEAD, POST, PUT) is not supported for this request URI. |- | 406 Not Acceptable | The resource identified by this request is not capable of generating a representation corresponding to one of the media types in the ''Accept'' header of the request. |- | 409 Conflict | A creation or update request could not be completed, because it would cause a conflict in the current state of the resources supported by the server (for example, an attempt to create a new resource with a unique identifier already assigned to some existing resource). |- | 500 Internal Server Error | The server encountered an unexpected condition which prevented it from fulfilling the request. |- | 501 Not Implemented | The server does not (currently) support the functionality required to fulfill the request. |- | 503 Service Unavailable | The server is currently unable to handle the request due to temporary overloading or maintenance of the server. |} FIXME - Do we need to worry about redirects? = Error Response Message Bodies = == Introduction == Successful requests will generally return an HTTP status code of 200 (OK), 201 (Created), or 204 (No Content), to indicate that the requested action has been successfully performed. In addition, they might include a response message body (with an appropriate media type) containing a representation of the requested information. However, it is possible for a number of things to go wrong. The various underlying causes are described (as discussed in the previous section) by various HTTP status codes in the range 400-499 (for client side errors) or 500-599 (for server side problems). The description of each request type '''SHOULD''' list the possible status codes returned by that request type. If a response is returned with an error status code (400-499 or 500-599), the server '''SHOULD''' also return a response message body containing a ''messages'' data model, containing zero or more ''message'' data models, describing what went wrong. The text values of such messages might be used, for example, to communicate with a human user of the client side application. == Data Models == Note that these data models, while discussed in the context of reporting error conditions, are also suitable for a general event logging interface, and might get additionally purposed for this use at some point in the future. === Messages Data Model === The entire list of messages included in a single error response are encapsulated in a ''messages'' data model. The media type is ''application/vnd.com.sun.cloud.common.Messages+json'' {|- border="1" width="100%" ! Field Name ! Type ! Occurs ! Description |- | message | Message | 0..n | Zero or more ''message'' data models for each individual message. |} === Message Data Model === An individual ''message'' contains the following fields: {|- border="1" width="100%" ! Field Name ! Type ! Occurs ! Description |- | action | String | 0..1 | Symbolic identifier of the action being performed by the service implementation that triggered the creation of this message. |- | code | String | 0..1 | Symbolic error code identifying the type of error reported by this message. |- | field | String | 0..1 | Name of the input field (from the request data model) that this message is associated with. If not specified, this message should be considered global to the entire request. |- | hint | String | 0..1 | Localized text further describing the nature of the problem, possibly including potential workarounds that the client could try. |- | severity | String | 0..1 | Label indicating the severity of the error condition represented by this message (SEVERE, WARNING, CONFIG, INFO, FINE, FINER, FINEST). |- | source | String | 0..1 | Symbolic identifier of the service implementation component that triggered this message. |- | stack-trace | String | 0..1 | Stack trace associated with this message. |- | '''text''' | String | 1 | Localized text describing the nature of the problem reported by this ''message''. |} '''SECURITY NOTE''': The ''action'', ''source'', and ''stack-trace'' fields may convey sensitive information about the service implementation, and generally '''SHOULD NOT''' be included in messages returned to third party clients outside the cloud firewall. However, they '''MAY''' be used in messages transmitted between internal application components. = Version Request Type = == Introduction == Each instance of a Sun Cloud Computing Service API '''MUST''' provide a request type that allows a client to determine the specification version(s) supported by a particular instance of this API, as well as an implementation version primarily useful in error reporting. This request type '''SHOULD''' have a URI matching ''{ServiceURI}/versions''. == Version Data Model == The media type for a versions request response is ''application/vnd.com.sun.cloud.common.Version+json'' The data model contains the following fields: {|- border="1" width="100%" ! Field Name ! Type ! Occurs ! Description |- | '''implementation_version''' | String | 1 | Implementation version identifier for this service instance. |- | '''specification_version''' | String | 1 | Comma-delimited list of the specification version(s) supported by this service instance. |} Copyright &copy; Sun Microsystems, 2009. This work is licensed under [http://creativecommons.org/licenses/by/3.0/ Creative Commons Attribution 3.0 Unported License]
  • Mysql
  • Glassfish
  • Jruby
  • Rails
  • Nblogo
Terms of Use; Privacy Policy;
© 2013, Oracle Corporation and/or its affiliates
(revision 20140418.2d69abc)
 
 
Close
loading
Please Confirm
Close