REST Web Service

This post is to continue the last post about XML-Based Web Service. Here, we're going to speak about the second type of web service, the REST.

The REST (REpresentational State Transfer) is an architectural style to build web services. The RESTful is its implementation.
The architecture is client/server, stateless (no state is stored), layered, and supports caching. It's lightweight, easier to learn and to coding then SOAP services.
REST permits different data format: RESTful web service permits different data format such as Plain Text, HTML, XML and JSON.
REST can make use of SOAP as the underlying protocol for web services because, in the end, it is just an architectural pattern.
REST does not need much bandwidth when requests are sent to the server.

A good comparing between SOAP and REST you can see here.

Key Elements

Resources: it is what you need to work. An example is http://www.example.com/rest/person/1
Request Verbs (GET POST, PUT, and DELETE): what you want to do with the resource
Request Headers: additional instructions sent with the request
Request Body: Data is sent with the request
Response Body: This is the main body of the response.
Response Status codes: These codes are the general codes which are returned along with the response from the web server.

RESTful Methods

POST – This would be used to create new data using the RESTful web service
GET - This would be used to get a list of all data using the RESTful web service
PUT - This would be used to update all data using the RESTful web service
DELETE - This would be used to delete all data using the RESTful web service

Response(Status) Codes

You can see some different codes in your response and each one can have a definition. Below a summary of them but you can see detail here.

1XX Codes: Informational Codes
2XX Codes: Success Codes
3XX Codes: URL Redirection
4XX Codes: the client's request error
5XX Codes: Server error

Implementations

JAX-RS: Java API for RESTful Web Services is the Java API for creating REST web services. JAX-RS uses annotations to simplify the development and deployment of web services.
Jersey: "Jersey framework is more than the JAX-RS Reference Implementation. Jersey provides its own API that extends the JAX-RS toolkit with additional features and utilities to further simplify RESTful service and client development. Jersey also exposes numerous extension SPIs so that developers may extend Jersey to best suit their needs."
RESTEasy: It is similar to Jersey. "JBoss project that provides various frameworks to help you build RESTful Web Services and RESTful Java applications. It is a fully certified and portable implementation of the JAX-RS 2.1 specification, a JCP specification that provides a Java API for RESTful Web Services over the HTTP protocol".

Jersey vs JAX-RS

Jersey is an interface to use JAX-RS and provide servlet. JAX-RS is a specification (just a definition) and Jersey is a JAX-RS implementation.
JAX-RS gives you a set of interfaces (standard Java interfaces) which are implemented by Jersey. So that set of interfaces (or classes) are needed as a dependency to be implemented.

Another good post about different implementation you can see here.

Examples

Three good examples you can see in [1][2][3]. These examples illustrate the dependence in pom.xml used with maven, the control class where you can control the resource, and how to test. To test you can use the postman or even the SoupUI. A good tool to document the REST can be the Swagger.

The Levels of REST

The level of the REST, in fact, is the Richardson Maturity Model. To think the level you are using tinkling in this question: Your service is using the advantages that REST can offer?

Martin Flower describe four level to the REST service presented by Leonard Richardson.

Level 0 [Plain Old XML]: this level use HTTP to communicate. It use single POST/GET method only to transport and using XML (or other type) to communicate between services.
Level 1 [Resources]: the API must be using resources that reside at their URLs. Each request is related to an individual resources and not only a singular endpoint.
```
http://example.com/images
http://example.com/images/{image-id}
```
Level 2 [HTTP Verbs]: Use the verbs like HTTP do. For example, use GET many times without any changes to the state. it makes possible use cache. Also, in this level, you can manipulate the response code.
Level 3 [Hypermedia Controls]: or HATEOAS (Hypertext As The Engine Of Application State). The response has a link element which contains a URI, that means what we can do next.

Challenges with the REST API

Lack of Security [4]
Lack of state

Best Practices

When you start to work with any new technologies or languages is a good practices you search the good practices about that :D.

Here I’ll let some good links where we can take a look before create the new endpoints.

Conclusion

REST is not a better solution then SOAP in evere situation. You need to be careful to understand the necessities to decide which one you should use.

When you are building a REST you also need to be careful about the design, test and performance. [5]