Understand what is REST and it's principles. How to build RESTful application using JAX-RS. How to expose it and test it using SWAGGER.

1. July 29, 2017
Kumaraswamy Gowda
Software Architect, PSL
Build RESTful
application
with JAX-RS

2. Agenda
2
• What is REST
• REST principles
• Java API for RESTful Web Services (JAX-RS, defined in
JSR 311)
• HTTP Methods
• Annotations
• Client APIs
• SWAGGER – Expose and Test REST API

3. HTTP Example
3
Request
GET /music/artists/beatles/recordings HTTP/1.1
Host: media.example.com
Accept: application/xml
Response
HTTP/1.1 200 OK
Date: Sat, 08 Jul 2017 16:41:58 GMT
Content-Type: application/xml(or json); charset=UTF-8
<?xml version="1.0"?>
<recordings xmlns="…">
<recording>…</recording>
…
</recordings>
Method Resource
Representation
State
transfer
{
"recordings": {
"recording": [
{},
{}
]
}
}

4. What is REST
4
• REpresentational State Transfer is an architectural style
for building online applications
• First described by Roy Fielding in his doctoral dissertation
in 2000
• Lightweight, Scalable and maintainable
• Stateless by nature
• Client server protocol, almost always HTTP
• Clients can be any programming language

5. REST architecture for Web
5
Resources
Web Container
Resources
Web Container

6. REST Principles
6
• Everything is a resource
• Assign everything an ID
• Uniform Interface- fixed set of four
create, read, update, delete operations
o PUT, GET, POST, and DELETE
• Representation of the Resource
o JSON, XML, TEXT
/reports
--------------------
GET – list all reports
PUT – not supported
POST – create a report
DELETE – not supported
/reports/{id}
--------------------
GET – get report details
PUT – update report
POST – not supported
DELETE – delete a report
{
"recordings": {
"recording": [
{},
{}
]
}
}
<?xml version="1.0"?>
<recordings xmlns="…">
<recording>…</recording>
…
</recordings>

7. REST Principles contd…
7
• Stateless
• Link
o /reports to contain links to all reports like /reports/1,
/reports/2
• Pagination
o Limit data per request
o Enables clients to navigate forward or backward
• Caching
• Fields, sorting, filtering, versioning

8. JAX-RS (2.0)
8
• Java API for RESTful Web Services (JAX-RS, defined in
JSR 311)
• Designed to make it easy to develop applications that use
the REST architecture
• Implementations
o Jersey
o Apache CXF
o Apache Wink
o Restlet
• JAX-RS uses annotations available from Java SE 5

9. Annotations
9
• @Path
o Sets path to base URL +
@Path value
o https://server:port/eclipseapp
/api/reports
o @Path(“/reports”/{id})
o @Path("/username/{usernam
e : [a-zA-Z][a-zA-Z_0-9]}")
o @Path("{id : d+}")

10. @GET, @POST, @PUT, @DELETE
10
/reports – GET POST
/reports/{reportid} – GET, DELETE, PUT
/reports/{reportid}/templates
/reports/{reportid}/templates/{templateid}

11. @Produces and @Consumes
11
• MIME type content returned
• Equivalent to Content-type response header

12. @PathParam @QueryParam @HeaderParam
@FormDataParam @FormParam
12
• Binds values from request to the parameter

13. Deployment Descriptor (web.xml)
13
<servlet>
<servlet-name>JAX-RS Servlet</servlet-name>
<servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
<init-param>
<param-name>com.sun.jersey.config.property.packages</param-name>
<param-value>com.abc.xyz.services</param-value>
</init-param>
<init-param>
<param-name>javax.ws.rs.Application</param-name>
<param-value>com.abc.xyz.service.MyApplication</param-value>
</init-param>
</servlet>
<servlet-mapping>
<servlet-name>JAX-RS Servlet</servlet-name>
<url-pattern>/api/*</url-pattern>
</servlet-mapping>

14. Client APIs
14
• Remember URLConnection? Or apache http client
libraries?
• Fluent API available from JAX-RS 2.0
Client
Builder
Client
Web
Target
Request
Building
Response..

15. SWAGGER
API developer tools for the OpenAPI Specification
15

16. What is Swagger and Why Swagger?
16
• Simple representation of your RESTFul API
• Declarative resource specification
• JSON specification
• Developers and documentation… hahaha
• Why Jersey Client / JUNIT or Rest Client (Poster /
Postman) or API document for your client or boss?
• Swagger UI to interact with the API in a sandbox UI
• Support your existing RESTFul API without change

17. Swagger Specification
17
Web Services
• Resource Listing
• API Description
Create Swagger Specification
• Manually - writing the JSON by hand
• Codgen - converts annotations in your code into swagger
specification

18. Swagger Specifications
18

19. 19

20. Swagger Tools
20
Adjacent tools also provided by the
Swagger project are
Tool Description
Swagger JS Javascript library for consuming Swagger-defined APIs from both client and node.js app
Swagger Node Swagger module for node.js
Swagger-Socket expose/invoke Swagger defined APIs over WebSockets
Swagger Parser Standalone library for parsing Swagger definitions from Java
Tools for nearly every language and
allows you to deploy server instances
to get your API up and running -
Clojure, Go, JS, Java, .Net, Node,
PHP, Python, Ruby, Scala

21. References
21
• http://docs.oracle.com/javaee/6/tutorial/doc/giepu.html
• http://www.vogella.com/tutorials/REST/article.html
• https://jersey.java.net/documentation/latest/jaxrs-
resources.html
• https://github.com/koushikkothagal/messenger
• http://swagger.io/specification/
• https://github.com/swagger-api/swagger-spec
• https://github.com/swagger-api/swagger-core
• http://petstore.swagger.io/

22. 22
Thanks!
Any questions?
You can find me at
➝https://www.linkedin.com/in/kumaraswamym/
➝kumaraswamy.m@gmail.com