Location via proxy:   [ UP ]  
[Report a bug]   [Manage cookies]                
SlideShare a Scribd company logo

Restful webservice

•Download as PPTX, PDF•
•
Dong Ngoc
Dong Ngoc

The document discusses building Restful web services including: - Main steps like defining resources, HTTP methods, authentication, and best practices - Frameworks for building Restful services like JAX-RS which uses annotations like @Path and @GET - Additional tools that can help like Swagger for documentation and JSON parsers for validation

1 of 26
• 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
• 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
• 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
• 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
• 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
• 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
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
• 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
Resource state and application state
• 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
• 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
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/
Operation on resource summary
• 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
• 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
Token Base Authentication • Database for validating token • Json web token for self validation token.
Oauth2 authentication
• 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
• 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
• 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
• 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
• 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
• 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
• 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
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
THANK YOU

More Related Content

Restful webservice

  • 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/
  • 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.
  • 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