Rest overview briefing

REST OVERVIEW
Viquar Mohammed Khan
+1-224-436-0783

INTRODUCTION
REST (Representational State Transfer) which was detailed in Roy Thomas Fielding's doctorate dissertation
"Architectural Styles and the Design of Network-based Software Architectures" in year 2000, which can
dramatically reduce the investment necessary to provide service-oriented access to enterprise resources. Fielding
used the term to describe a technique and best practices for retrieving data formatted in XML over HTTP for use in
applications.
REST is an architectural style, not a standard or specification, built on existing, well-understood standards governed
by the W3C, such as HTTP, URI (Uniform Resource Identifier) and RDF(Resource Description Format). REST
services are focused on access to resources.
1

REST :
So this means areas that REST works really well for are:
 Limited bandwidth and resources; remember the return structure is really in any format (developer
defined). Plus, any browser can be used because the REST approach uses the standard GET, PUT,
POST, and DELETE verbs. Again, remember that REST can also use the XML HttpRequest object
that most modern browsers support today, which adds an extra bonus of AJAX.
 Totally stateless operations; if an operation needs to be continued, then REST is not the best
approach and SOAP may fit it better. However, if you need stateless CRUD (Create, Read, Update,
and Delete) operations, then REST is it.
 Caching situations; if the information can be cached because of the totally stateless operation of the
REST approach, this is perfect.
SOAP :
 Asynchronous processing and invocation; if your application needs a guaranteed level of reliability
and security then SOAP 1.2 offers additional standards to ensure this type of operation. Things like
WSRM – WS-Reliable Messaging.
 Formal contracts; if both sides (provider and consumer) have to agree on the exchange format then
SOAP 1.2 gives the rigid specifications for this type of interaction.
 Stateful operations; if the application needs contextual information and conversational state
management then SOAP 1.2 has the additional specification in the WS* structure to support those
things (Security, Transactions, Coordination, etc). Comparatively, the REST approach would make the
developers build this custom plumbing.
2
SOAP VS REST

APACHE CXF
5
PROJECT HOME http://cxf.apache.org/
ABOUT Apache CXF is an open source services framework. CXF helps you build and develop services using
frontend programming APIs, like JAX-WS and JAX-RS. These services can speak a variety of protocols
such as SOAP, XML/HTTP, Restful HTTP, or CORBA and work over a variety of transports such as
HTTP, JMS or JBI.
Developer(s) Apache Software Foundation
License Type Apache License
Released February 18, 2015 - Apache CXF 3.0.4
Download Page http://cxf.apache.org/download.html
Development Status Active
Tutorial/Getting started http://www.javatips.net/blog/2012/02/cxf-restful-tutorial
Forum Mailing List: http://cxf.apache.org/mailing-lists.html
Support: http://cxf.apache.org/support.html
Support for Java 7 Yes

JERSEY
6
PROJECT HOME https://jersey.java.net/
ABOUT Jersey RESTful Web Services framework is open source, production quality, framework for developing
RESTful Web Services in Java that provides support for JAX-RS APIs and serves as a JAX-RS (JSR 311
& JSR 339) Reference Implementation. Jersey provides it’s own API that extend the JAX-RS toolkit with
additional features and utilities to further simplify RESTful service and client development.
Developer(s) Oracle Corporation
License Type CDDL version 1.1 and GPL v2 license
Released August 2008 (Not sure) (One post indicates that it was available since 2007)
Last Release Jersey 2.19 / June 29, 2015
Download Page https://jersey.java.net/download.html
Tutorial/Getting started https://jersey.java.net/documentation/latest/getting-started.html
http://www.vogella.com/tutorials/REST/article.html
Forum Mailing List: users@jersey.java.net
Stake overflow: http://stackoverflow.com/questions/tagged/jersey
Issue Tracking: https://java.net/jira/browse/JERSEY

RESTLET
7
PROJECT HOME http://restlet.com/
ABOUT Restlet Framework is the leading RESTful web API framework for Java. Its unique Java API is available
on both client and server sides, in six consistent editions: Java SE, Java EE, Android, GAE, GWT and
OSGi! This project has been around for a long time and implemented REST before REST was popular.
JAX-RS was a natural extension
Developer(s) Jerome Louvel & Thierry Boileau of Noelios Consulting (now Aeon Consulting partner) and Restlet
community
License Type Apache license 2.0, LGPL license 3.0, LGPL license 2.1, CDDL license 1.0, EPL license 1.0
Released 2005
Last Release 2.3.3 / May 21, 2015
Download Page http://restlet.com/downloads/current/
Tutorial/Getting started http://restlet.com/technical-resources/restlet-framework/guide/2.2
http://restlet.com/technical-resources/restlet-framework/guide/2.3/extensions/jaxrs
Forum http://restlet-discuss.1400322.n2.nabble.com/

RESTEASY
8
PROJECT HOME http://resteasy.jboss.org/
ABOUT RESTEasy is a 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
specification.
Developer(s) Jboss (redhat)
License Type Apache License, Version 2.0
Released Jan 2009
Last Release Release 3.0.9/Sep 2014
Download Page http://sourceforge.net/projects/resteasy/files/Resteasy%20JAX-RS/
Tutorial/Getting started https://developer.jboss.org/wiki/ResteasyWIKI
http://www.mastertheboss.com/resteasy/resteasy-tutorial
https://www.youtube.com/watch?v=Re8CggeqDr4
Forum http://resteasy.jboss.org/mailinglists

DROPWIZARD
9
PROJECT HOME https://dropwizard.github.io/dropwizard/
ABOUT Dropwizard is a Java framework for developing ops-friendly, high-performance, RESTful web services.
Dropwizard pulls together stable, mature libraries from the Java ecosystem into a simple, light-weight
package that lets you focus on getting things done. Dropwizard has out-of-the-box support for
sophisticated configuration, application metrics, logging, operational tools, and much more, allowing you
and your team to ship a production-quality web service in the shortest time possible.
Developer(s) Yammer Inc.
License Type Apache License, Version 2.0
Released Dec 2011
Last Release July 06, 2015 – Version 0.8.2
Download Page https://dropwizard.github.io/dropwizard/getting-started.html
Tutorial/Getting started https://dropwizard.github.io/dropwizard/getting-started.html
https://www.openshift.com/blogs/day-13-dropwizard-the-awesome-java-rest-server-stack
Forum https://groups.google.com/forum/#!forum/dropwizard-user

SPRING REST
10
PROJECT HOME
ABOUT Spring Framework is an open source services framework. Spring Rest helps you build and develop
services using frontend programming APIs supported by Spring MVC, Spring Rest not JAX-RS
compliant.
Developer(s) pivotal
License Type Apache License 2.0
Released March 2004
Last Release 4.2.0-SNAPSHOT / December 26, 2014
Download Page http://maven.apache.org/download.cgi
http://gradle.org/gradle-download/
Tutorial/Getting started https://spring.io/guides/gs/rest-service/
https://github.com/spring-guides/gs-rest-service
Forum http://stackoverflow.com/questions/tagged/spring-restdocs
http://forum.spring.io/forum/spring-projects/web
Support for Java 7

COMPARISON
 We checked both Spring MVC and JAX-RS compliant frameworks to see what may be the most suitable
technology for your purpose.
 We think that both technologies can do whatever you want to achieve with it, although there are
philosophical divergences in approach and design. Mainly that Spring is controller hierarchy, while JAX-
RS frameworks adopt a resource hierarchy.
 JAX-RS is a specification (JSR311), and you have the advantage of replacing Jersey with Apache CXF
or RESTEasy (theoretically) without effecting your main codebase. Most of the JAX-RS frameworks
support spring integration, so technically your own functional code wouldn't need to change, except for
configuration of JAX-RS frameworks.
 Sticking with existing Spring MVC would of course lend towards "less framework explosion" than
introducing another paradigm and more framework(s)
 Going with a JAX-RS framework, however might force you, in a good way, to think in terms of resources
first, and encourage logical separation.
11

COMPARISON (CONT.…)
 All of these are mature and production ready frameworks. They all have integration capabilities with
Spring And of have support to documentation and contract specification , Chances of going wrong with
any of them is minimal..
 CXF JAX-RS is implemented as a CXF filter sitting behind the servlets, while Jersey and RestEasy are,
servlet filters.
 One unique advantage with CXF is that it makes it very easy to produce both a JAX-RS and JAX-WS
(SOAP) endpoint from the exact same data model and service interface at the same time. So if that is
something which matters to you, this may be the way to go. CXF had issues with handling SSL and
HTTP proxies which seems to have been addressed in recent releases
 Restlet based program can run as a standalone Java application. The restlet also supports Java EE
environment with the help of Jetty web container. So this may result into a light-weight implementation
and have unique value that way. There are some challenges or manual work involved in de-marshalling
the response into java object.
12

COMPARISON (CONT.…)
 RESTEasy may be a good choice if your environment is Jboss oriented. It also provides good
integration with EJB 3.0 and SEAM (something to consider if you have a need for that). Also it has a
proprietary caching for URL or query which could be handy for high volume applications.
 Jersey has some of the best tooling (IDE) support specially if you are using NetBeans. So you can
achieve better productivity from tooling perspective. There are some challenges with Jersey-Spring
integration specially with AOP. Also since it is a reference implementation for JAX-RS, it will continue
to support any updates to the specification.
 DROPWIZARD promises improved performance and ease of development and has out-of-the-box
support for sophisticated configuration, application metrics, logging, operational tools etc. It aims to
integrate best of breed features and best practices components, something which may be good to
consider from a technical debt perspective as well (use of best of breed libraries tend to reduce
technical debt).
 Spring Rest is Easy to use and inbuilt support by spring framework. It using Jekson for convert object to
JSON. Spring Rest has its rich API and annotation support. Spring Rest is not JAX-RS compliant.
13

REST SECURITY
Basic Authentication w/ TLS/SSL
1) In the authentication process, a TLS/SSL client sends a message to a TLS/SSL server, and the
server responds with the information that the server needs to authenticate itself. The client and
server perform an additional exchange of session keys, and the authentication dialog ends.
2) When authentication is completed, SSL-secured communication can begin between the server
and the client using the symmetric encryption keys that are established during the
authentication process.
Link:
http://www-01.ibm.com/support/knowledgecenter/SSPVUA_9.0.1/com.ibm.p8.installingmcs.doc/mcsin051.htm
http://java2novice.com/restful-web-services/http-basic-authentication/
http://www.codingpedia.org/ama/how-to-secure-jersey-rest-services-with-spring-security-and-basic-authentication/

REST SECURITY
Basic Authentication pros and cons
Pros:
Basic authentication is the easiest of the three to implement, because the majority of the time, it
can be implemented without additional libraries. Everything needed to implement basic
authentication is usually included in your standard framework or language library.
Cons:
The problem with basic authentication is that it is, well “basic”, and it offers the lowest security
options of the common protocols. There are no advanced options for using this protocol, so
you are just sending a username and password that is Base64 encoded. Basic authentication
should never be used without TLS (formerly known as SSL) encryption because the username
and password combination can be easily decoded otherwise.
Passwords are reset often. If you use the password as part of your API authentication scheme,
API access would fail every time the password is changed.
Rest API logout issue, How to perform logout.
15

REST SECURITY
Oauth :
• OAuth is an open standard for authorization. OAuth provides client applications a 'secure delegated
access's to server resources on behalf of a resource owner. It specifies a process for resource owners
to authorize third-party access to their server resources without sharing their credentials.
• Designed specifically to work with Hypertext Transfer Protocol (HTTP), OAuth essentially allows access
tokens to be issued to third-party clients by an authorization server, with the approval of the resource
owner, or end-
• user. The client then uses the access token to access the protected resources hosted by the resource
server. OAuth is commonly used as a way for Internet users to log into third party websites using their
Microsoft, Google, Facebook or Twitter accounts without exposing their password.
• OAuth is a service that is complementary to, and therefore distinct from, OpenID. OAuth is also distinct
from OATH, which is a reference architecture for authentication, not a standard for authorization.
16

REST SECURITY
Oauth 1.0a:
OAuth Core 1.0 (also known as RFC 5849), the community-based specification published on December
4th, 2007, revised June 24th, 2009, and finalized in April 2010 is one of the fastest growing Open Web
specifications. It provides a much needed solution for security web APIs without requiring users to share
their usernames and passwords.
https://github.com/ddo/oauth-1.0a
Note :Important: OAuth 1.0 was officially deprecated on April 20, 2012, and is no longer supported. We
encourage you to migrate to OAuth 2.0 as soon as possible.
17

Oauth 1.0 a pros and cons
Pros:
Oauth 1.0a is the most secure of the three common protocols. Oauth1 is a widely-used, tested, secure,
signature-based protocol. The protocol uses a cryptographic signature, (usually HMAC-SHA1) value
that combines the token secret, nonce, and other request based information. The great advantage of
OAuth 1 is you never directly pass the token secret across the wire, which completely eliminates the
possibility of anyone seeing a password in transit. This is the only of the three protocols that can be
safely used without SSL (although you should still use SSL if the data transferred is sensitive).
Cons:
This level of security comes with a price: generating and validating signatures can be a complex
process. You have to use specific hashing algorithms with a strict set of steps. However, this
complexity isn’t often an issue anymore as every major programming language has a library to handle
this for you.
18
REST SECURITY

REST SECURITY
OAuth 2.0 :
OAuth 2.0 is the next evolution of the OAuth protocol which was originally created in late 2006. OAuth
2.0 focuses on client developer simplicity while providing specific authorization flows for web
applications, desktop applications, mobile phones, and living room devices. This specification is being
developed within the IETF OAuth WG and is based on the OAuth WRAP proposal.
19

REST SECURITY
OAuth 2.0 a pros and cons
Pros:
Oauth2’s current specification removes signatures, so you no longer need to use cryptographic
algorithms to create, generate, and validate signatures. All the encryption is now handled by TLS,
which is required. There are not as many Oauth2 libraries as there are Oauth1a libraries, so integrating
this protocol into your API may be more challenging.
Cons:
OAuth2’s default settings are less secure than OAuth1 (no digital signature means you can’t verify if
contents have been tampered with before or after transit), we recommend OAuth1 over OAuth2 for
sensitive data applications. OAuth2 could make sense for less sensitive environments, like some social
networks.
20

JAX-RS SECURITY SUPPORT
https://jersey.java.net/documentation/latest/security.html
https://docs.oracle.com/middleware/1212/wls/RESTF/secure-restful-service.htm#RESTF284
21

SPRING SECURITY SUPPORT
http://www.networkedassets.com/en/configuring-spring-security-for-a-restful-web-services/
http://www.baeldung.com/2011/10/31/securing-a-restful-web-service-with-spring-security-3-1-part-3/
22

HATEOAS
Hypermedia as the Engine of Application State, is a constraint of the REST application architecture that
distinguishes it from most other network application architectures.
A hypermedia-driven site provides information to navigate the site's REST interfaces dynamically by
including hypermedia links with the responses.
Layman terms HATEOAS means provide all required information to client with response so client can
use same information for further call or logics.
A simple JSON presentation is traditionally rendered as:
{ "name" : “Vaquar" }
HATEOAS-based response would look like this:
{ "name": “Vaquar",
"links": [ { "rel": "self", "href": "http://localhost:8080/customer/1" } ]
}
 Example:
 http://keaplogik.blogspot.com/2015/01/spring-hateoas-embedded-resources-with.html
23

HATEAOAS provides a way to interact with the REST API entirely through hyperlinks. With each call
that you make to the API, we’ll return an array of links that allow you to request more information about
a call and to further interact with the API. You no longer need to hard code the logic necessary to use.
There are three components for each link in a HATEOAS links array:
 href: URL of the related HATEOAS link you can use for subsequent calls.
 rel: Link relation that describes how this link relates to the previous call.
 method: The HTTP method required for the related call.
[ {
"href": "https://api.sandbox.paypal.com/v1/payments/payment/PAY-6RV70583SB702805EKEYSZ6Y",
“
rel": "self",
"method": "GET"
}, {
"href": "https://api.sandbox.paypal.com/v1/payments/payment/PAY-
6RV70583SB702805EKEYSZ6Y/execute",
"rel": "execute",
"method": "POST"
} ]
24

RICHARDSON MATURITY MODEL
'
25

Level 0: Swamp of POX
Level 0 uses its implementing protocol (normally HTTP, but it doesn't have to be) like a transport protocol.
That is, it tunnels requests and responses through its protocol without using the protocol to indicate
application state. It will use only one entry point (URI) and one kind of method (in HTTP, this normally is
the POST method). Examples of these are SOAP and XML-RPC.
Level 1: Resources
When your API can distinguish between different resources, it might be level 1. This level uses multiple URIs,
where every URI is the entry point to a specific resource. Instead of going through
http://example.org/articles, you actually distinguish between http://example.org/article/1 and
http://example.org/article/2. Still, this level uses only one single method like POST.
26

Level 2: HTTP verbs
API MUST use HTTP verbs. It doesn't. REST is completely protocol agnostic, so if you want to use a
different protocol, your API can still be RESTful.
This level indicates that your API should use the protocol properties in order to deal with scalability and
failures. Don't use a single POST method for all, but make use of GET when you are requesting
resources, and use the DELETE method when you want to delete a resources. Also, use the response
codes of your application protocol. Don't use 200 (OK) code when something went wrong for instance.
By doing this for the HTTP application protocol, or any other application protocol you like to use, you
have reached level 2.
Level 3: Hypermedia controls
Level 3, the highest level, uses HATEOAS to deal with discovering the possibilities of your API towards the
clients. More information about HATEOAS can be found below.
- See more at: http://restcookbook.com/Miscellaneous/richardsonmaturitymodel/#sthash.hKwUyXJn.dpuf
27

ERROR HANDLING
Best Practices for REST Error Handling
Human Readable Error Messages: Part of the major appeal of REST based web services is that you
can open any browser, type in the right URL, and see an immediate response -- no special tools
needed. However, HTTP error codes do not always provide enough information. For example, if we take
option 1 above, and request and invalid book ID, we get back a 404 Error Code. From the developer
perspective, have we actually typed in the wrong host name, or an invalid book ID? It's not immediately
clear. In Option 3 (DAS), we get back a blank page with no information. To view the actual error code,
you need to run a network sniffer, or point your browser through a proxy. For all these reasons, I think
Option 4 has a lot to offer. It significantly lowers the barrier for new developers, and enables all
information related to a web service to be directly viewable within a web browser.
Application Specific Errors: HTTP status codes are specific to document retrieval and posting, and
these may not map directly to your application domain. For example, one of the DAS error codes relates
to invalid genomic coordinates (sequence coordinate is out of bounds/invalid). What HTTP error code
would we map to in this case?
Machine Readable Error Codes: As a third criteria, error codes should be easily readable by other
applications.
http://www.codingpedia.org/ama/error-handling-in-rest-api-with-jersey/
28

REST VERSION
A commonly used way to version your API is to add a version number in the URL.
For instance:
/api/v1/article/1234
To "move" to another API, one could increase the version number:
/api/v2/article/1234
The hypermedia way
GET /api/article/1234 HTTP/1.1 Accept: application/vnd.api.article+xml; version=1.0
M E R V A / B O X 29

REST PARTIAL RESPONSE AND PAGINATION
Partial Response :
Making API faster we can filter Rest response based on given criteria , instead of returning full objects in API
responses with all the data fields, only a subset of data fields are returned. The benefit is obvious —- less data
transferred over the network means less bandwidth usage, faster server response, less CPU time spent on the
server and client, as well as less memory usage on the client.
Example:
https://blog.apigee.com/detail/restful_api_design_can_your_api_give_developers_just_the_information
https://developers.google.com/youtube/2.0/developers_guide_protocol_partial
Pagination:
Pagination is the process of dividing (content) into discrete pages, It is necessary to anticipate the paging of your
resources in the early design phase of your API. It is indeed difficult to foresee precisely the progression of the
amount of data that will be returned.
http://blog.octo.com/en/design-a-rest-api/
https://developer.atlassian.com/confdev/confluence-rest-api/pagination-in-the-rest-api
http://dev.billysbilling.com/blog/How-to-make-your-API-better-than-the-REST
30

REST TESTING
Following testing tools available to perform end to end Rest testing
https://github.com/spring-projects/rest-shell
https://addons.mozilla.org/en-us/firefox/addon/poster/
https://spring.io/blog/2009/03/27/rest-in-spring-3-resttemplate
http://howtodoinjava.com/2015/02/20/spring-restful-client-resttemplate-example/
http://www.soapui.org/rest-testing/getting-started.html
31

REST CACHING
32
The goal of caching is never having to generate the same response twice. The benefit of doing this is that we
gain speed and reduce server load. The best way to cache your API is to put a gateway cache (or
reverse proxy) in front of it. Some frameworks provide their own reverse proxies
https://www.varnish-cache.org/
http://sleeplessinslc.blogspot.com/2009/03/example-of-caching-with-rest-using.html

REST DOCUMENTATIONS
Following tools are good for generating documentation not for contract agreement
Swagger
An open spec for describing REST APIs [ github ]
Tools for auto-generating
Documentation
Code for your API
Mashery
An open source project [ github ]
Tools for generating
Documentation
An exploration interface for your API
Apiary and API Blueprint
Write the API description in a DSL within markdown
Tools for auto-generating
Documentation
Mock server
Seems to be focused on ruby+mac devs
33

RAML
A spec for describing REST APIs [ github ]
APIgee
A commercial product with some documentation features
A commercial product with some documentation features
miredot
Commercial REST API documentation generator
Java specific
34

REFERENCES
http://cxf.apache.org/
http://en.wikipedia.org/wiki/Apache_CXF
http://stackoverflow.com/questions/2704700/java-rest-implementation-jersey-vs-cxf
http://programmers.stackexchange.com/questions/155467/selecting-a-jax-rs-implementation-for-a-new-project
http://en.wikipedia.org/wiki/Project_Jersey
https://jersey.java.net/
http://www.vogella.com/tutorials/REST/article.html
http://en.wikipedia.org/wiki/Restlet
http://nagesh625.blogspot.com/2014/01/difference-between-jax-rs-specification.html
https://github.com/fcrepo4/fcrepo4/wiki/JAX-RS-Implementation-Comparison
http://compare-tech.blogspot.com/2012/09/comparing-restful-web-services.html
http://www.aeon-consulting.fr/2010/02/28/noelios-technologies-becomes-aeon-consulting-partner/
http://resteasy.jboss.org/
https://www.openshift.com/blogs/day-13-dropwizard-the-awesome-java-rest-server-stack
http://www.jroller.com/Solomon/entry/jax_rs_vendor_comparisons_part
http://cxf.547215.n5.nabble.com/In-JAX-RS-what-do-you-think-distinguishes-CXF-from-Jersey-td5735519.html
36

Rest overview briefing

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Similar to Rest overview briefing

Similar to Rest overview briefing (20)

More from ◄ vaquar khan ► ★✔

More from ◄ vaquar khan ► ★✔ (11)

Recently uploaded

Recently uploaded (20)

Rest overview briefing