Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.
Best practices
for RESTful web
service design
Ramin Orujov
Azercell Telecom LLC
#whoami
 Senior Software developer
 Internal Applications Team Head
@Azercell Telecom
 Part time teacher @Qafqaz Univer...
#agenda
 REST fundamentals
 Resource naming
 Representation
 HTTP methods
 Error handling
 Version management
 Pagi...
#rest fundamentals
REpresentational State Transfer (REST) is a
style of software architecture for distributed
systems such...
#rest constraints
 Client-server
 Stateless
 Cacheable
 Layered system
 Layered system
 Code on demand (optional)
 ...
#resource naming
Follow KISS principle
Use nouns for resource
names
Use verbs actions
#resource naming
2 base urls:
Collection (plural)
/employees
Resource
/employees/itramin
#resource naming
Use nouns for non-resource
actions:
convert
calculate
#representation
 Request header: Content-type
 application/json
 application/xml
 Extension
 /employees.json
 /emplo...
#http methods
 Create
 Read
 Update
 Delete
 POST
 GET
 PUT
 DELETE
#http methods
Resource POST
Create
GET
Read
PUT
Update
DELETE
Delete
/employees Create new
emp
Return list of
employees
Bu...
#error handling
 Error handling is very important for reliable
and stable API.
 Use appropriate HTTP status codes
 Docu...
#http status codes
Group Comment
1xx Informational(100,101)
2xx Success(200,201)
3xx Redirect (301, 304)
4xx Client error(...
#error messages
Consider the following:
 For user
 For developer
 Unique error code
 Link to documentation
#error messages
{
userMessage:”Show this error to user”,
devMessage:”Detailed error for developer”,
“errorCode”: 12345,
“d...
#version management
 Consider versioning during design, no
later
 Consider support for multiple client
 3 general pract...
#version management
 Part of url
 api.azercell.com/azimus/v1/employees
 api.azercell.com/azimus/20130501/employ
ees
 R...
#paging
 It is bad idea to return all resources in
database, so use paging
 Query parameter
 Request/response headers
#paging
Query parameter:
 Facebook - limit, offset
 Twitter – page, rpp(records per page)
 LinkedIn – start, count
 Co...
#paging
 Request header
Range: items=0-19
 Response header
Content-Range: items 0-19/152
Content-Range: items 0-19/*
#search&filter&sort
 Search
 /employees?q=ramin – (default json)
 /employees.xml?q=ramin
 Filter
 /employees?filter=“...
#partial response
Facebook:
/employees/?fields=name,surname,title
LinkedIn:
http://api.linkedin.com/v1/people/~/connectio
...
#partial response
Request a feed of a user's uploaded videos
that only contains the title, number of
comments (and comment...
#partial response
@GET
@Path("/{userId}")
@Produces("application/json")
public String getUser(@PathParam("userId")
Long
us...
#security
 Authentication
 HTTP Basic authentication + SSL
 API token,key
 Custom authentication mechanism
 Authoriza...
#security
 HTTP Basic authentication + SSL
GET /employees/ HTTP/1.1
Host: www.example.org
Authorization: Basic
cGhvdG9hcH...
#cache&scalability
 Carefully implement caching
HTTP/1.1 200 OK
Date: Sat, 06 Jul 2013 09:56:14 GMT
Last-Modified: Sat, 0...
#best rest
Sample application implementing best
practices for RESTful web service.
https://github.com/raminorujov/best-res...
#references
 https://en.wikipedia.org/wiki/List_of_HTTP_hea
der_fields
 http://www.slideshare.net/apigee/restful-api-
de...
#references
 Web API Design, Brian Mulloy, Apigee
 RESTful Java with JAX-RS, Bilk
Burke, O’Reilly, 2010
 REST API Desig...
#contacts
 https://www.twitter.com/raminorujov
 https://www.linkedin.com/in/raminorujov
 https://www.facebook.com/ramin...
Best practices for RESTful web service design
Best practices for RESTful web service design
Upcoming SlideShare
Loading in …5
×

Best practices for RESTful web service design

29,485 views

Published on

This is my presentation from Caucasus Web Conference.
caucasuswebcon.com/speakers.html

Published in: Technology
  • Check the source ⇒ www.WritePaper.info ⇐ This site is really helped me out gave me relief from headaches. Good luck!
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
  • Überprüfen Sie die Quelle ⇒ www.WritersHilfe.com ⇐ . Diese Seite hat mir geholfen, eine Diplomarbeit zu schreiben.
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
  • Yes you are right. There are many essay writing services available now. But almost services are fake and illegal. Only a genuine service will treat their customer with quality essay papers. HelpWriting.net
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
  • Both the exercises and the games are very practical so dog owners may use them throughout the day to have a well-trained dog. There are training nuggets throughout, both in the step-by-step instructions and the Troubleshooting sections that will help enrich the lives of both dogs and their owners! ➤➤ https://bit.ly/38b79Wm
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
  • Update on Ace - I have gotten him involved in playing some of the games and I can see a difference in his confidence already! My other dog played along and he became intrigued - now its a daily part of our routine - about 3 times a day we do the shell game and the muffin tin game. I am so grateful for coming upon your training techniques! ★★★ https://bit.ly/38b79Wm
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here

Best practices for RESTful web service design

  1. 1. Best practices for RESTful web service design Ramin Orujov Azercell Telecom LLC
  2. 2. #whoami  Senior Software developer  Internal Applications Team Head @Azercell Telecom  Part time teacher @Qafqaz University (Java OOP, Java web, Android)  AZERJUG founder and manager  Trainer, mentor, speaker, consultant, etc…
  3. 3. #agenda  REST fundamentals  Resource naming  Representation  HTTP methods  Error handling  Version management  Paging  Search and filtering  Security
  4. 4. #rest fundamentals REpresentational State Transfer (REST) is a style of software architecture for distributed systems such as the WWW. It was introduced and defined in 2000 by Roy Fielding in his doctoral dissertation. Source: http://en.wikipedia.org/wiki/REST
  5. 5. #rest constraints  Client-server  Stateless  Cacheable  Layered system  Layered system  Code on demand (optional)  Uniform interface
  6. 6. #resource naming Follow KISS principle Use nouns for resource names Use verbs actions
  7. 7. #resource naming 2 base urls: Collection (plural) /employees Resource /employees/itramin
  8. 8. #resource naming Use nouns for non-resource actions: convert calculate
  9. 9. #representation  Request header: Content-type  application/json  application/xml  Extension  /employees.json  /employees.xml  /employees/itramin.json  /employees/itramin.xml  Query param  /employees/type=json  /employees/type=xml
  10. 10. #http methods  Create  Read  Update  Delete  POST  GET  PUT  DELETE
  11. 11. #http methods Resource POST Create GET Read PUT Update DELETE Delete /employees Create new emp Return list of employees Bulk update or Error Delete all employees Error /employees/ itramin Not used Error Return employee itramin Update employee itramin Delete emp itramin
  12. 12. #error handling  Error handling is very important for reliable and stable API.  Use appropriate HTTP status codes  Document success and error cases
  13. 13. #http status codes Group Comment 1xx Informational(100,101) 2xx Success(200,201) 3xx Redirect (301, 304) 4xx Client error(401, 404, 405) 5xx Server error(500, 503) http://en.wikipedia.org/wiki/List_of_HTTP_status_codes
  14. 14. #error messages Consider the following:  For user  For developer  Unique error code  Link to documentation
  15. 15. #error messages { userMessage:”Show this error to user”, devMessage:”Detailed error for developer”, “errorCode”: 12345, “doc”:”http://api.azercell.com/azimus/doc s/errors/12345” }
  16. 16. #version management  Consider versioning during design, no later  Consider support for multiple client  3 general practice:  Part of url  Request param  Request header
  17. 17. #version management  Part of url  api.azercell.com/azimus/v1/employees  api.azercell.com/azimus/20130501/employ ees  Request header  Content-Type: application/json;v=1  Query param – overrides header  ?v=1
  18. 18. #paging  It is bad idea to return all resources in database, so use paging  Query parameter  Request/response headers
  19. 19. #paging Query parameter:  Facebook - limit, offset  Twitter – page, rpp(records per page)  LinkedIn – start, count  Consider reasonable default values such as limit=20, offset=0
  20. 20. #paging  Request header Range: items=0-19  Response header Content-Range: items 0-19/152 Content-Range: items 0-19/*
  21. 21. #search&filter&sort  Search  /employees?q=ramin – (default json)  /employees.xml?q=ramin  Filter  /employees?filter=“name::ramin|department=ICT”  /employees?name=ramin&department=ICT  Sort /employees?sort=name|surname /employees?sort=-salary|name
  22. 22. #partial response Facebook: /employees/?fields=name,surname,title LinkedIn: http://api.linkedin.com/v1/people/~/connectio ns:(id,first-name,last-name,positions:(title)) https://developer.linkedin.com/documents/fiel d-selectors
  23. 23. #partial response Request a feed of a user's uploaded videos that only contains the title, number of comments (and comment URL), and viewing statistics for each video: https://gdata.youtube.com/feeds/api/users /default/uploads? fields=entry(title,gd:comments,yt:statistics)
  24. 24. #partial response @GET @Path("/{userId}") @Produces("application/json") public String getUser(@PathParam("userId") Long userId, @DefaultValue("userId,fullname,t itle") @QueryParam("fields") String fields) { http://stackoverflow.com/questions/9314735/ho w-to-return-a-partial-json-response-using-java
  25. 25. #security  Authentication  HTTP Basic authentication + SSL  API token,key  Custom authentication mechanism  Authorization  Oauth 1.0  Oauth 2.0  Custom mechanism  Amazon AWS Identity and Access Management  PayPal Permissions Service  Your own homegrown api
  26. 26. #security  HTTP Basic authentication + SSL GET /employees/ HTTP/1.1 Host: www.example.org Authorization: Basic cGhvdG9hcHAuMDAxOmJhc2ljYXV0aA==
  27. 27. #cache&scalability  Carefully implement caching HTTP/1.1 200 OK Date: Sat, 06 Jul 2013 09:56:14 GMT Last-Modified: Sat, 06 Jul 2013 09:56:14 GMT Expires: Sun, 06 Jul 2013 10:56:14 GMT Cache-Control: max-age=3600,must-revalidate Content-Type: application/xml; charset=UTF-8
  28. 28. #best rest Sample application implementing best practices for RESTful web service. https://github.com/raminorujov/best-rest/
  29. 29. #references  https://en.wikipedia.org/wiki/List_of_HTTP_hea der_fields  http://www.slideshare.net/apigee/restful-api- design-second-edition  http://googlecode.blogspot.com/2010/03/m aking-apis-faster-introducing-partial.html  https://blog.apigee.com/detail/restful_api_de sign_can_your_api_give_developers_just_the_i nformation  http://aws.amazon.com/documentation/iam /
  30. 30. #references  Web API Design, Brian Mulloy, Apigee  RESTful Java with JAX-RS, Bilk Burke, O’Reilly, 2010  REST API Design Rulebook, Mark Masse, O’Reilly, 2012  RESful Web Services Cookbook, Subhu Allamaraju, O’Reilly, Yahoo Press, 2010  REST in Practice, Hypermedia and Systems Architecture, Jim Webber, Savas Parastatidis, Ian Robinson, O’Reilly, 2010
  31. 31. #contacts  https://www.twitter.com/raminorujov  https://www.linkedin.com/in/raminorujov  https://www.facebook.com/ramin.orucov  http://raminorucov.wordpress.com

×