CSE3510 TOPIC 5
SOFTWARE RESTful WEB
SERVICES
ARCHITECTURE
© Michael Arnwine: Service Oriented Architecture (SOA) and “Restful”
Service.
© Bill Burke: REST and JAX-RS
WHAT IS
REST?
• REpresentational State Transfer
▫ PhD by Roy Fielding
▫ The Web is the most successful application on the Internet
▫ What makes the Web so successful?
• Addressable Resources
▫ Every “thing” should have an ID
▫ Every “thing” should have a URI
• Constrained interface
▫ Use the standard methods of the protocol
▫ HTTP: GET, POST, PUT, DELETE
• Resources with multiple representations
▫ Different applications need different formats
▫ Different platforms need different representations (XML +
JSON)
• Communicate statelessly
▫ Stateless application scale
• Every “thing” has a URI (Universal Resource Identifier)
Addressability
http://sales.com/customers/323421
http://sales.com/customers/32341/address
• A URI describes
▫ The protocol (How do we communicate)
▫ The host/port (Where it is on network)
▫The resource path (What resource are we
communicating with)
DESCRIBING
A URI
http://sales.com/customers/323421
/customers/{customer-id}
• Human readable URIs: Desired but not required
• URI Parameters
http://sales.com/customers?zip=49009
• Query parameters to find other resources
http://sales.com/cars/mercedes/amg/e55;color=black
• Matrix parameters to define resource attributes
IMPLICATIONS OF A
UNIFORM INTERFACE
• Intuitive
▫ You know what operations the resource will
support
• Predictable behavior
▫ GET - readonly and idempotent. Never changes
the state of the resource
▫ PUT - an idempotent insert or update of a
resource.
Idempotent because it is repeatable without side
effects.
▫ DELETE - resource removal and idempotent.
▫ POST - non-idempotent, “anything goes”
operation
• Clients, developers, admins, operations know
what to expect
▫ Much easier for admins to assign security
roles
▫ For idempotent messages, clients don’t have to
RES
T
"Representational State Transfer is intended
to evoke an image of how a well-designed
Web application behaves: a network of web
pages (a virtual state- machine), where the
user progresses through an application by
selecting links (state transitions), resulting
in the next page (representing the next
state of the application) being transferred to
the user and rendered for their use.“
WHY REST?
• Less overhead (no SOAP envelope to wrap every call in)
• Less duplication (HTTP already represents operations like DELETE,
PUT, GET, etc. that have to otherwise be represented in a SOAP
envelope).
• More standardized (HTTP operations are well understood and
operate consistently.)
• More human readable and testable (harder to test SOAP with just a
browser).
• Don't need to use XML
• Libraries have made SOAP (kind of) easy. But you are abstracting
away a lot of redundancy underneath.
REST DATA ELEMENTS
• Resources and Resource Identifiers
• Uniform Interface (GET, PUT, POST, DELETE)
• Resource Oriented
• Simple
HTTP Method CRUD Desc.
POST CREATE Create -
GET RETRIEVE Retrieve Safe,Idempotent,Cacheable
PUT UPDATE Update Idempotent
DELETE DELETE Delete Idempotent
REST CORE
IDIOLOGIES
• Simple is better
• The web works and works well
• Some web services should follow the
“way of the web”.
RESTFUL
SERVICES
• Resources as URI
▫Use unique URI to reference every resource
on your API
• Operations as HTTP Methods
GET – Queries
POST – Queries
PUT – Insert, Update
DELETE - Delete
• Connectedness and Discoverability
▫Like the Web, HTTP Responses contains
links to other resources
SOAP VS
REST
??
Source: https://www.javatpoint.com/soap-vs-rest-web-services
11
REST API EXAMPLE: Delicious
http://del.icio.us/api/[username]/
URL
book marks/
Method GET
tag= Filter by tag
dt= Filter by date
The number of the
start= first bookmark to
Querystring
return
The number of the last
end= bookmark to return
200 OK & XML
(delicious/bookmarks+xml)
Returns
401 Unauthorized
404 Not Found
REST API EXAMPLE: Delicious
http://del.icio.us/api/
URL
[username]/bookmarks/
Method POST
XML
Request Body
(delicious/
bookmark+xml)
201 Created & Location
401 Unauthorized
Returns
415 Unsupported
Media Type
REST API EXAMPLE: Delicious
http://del.icio.us/api/
URL
[usern
ame]/bookmarks/[hash]
Method DELETE
204 No Content
Returns 401 Unauthorized
404 Not Found
DESIGNING SERVICES WITH A
UNIFORM INTERFACE
When in doubt, define a new
resource
• /orders
▫ GET - list all orders
▫ POST - submit a new order
• /orders/{order-id}
▫ GET - get an order
representation
▫ PUT - update an order
▫ DELETE - cancel an order
• /orders/average-sale
▫ GET - calculate average sale
• /customers
▫ GET - list all customers
▫ POST - create a new customer
• /customers/{cust-id}
▫ GET - get a customer
representation
▫ DELETE- remove a customer
• /customers/{cust-id}/orders
▫ GET - get the orders of a
RESOURCES WITH MULTIPLE
REPRESENTATIONS
• HTTP Headers manage this negotiation
▫ CONTENT-TYPE: specifies MIME type of
message body
▫ ACCEPT: comma delimited list of one or more
MIME types the client would like to receive
as a response
▫ In the following example, the client is
requesting a customer representation in
either xml or json format
GET /customers/33323
ACCEPT: application/xml,application/json
• Preferences are supported and defined
by HTTP specification
GET /customers/33323
WHAT IS
JSON?
• JavaScript Object Notation
• Lightweight syntax for representing
data
• Easier to “parse” for JavaScript client
code
• Alternative to XML in AJAX applications
[{"Email":"[email protected]","Name":"Bob"},
{"Email
":"[email protected]","Name":"Mark"},
{"Email":"j [email protected]
","Name":"John"}]
EXAMPLE
S:
Publish and Consume REST
Services
EXAMPLES of REST
APIs:
Facebook Graph API
Google Custom Search
API Yahoo
… and a lot more …
N-TIERS
ARCHITECTURE
• SOAP and REST based web-services
enable the 3-tier architecture to be
extended into n-tiers.
•
JAX-
RS
• JCP Specification
▫ Lead by Sun, Marc Hadley
▫ Currently in public draft (which means final
draft right around the corner)
• Annotation Framework
• Dispatch URI’s to specific classes and
methods that can handle requests
• Allows you to map HTTP requests to
method invocations
• IMO, a beautiful example of the power of
parameter annotations
• Nice URI manipulation functionality
JAX-RS
ANNOTATIONS
• @Path
▫ Defines URI mappings and templates
• @ProduceMime, @ConsumeMime
▫What MIME types does the resource
produce and consume
• @GET, @POST, @DELETE, @PUT,
@HEADER
▫Identifies which HTTP method the Java
method is interested in
JAX-RS PARAMETER
ANNOTATIONS
•@PathParam
▫ Allows you to extract URI parameters/named URI template
segments
• @QueryParam
▫ Access to specific parameter URI query string
• @HeaderParam
▫ Access to a specific HTTP Header
• @CookieParam
▫ Access to a specific cookie value
• @MatrixParam
▫ Access to a specific matrix parameter
• Above annotations can automatically map HTTP request
values to
▫ String and primitive types
▫ Class types that have a constructor that takes a String
parameter
▫ Class types that have a static valueOf(String val) method
▫ List or Arrays of above types when there are multiple
values
• @Context
▫ Access to contextual information like the incoming URI
JAX-RS RESOURCE
CLASSES
• JAX-RS annotations are used on POJO
classes
• The default component lifecycle is per-
request
▫ Same idea as @Stateless EJBs
• Root resources identified via @Path
annotation on class
JAX-
RS
@Path(“/orders”)
public class OrderService {
@Path(“/{order-
id}”) @GET
@ProduceMime(“appli
cation/xml”)
String
getOrder(@PathParam
(“order-id”) int
id) {
…
}
}
DEFAULT RESPONSE
CODES
• GET and PUT
▫ 200 (OK)
• DELETE and POST
▫ 200 (OK) if content sent back with
response
▫ 204 (NO CONTENT) if no content
sent back
RESPONSE
OBJECT
•
JAX-RS has a Response and
ResponseBuilder class
▫ Customize response code
▫ Specify specific response headers
▫ Specify redirect URLs
▫ Work with variants
@GET
Response getOrder() {
ResponseBuilder builder =
Response.status(200);
builder.type(“text/xml”)
.header(“custom-header”,
“33333”); return builder.build();
}
RESTFUL SERVICE
EXAMPLE:
JAVA.NET.URL RESTFUL
CLIENT:
APACHE
HTTPCLIENT:
JERSEY CLIENT (JERSEY-
CLIENT.JAR):
