REST

Concept

Representational state transfer (REST) invented by Roy Fielding is a way to create, read, update or delete information on a server often using simple HTTP callswas . REST provides guidance on how to implement web application interfaces to the web. Typically, one says a web application is constructed in a REST-like way or not. REST is often associated (or implemented) with HTTP, but it could be implemented with other technologies too. REST is platform and language independent.

• Resource – In REST everything is a resource. A logical resource is any concept (car, dog, user, invoice…) which can be addressed and referenced using a global identifier. Typically, each resource is accessible with a URI when implementing REST over HTTP (for example: http://www.mysite.com/invoice/34657). The preference is given to nouns rather than verbs to indicate the type of a resource (cat, dog, car…).A group of resources can also be accessed with a URI, for example: http://www.mysite.com/user/7723/invoices. REST allows that resources have different representations, e.g., text, XML, JSON etc. The REST client can ask for a specific representation via the HTTP protocol (content negotiation).
• Server – A logical server is where resources are located, together with any corresponding data storage features. Such servers do not deal with end user interfaces (GUI).
• Client – Logical clients make requests to logical servers to perform operations on their resources. For example, a client can request the state of the resource, create a resource, update a resource, delete a resource, etc… Clients do not possess resources or corresponding data storage features. However, they deal with end user interfaces (GUI).
• Request and Responses – The interactions between client and servers is organized with requests from client to server, and responses to requests from server back to client. Requests can contain representations of the resource.
• Representation – A representation is a document representing the current status of a resource. It can also be the new desired status when a client makes a request to update a resource, for example.

Exceptions

There is a general agreement that whatever ‘resource’ is required to implement authentication between the client and the server is considered out-of-scope for REST. These authentication resources do not have to follow REST principles

Principles

• The state of a resource remains internal to the server, not the client – The client can request it, or update it with requests made to the server.
• No client context saved on the server between requests – The server must not store the status of a client. Otherwise, this would break the scalability objective of REST when reaching a couple million users. Remember that requests can be distributed to several physical servers, which could cause physical resource consumption issues.
• Client requests contain all information to service it – No matter which request is sent by a client to a server, it must be complete enough for the server to process it.
• Session states are stored on the client side – If necessary, any information about the status of the communication between a logical server and a logical client must be held on the client side.
• Multiple representations of a resource can coexist – The chosen format used to represent the state of a resource in requests and responses is free (XML, JSON…). Multiple formats can be used.
• Responses explicitly indicate their cacheability – When a server returns a response to a request, the information it contains may or may not be cached by the client. If not, the client should make new requests to obtain the latest status of a resource, for example.
• Code on Demand – This is an optional feature in REST. Clients can fetch some extra code from the server to enrich their functionalities. An example is Javascript.

Implementations

JAX-RS

Java defines REST support via the JSR 311. This specification is called JAX-RS (The Java API for RESTful Web Services), kurz JAX-RS. Es handelt es sich um die Spezifikation einer Programmierschnittstelle (API) der Programmiersprache Java, die die Verwendung von REST im Rahmen von Webservices ermöglicht und vereinheitlicht. Wie auch andere Programmierschnittstellen der Java Platform Enterprise Edition (JEE) benutzt JAX-RS Annotationen, um die Entwicklung und das Deployment von Webservice-Clients und Service-Endpunkten zu vereinfachen.

Annotations

@javax.ws.rs.ApplicationPath(<Path>)

Class annotation which extends javax.wx.rs.core.Application instructs the container to look for JAX-RS annotated classes and install them as endpoints e.g.

@ApplicationPath("/rest")

will lead to

http://localhost:8080/MyFirstJEEWebProjectFromScratch/rest/notes

1. @GET
2. @Path

Implementing a Restful Service with JAX-RS

• implement an empty class with annoation like

@ApplicationPath("/rest")
public class JaxRsActivator extends javax.ws.rs.Application { }

• reuse BaseEntityService as base class of project uweheuer_new and define subclass like

@Path("/notes")
@Stateless // This is a stateless service, so a single shared instance can be used in this case.
public class NotesService extends BaseEntityService<Note>

• annotate changing services like and return response applying the following patterns

@POST
@Consumes(MediaType.APPLICATION_JSON)
public Response saveNote(Note note)
{
  return Response.ok() // creates a response with a status of 200 and an empty entity body.
  return Response.ok(entity) // creates a response with a status of 200, stores the supplied object in the
                             // responses entity body, and determines the entities media type by introspecting the object

}