Restful Web Service

1. • Introduction of Restful Web Service
• Main steps for building a Restful Web Service
• Some frameworks use to build a Restful Web Service
Restful Web Service Agenda

2. • REST is described by a set of architectural constraints that attempt to minimize latency and
network communications while, at the same time, maximizing the independence and scalability of
component implementations.
• REST characteristic/constraints(ordered)
– Client-Server: Separation of concerns is the principle behind the client-server.
– Stateless: communication must be stateless in nature
– Caching: improve network efficiency
– Uniform interface: The uniform interface simplifies and decouples the architecture, which
enables each part to evolve independently
– Layered System: A REST-based solution can be comprised of multiple architectural layers,
and no one layer can "see past" the next
– Code On-Demand(optional):
Rest concept

3. • Restful web service built base on the REST architecture style with some
important features:
– Use HTTP protocol for communication between components.
– The web services are completely stateless.
– A caching infrastructure can be leveraged for performance.
– Bandwidth is particularly important and needs to be limited. REST is particularly
useful for limited-profile devices, such as PDAs and mobile phones.
– The service producer and service consumer have a mutual understanding of the
context and content being passed along by having a negotiation.
Restful Web Service

4. • Simplicity
– Compliant with unique interface for abstraction.
– Reduce step of service define and discovery.
– Utilize non-schema format for transferring data like Json.
• Performance
– Cacheable
– Reduce network latency and bandwidth
• Scalability
– Easy to scale with statelessness
– Support load balancing across service instances via the layered and Uniform interface
constraints.
• Reliability
– Help to avoid single points of failure
• Portability
– The ease of moving services and solutions from one deployed location to another
Benefit of Restful Web Service

5. • Define resource/service want to expose
• Determine appropriate HTTP methods
• Add authentication/encryption
• Caching appropriate data
• Applying best practices
Main steps building a Restful WS

6. • Base on business domain model
– An abstraction to represent an object associate with type, data, and relationship: a user,
document, image, services…
– Has data associate with it.
– It is a “noun” in application.
– Resource can contain sub-resource
• Has an identification
– Each resource has an unique associate to identify.
– Can use URL, URI
• Resource representation
– Is a view of resource state at particular time.
– A representation of resource is transferred between components, not resource itself.
– Can be represented by various format: JSON, XML,HTML… to interact between components
– A resource can be represented by many representation.
Restful Resource model

7. A resource model sample
http://localhost/hotel/{hotelId} -> Single Resource
http://localhost/hotel/1/room/1 -> sub-resource
http://localhost/hotel/1/Reservation/15
http://localhost/hotel/1/Room/4/Reservation/15

8. • Resource metadata
– Id: Identifies the unique ID of a resource.
– Href: Identifies the URL of the current resource.
– Link: Identifies a relationship for a resource. This attribute is itself an object and has “rel”
“href” attributes.
– This can be referred to HATEOAS
• Resource state and application state
– Resource state: value of resource at particular time and maintained at server, be persistent
and survivable, ex purchase status….
– Application state: maintain at client, the way client interact with server, like paging info,
authentication info….and can refer as session state
– Each client request encapsulating all necessary application state , server doesn’t maintains
session state for working with each client….
Resource model

9. Resource state and application state

10. • Use HTTP as a standard protocol for manipulate resource
– Used to transfer representation of resource over network
– Utilize all verbs in HTTP
– Hierarchy the URI to express hierarchy parameter
• GET to retrieve a resource
– GET http://www.example.com/hotel/12345
– Is safe and Idempotent
– Is cacheable
• DELETE to delete a resource
– DELETE http://www.example.com/hotel/12345
Operation on Resource

11. • POST to add a resource
– POST http://www.example.com/customers
– Create resources when you do not know the resource identifier.
• PUT to update a resource
– Requests you MUST send all the available properties/values, not just the ones
you want to change.
– Is Idempotent
– Can use to create new Resource.
• For other operations to represent status(not state) of resource belong to a
process: cancel…
– Encapsulate in the resource representation.
– Define another resource
Operation on resource

12. Resource operation samples
Guest cancel reservation:
DELETE /guest/1/reservation/233?cance=true
Guest transfer money for reservation:
POST /guest/1/reservation/233/acount/1/transfer/2
Register a user
POST /register/

13. Operation on resource summary

14. • Authentication
– Various approaches can be used
• Authorization
– Role of user to use service
• Other consideration
– Validation all input on server
– Validate Malformed XML/JSON
– No sensitive data in URL
Restful WS security

15. • Authentication a restful Web Service
– Stateless , so can’t rely on session to keep authentication info.
– Client need to provide all necessary info a each request.
– Base on some methods: Basic, Digest, Token base, Oauth2
• Basic authentication
– Send pair of Username/Password encode base64.
– Not secure
• Digest authentication
– Password is encrypted using MD-5
– More secure than Basic Authentication.
• Token-base authentication
• Oauth2 approach
Restful WS: Authentication

16. Token Base Authentication
• Database for validating token
• Json web token for self validation token.

17. Oauth2 authentication

18. • The API suggests its own usage
– Using common and concrete terms
– Using noun, not verb: /getAllCars -> /cars
– Do not mix up singular and plural nouns, prefer plural for all resources.
• JSON when possible, XML if have to
• SSL everywhere - all the time
• Deal with collection of resources via GET
– Appling filter via query parameter
– Sort the result
– Limiting which fields are returned by the API
• Average granularity
– Balancing between Fine grained and Coarse Grained
– Don’t mix DB CRUD and Resource CRUD.
• Use sub-resources for relations
• Updates & creation should return a resource representation
– Prevent an API consumer from having to hit the API again
Some best practices

19. • Versioning with timestamp, a release number and in the path, not header
• Leverage the HTTP status codes and error In a payload
• Allow overriding HTTP method
– Some proxies support only POST and GET methods, using custom HTTP Header X-HTTP-
Method-Override.
• Use HTTP headers for specifying serialization formats
– Content-Type defines the request format
– Accept defines a list of acceptable response formats
• Self-description the request-response.
• Stateless design.
Some other best practices

20. • Java platform
– Base on JAX-RS specification stand for Java API for RESTful Web Services
– Various compliant implementation: Jersey, RESTEasy
– Spring MVC also support building a Restful Web Service.
• .Net platform
– Using ASP.NET Web API
– WCF
• Other platforms
– Scala with Akka HTTP
– Golang with Revel
Frameworks/Tools to build a Restful WS

21. • Annotation
– @Path: is used to define a URI matching pattern for incoming HTTP requests to
a specific resource. URI value can be a regular expression, variables are
denoted by braces { and }:
@Path("/users/{username}") -> http://example.com/users/Galileo
@Path("{database}-db")
public Object getDatabase(@PathParam("database") String db) ->
http://example.com/oracle-db
– @GET: HTTP GET method is used to retrieve a representation of a resource,
and It is both an idempotent and safe operation
• GET http://www.example.com/customers/12345
• GET http://www.example.com/customers/12345/orders
– @POST: HTTP POST to *create* new resources
• POST http://www.example.com/customers
• POST http://www.example.com/customers/12345/orders
JAX-RS

22. • Annotation
– @PUT: HTTP PUT to create/update a resource, this is an idempotent
– @DELETE: HTTP DELETE use to delete a resource
– @PathParam: retrieval based on id like GET /employee/{id}
– @QueryParam: for filtering, allows to inject individual URI query
parameter
GET /customers?start=0&size=10 ->
@GET(“/customers”) @Produces("application/xml")
public String getCustomers(@QueryParam("start") int start,
@QueryParam("size") int size)
– @FormParam: used to access application/x-www-formurlencoded request
bodies.
– @DefaultValue
– @Cookie: use to retrieve the cookie value sending by client.
JAX-RS

23. • Asynchronous
– Client asynchronous call by polling using Future or callback using AsyncInvoker
interface.
– Server side asynchronous implementation
• Bean validation
– Supports the Bean Validation to verify JAX-RS resource classes.
– Using annotation: @NotNull, @Email..
• Filter and handler
– Server filter: Request Filter and Response Filter by implementing
ContainerRequestFilter, ContainerRequestFilter.
– Client filter: Request Filter and Response Filter by implementing
ClientRequestFilter, ClientResponseFilter.
JAX-RS

24. • Content negotiation
– Client/Server can specify the expected content:
• Media: GET /library Accept: application/json
• Language: GET /stuff Accept-Language: en-us, es
• Encode:
– Using annotation:
• @Consumes: specify which MIME media types of representations a resource can
accept, or consume, sending from the client.
• @Produces: specify the MIME media types of representations a resource can produce
and send back to the client: application/json, application/xml, text/html, image/jpeg,
image/png
• Client API
• HATEOAS
JAX-RS

25. Other useful tools
• Rest Client
– Google Advanced Rest Client
• Document maker
– Swagger
– RAML
• Json validation
– Json parser(http://json.parser.online.fr/)
• Monitor
– Mashape(https://www.mashape.com/)
– Kibana with Logstash

26. THANK YOU