Enunciate's REST model is used to provide the metadata required to publish web services in a RESTful manner. The REST model encourages adherence to the fundamental design principles of REST, i.e.:
(see Representational State Transfer on Wikipedia)
Enunciate's REST model encourages adherence to these principles by applying a mapping between REST resources/methods and Java web operations.
The invocation of a RESTful web operation can be associated metaphorically with an English sentence. Each sentence has a verb, a noun (possibly a proper noun), and an optional set of adjectives that describe the verb and the noun, respectively. Likewise, a RESTful web operation has a verb (contrained to a small set, e.g. create, read, update, and delete), a noun (i.e. a resource), and optionally a set of adjectives that describe more specifically on what kind of noun to perform the action. Each Java web operation is that is mapped to RESTful invocation is assigned a verb, a noun, and an optional set of adjectives. Some verbs also support a "noun value" that is the value that is to be associated with the noun.
In it's simplest form, a void no-arg method can be invoked when its verb is applied to its noun. Assuming HTTP, the verb is the HTTP method, and the noun is identified by the URL. For example, consider a Java method defined like so:
public void ping();
If the verb "create" and the noun "ping" are assigned to the method, the "sentence" associated with this method becomes "Create a ping.", and it could be invoked RESTfully over HTTP 1.1 by sending the following over a TCP connection to the endpoint:
PUT /ping HTTP/1.1
It is often desireable to perform an action on a specific noun. Nouns are identified in english sentences by the use of a "proper noun." The noun "person," for example, is often identified specifically through the use of a name, e.g. "Bob." Consider, then, a Java method that is used to retrieve a specific person object out of a database:
public Person getPerson(String personId);
If the verb "read" and the noun "person" were assigned to the method, and the parameter "personId" was identified as a proper noun, the "sentence" associated with this method becomes "get person 12345" where "12345" is the value of the parameter. It could be invoked RESTfully over HTTP 1.1 by sending the following over a TCP connection to the endpoint:
GET /person/12345 HTTP/1.1
While REST implies the use of only one noun (possibly identified by a proper noun), there could be additional parameters to a method invocation adding specificity to what kind of noun to invoke the method on. Consider the following Java method used to find a person by name and birthday (note that in this case, there is no parameter identified as a proper noun):
public Person findPerson(String name, java.util.Date birthday);
If the verb "read" and the noun "person" were assigned to this method, and the parameters used were "Bob" and "01.01.2006" for the name and birthday respectively, the "sentence" associated with this method becomes "find the person whose name is 'Bob' and whose birthday is '01.01.2006'". It could be invoked RESTfully over HTTP 1.1 by sending the following over a TCP connection to the endpoint:
GET /person?name=Bob&birthday=01.01.2006 HTTP/1.1
Enunciate uses JAXB 2.0 to marshal and unmarshal Java objects to/from XML. Since the proper noun and all adjectives must be put on a URL, Enunciate requires the proper noun and all adjectives to be JAXB 2.0 simple types, which means the parameter types of for the adjectives must have a single value element with no attributes. Built-in, these types include the Java primitive types, their associated wrapper classes, java.lang.String, and enums. There is a special exception that adjectives can be a collection or array of simple types.
If there is a parameter type that is a complex type, it must be specified as the noun value for the method. Only the "create" and "update" verbs support a noun value, and only one noun value can be specified per method. Furthermore, complex objects must be JAXB 2.0 root elements in order to correctly. marshall and unmarshall. The return type of a method, if exists, must always be a JAXB 2.0 root element.
At this time, Enunciate does not enable XOP. All binary data is serialized as base64-encoded data.
Exceptions that are thrown will result in an HTTP response code and message. The default error code is 500. Currently, the content of the HTTP response for errors is container-specific and undefined.
REST contrains the set of verbs that can be applied to the available resources. The Enunciate REST Model defines this set to be { "create", "read", "update", "delete" }. Since Enunciate currently only supports HTTP as the RESTful invocation mechanism, it associates this set of verbs with HTTP methods "PUT," "GET," "POST," and "DELETE". The following describes how each verb is applied to its associated noun and adjectives.
The "create" verb is mapped to the HTTP method "PUT." There are no constraints on its use in terms of a proper noun or adjectives, but to "create" a noun often implies the use of a noun value.
Example:
void createPerson(Person value);
HTTP invocation:
PUT /person HTTP/1.1
Content-Type: text/xml
<person><name>Bob</name><birthday>01.01.2006</birthday></person>
Read is the default verb. It is mapped to the HTTP method "GET." The "read" verb does not support the use of a noun value. The read verb often, but not always, implies a proper noun and an optional set of adjectives.
Example:
Person getPerson(String personId);
HTTP invocation:
GET /person/12345 HTTP/1.1
The "update" verb is mapped to the HTTP method "POST." The only real difference between the "update" verb and the "create" verb is that the "update" verb more often implies a proper noun.
Example:
void updatePerson(String personId, Person value);
HTTP invocation:
POST /person/12345 HTTP/1.1
Content-Type: text/xml
<person><name>Bob</name><birthday>01.01.2006</birthday></person>
The "delete" verb is mapped to the HTTP method "DELETE." Like the "read" verb, this verb does not support a noun value.
Example:
void deletePerson(String personId);
HTTP invocation:
DELETE /person/12345 HTTP/1.1