RestFull Web Services
REST (Representational State Transfer )
In a REST based architecture everything is a resource. REST allows that resources have different representations, e.g. text, xml, json etc. The rest client can ask for specific representation via the HTTP protocol (Content Negotiation).
HTTP methods
The HTTP standards methods which are typical used in REST are PUT, GET, POST, DELETE.- GET defines a reading access of the resource without side-effects. The resource is never changed via a GET request, e.g. the request has no side effects (idempotent).
- PUT creates a new resource, must also be idempotent.
- DELETE removes the resources. The operations are idempotent, they can get repeated without leading to different results.
- POST updates an existing resource or creates a new resource.
RESTFul webservices
A RESTFul webservices is based on the HTTP methods and the concept of REST. It typically defines the base URI for the services, the MIME-types its supports (XML, Text, JSON, user-defined,..) and the set of operations (POST, GET, PUT, DELETE) which are supported. JAX-RS supports the creation of XML and JSON via JAXB .Java, REST and Jersey
Java defines standard REST support via JAX-RS (The Java API for RESTful Web Services) in JSR 311 .JAX-RS uses annotations to define the REST relevance of classes.Via your "web.xml" you will register a servlet provided by Jersey and also define the path under which your REST web application will be available. The base URL of this servlet is:
http://your_domain:port/display-name/url-pattern/path_from_rest_class
This servlet which analyze the incoming HTTP request and select the correct class and method to respond to this request. This selection is based on annotation in the class and methods.The most important annotations in JAX-RS are the following.
Table 1. Sample Table
- AnnotationDescription@PATH(your_path)Sets the path to base URL + /your_path. The base URL is based on your application name, the servlet and the URL pattern from the web.xml" configuration file.@POSTIndicates that the following method will answer to a HTTP POST request@GETIndicates that the following method will answer to a HTTP GET request@PUTIndicates that the following method will answer to a HTTP PUT request@DELETEIndicates that the following method will answer to a HTTP DELETE request@Produces( MediaType.TEXT_PLAIN [, more-types ] )@Produces defines which MIME type is delivered by a method annotated with @GET. In the example text ("text/plain" ) is produced. Other examples would be "application/xml" or "application/json".@Consumes( type [, more-types ] )@Consumes defines which MIME type is consumed by this method.@PathParamUsed to inject values from the URL into a method parameter. This way you inject for example the ID of a resource into the method to get the correct object.
The complete path to a resource is therefore based on the base URL and the @PATh annotation in your class.
http://your_domain:port/display-name/url-pattern/path_from_rest_class
Jersey is the reference implementation for this specification. Jersey contains basically a REST server and a REST client. The core client is mainly available for testing and provides a library to communicate with the server.A REST web application consists out of data classes (resources) and services. These two types are typically maintained in different packages as the Jersey servlet will be instructed via the "web.xml"to scan certain packages for data classes.
Best Practices
URI Opacity
The creator of a URI decides the encoding of the URI, and users should not derive metadata from the URI itself. URI opacity only applies to the path of a URI. The query string and fragment have special meaning that can be understood by users. There must be a shared vocabulary between a service and its consumers.Query String Extensibility
Service provider should ignore any query parameters it does not understand during processing. If it needs to consume other services, it should pass all ignored parameters along. This practice allows new functionality to be added without breaking existing services.Server-Driven Negotiation
- When delivering a representation to its client, a server MUST check the following HTTP headers: Accept, Accept-Charset, Accept-Encoding, Accept-Language, and User-Agent to ensure the representation it sends satisfies the user agent's capability.
- When consuming a service, a client should set the value of the following HTTP headers: Accept, Accept-Charset, Accept-Encoding, Accept-Language, and User-Agent. It should be specific about the type of representation it wants and avoid "*/*", unless the intention is to retrieve a list of all possible representations.
- A server may determine the type of representation to send from the profile information of the client.
Service Provider Responsibility
If there is more than one representation available for a resource, the service should negotiate with the client as discussed above. When returning a representation, a service provider should set the HTTP headers that relate to caching policies for better performance.A safe service is by its nature idempotent. A service provider should not break this constraint. Clients should expect to receive consistent representations.
Obligated Services
Obligated services should be implemented using POST. A request to an obligated service should be described by some kind of XML instance, which should be constrained by a schema. The schema should be written in W3C XML Schema or Relax NG. An obligated service should be made idempotent so that if a client is unsure about the state of its request, it can send it again. This allows low-cost error recovery. An obligated service usually has the simple semantic of "process this" and has two potential impacts: either the creation of new resources or the creation of a new representation of a resource.
Status URI
The status resource can be seen as a different view of its associated transaction resource. The status URI should only differ in the query string with an additional status parameter. For example:Transaction URI: http://www.example.com/xyz2343 Transaction Status URI: http://www.example.com/xyz2343?view=statusRequest Result
A request result view should be regarded as a special view of a transaction. One may create a request resource and transaction resources whenever a request is received. The result should use XML markup that is as closely related to the original request markup as possible.Receiving and Sending XML
When receiving and sending XML, one should follow the principle of "strict out and loose in." When sending XML, one must ensure it is validated against the relevant schema. When receiving an XML document, one should only validate the XML against the smallest set of schema that is really needed. Any software agent must not change XML it does not understand.An Implementation Architecture
http://download.oracle.com/docs/cd/E12840_01/wls/docs103/webserv_adv/rest.html http://jersey.java.net/nonav/documentation/latest/user-guide.html
http://www.vogella.de/articles/REST/article.html
Comments
Post a Comment