# Warm up

This lesson is to get you started and give you an idea about JAX-RS in general. Feel free to skip this if you're not new to the framework.

## What exactly is JAX-RS ?

JAX-RS is a _POJO_ based, _annotation_ driven framework for building web services which comply with RESTful principles. Imagine writing all the low level code to parse a HTTP request and the logic just to wire these requests to appropriate Java classes/methods. The beauty of the JAX-RS API is that it insulates the developer from the complexity and allows them to concentrate on business logic - that's precisely where the use of POJOs and annotations come into play! It has annotations to bind specific URI patterns and HTTP operations to individual methods of your Java class.

**Other notable points**

* More on POJO and Annotation driven approach - POJOs can be modelled as Resources with core business logic (in methods) and can be easily wired up with the HTTP request URI (/books?isbn=1234567) and HTTP verb (GET)
* Both for server and client side - The latest version of the API i.e. JAX-RS 2.0 (JSR ???) provides a client side API as well &#x20;
* Standards driven - The beauty of a standards based API like JAX-RS lies in portability and vendor neutrality. One can easily switch from one implementation to another.

### History

Here is a historical snapshot

| Release version | Year     | Java EE version | MR       |
| --------------- | -------- | --------------- | -------- |
| JAX-RS 1.0      | Oct 2008 | Java EE 6       | Nov 2009 |
| JAX-RS 2.0      | May 2013 | Java EE 7       | Sep 2014 |
| JAX-RS 2.1      | TBD      | Java EE 8       | TBD      |

> * JAX-RS 2.1 is _work in progress_
> * _MR_ stands for Maintenance Release

### Implementations

Here is a list of implementations of the JAX-RS standard

| Name       | Website                                                  | Latest Release (at time of writing) | Packaged with Java EE server |
| ---------- | -------------------------------------------------------- | ----------------------------------- | ---------------------------- |
| Jersey     | jersey.java.net                                          | 2.2.22                              | Glassfish, Weblogic          |
| RESTEasy   | [http://resteasy.jboss.org/](http://resteasy.jboss.org/) | 3.0.12                              | Wildfly, JBoss               |
| Apache CXF | [https://cxf.apache.org/](https://cxf.apache.org/)       | 3.1.6                               | Apache TomEE                 |

> * Jersey serves as the _Reference Implementation_
> * In addition to JAX-RS specification compliance, each implementation also adds it's own proprietary features

## Basic tenets of RESTful services

> This is the only section which talks about REST in a _conceptual_ manner. Throughout the rest of the book, you'll not see references to _abstract_ concepts

REST stands for Representational State Transfer. Let's quickly zip through some of the important _good-to-know-terminologies_ associated with REST

* **Resources** - They are the cornerstone of REST based services. Server and client exchange _representations_ of the resource. REST is not about making RPC based calls by simply using XML/JSON payloads (of course no one cab prevent you from doing so - but that cannot be called RESTful)
* **Addressable** - The resource(s) should be reachable via a URI e.g. [https://api.github.com/search/repositories](https://api.github.com/search/repositories)
* **HTTP based** - One must be able to interact with resources (CRUD) using standard HTTP (GET,PUT,POST, DELETE etc) e.g. Issue a HTTP GET to the URI [https://api.github.com/search/repositories?q=user:abhirockzz](https://api.github.com/search/repositories?q=user:abhirockzz)
* **Stateless** - HTTP (which is the cornerstone of REST) is inherently stateless protocol and each RESTful payload should contain the related state. There is no co-relation b/w two subsequent requests even if they are the same. Also, a RESTful API should not depend on _previous_ state related data to be sent by the client
* **Interaction via&#x20;**_**Hyperlinks**_ - Let hyperlinks drive the application. Client friendly practice popularly known as _HATEOAS_ (Hypermedia As The Engine Of Application State)

> What's important to know is that the JAX-RS framework embraces these principles and helps you create RESTful services and APIs
