Diese Präsentation wurde erfolgreich gemeldet.
Wir verwenden Ihre LinkedIn Profilangaben und Informationen zu Ihren Aktivitäten, um Anzeigen zu personalisieren und Ihnen relevantere Inhalte anzuzeigen. Sie können Ihre Anzeigeneinstellungen jederzeit ändern.
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
Nächste SlideShare
Wird geladen in …5
×

Best practices for RESTful web service design

29.156 Aufrufe

Veröffentlicht am

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

Veröffentlicht in: Technologie
  • DOWNLOAD THIS BOOKS INTO AVAILABLE FORMAT (2019 Update) ......................................................................................................................... ......................................................................................................................... Download Full PDF EBOOK here { https://soo.gd/irt2 } ......................................................................................................................... Download Full EPUB Ebook here { https://soo.gd/irt2 } ......................................................................................................................... Download Full doc Ebook here { https://soo.gd/irt2 } ......................................................................................................................... Download PDF EBOOK here { https://soo.gd/irt2 } ......................................................................................................................... Download EPUB Ebook here { https://soo.gd/irt2 } ......................................................................................................................... Download doc Ebook here { https://soo.gd/irt2 } ......................................................................................................................... ......................................................................................................................... ................................................................................................................................... eBook is an electronic version of a traditional print book THIS can be read by using a personal computer or by using an eBook reader. (An eBook reader can be a software application for use on a computer such as Microsoft's free Reader application, or a book-sized computer THIS is used solely as a reading device such as Nuvomedia's Rocket eBook.) Users can purchase an eBook on diskette or CD, but the most popular method of getting an eBook is to purchase a downloadable file of the eBook (or other reading material) from a Web site (such as Barnes and Noble) to be read from the user's computer or reading device. Generally, an eBook can be downloaded in five minutes or less ......................................................................................................................... .............. Browse by Genre Available eBooks .............................................................................................................................. Art, Biography, Business, Chick Lit, Children's, Christian, Classics, Comics, Contemporary, Cookbooks, Manga, Memoir, Music, Mystery, Non Fiction, Paranormal, Philosophy, Poetry, Psychology, Religion, Romance, Science, Science Fiction, Self Help, Suspense, Spirituality, Sports, Thriller, Travel, Young Adult, Crime, Ebooks, Fantasy, Fiction, Graphic Novels, Historical Fiction, History, Horror, Humor And Comedy, ......................................................................................................................... ......................................................................................................................... .....BEST SELLER FOR EBOOK RECOMMEND............................................................. ......................................................................................................................... Blowout: Corrupted Democracy, Rogue State Russia, and the Richest, Most Destructive Industry on Earth,-- The Ride of a Lifetime: Lessons Learned from 15 Years as CEO of the Walt Disney Company,-- Call Sign Chaos: Learning to Lead,-- StrengthsFinder 2.0,-- Stillness Is the Key,-- She Said: Breaking the Sexual Harassment Story THIS Helped Ignite a Movement,-- Atomic Habits: An Easy & Proven Way to Build Good Habits & Break Bad Ones,-- Everything Is Figureoutable,-- What It Takes: Lessons in the Pursuit of Excellence,-- Rich Dad Poor Dad: What the Rich Teach Their Kids About Money THIS the Poor and Middle Class Do Not!,-- The Total Money Makeover: Classic Edition: A Proven Plan for Financial Fitness,-- Shut Up and Listen!: Hard Business Truths THIS Will Help You Succeed, ......................................................................................................................... .........................................................................................................................
       Antworten 
    Sind Sie sicher, dass Sie …  Ja  Nein
    Ihre Nachricht erscheint hier
  • DOWNLOAD THIS BOOKS INTO AVAILABLE FORMAT (2019 Update) ......................................................................................................................... ......................................................................................................................... Download Full PDF EBOOK here { https://soo.gd/irt2 } ......................................................................................................................... Download Full EPUB Ebook here { https://soo.gd/irt2 } ......................................................................................................................... Download Full doc Ebook here { https://soo.gd/irt2 } ......................................................................................................................... Download PDF EBOOK here { https://soo.gd/irt2 } ......................................................................................................................... Download EPUB Ebook here { https://soo.gd/irt2 } ......................................................................................................................... Download doc Ebook here { https://soo.gd/irt2 } ......................................................................................................................... ......................................................................................................................... ................................................................................................................................... eBook is an electronic version of a traditional print book THIS can be read by using a personal computer or by using an eBook reader. (An eBook reader can be a software application for use on a computer such as Microsoft's free Reader application, or a book-sized computer THIS is used solely as a reading device such as Nuvomedia's Rocket eBook.) Users can purchase an eBook on diskette or CD, but the most popular method of getting an eBook is to purchase a downloadable file of the eBook (or other reading material) from a Web site (such as Barnes and Noble) to be read from the user's computer or reading device. Generally, an eBook can be downloaded in five minutes or less ......................................................................................................................... .............. Browse by Genre Available eBooks .............................................................................................................................. Art, Biography, Business, Chick Lit, Children's, Christian, Classics, Comics, Contemporary, Cookbooks, Manga, Memoir, Music, Mystery, Non Fiction, Paranormal, Philosophy, Poetry, Psychology, Religion, Romance, Science, Science Fiction, Self Help, Suspense, Spirituality, Sports, Thriller, Travel, Young Adult, Crime, Ebooks, Fantasy, Fiction, Graphic Novels, Historical Fiction, History, Horror, Humor And Comedy, ......................................................................................................................... ......................................................................................................................... .....BEST SELLER FOR EBOOK RECOMMEND............................................................. ......................................................................................................................... Blowout: Corrupted Democracy, Rogue State Russia, and the Richest, Most Destructive Industry on Earth,-- The Ride of a Lifetime: Lessons Learned from 15 Years as CEO of the Walt Disney Company,-- Call Sign Chaos: Learning to Lead,-- StrengthsFinder 2.0,-- Stillness Is the Key,-- She Said: Breaking the Sexual Harassment Story THIS Helped Ignite a Movement,-- Atomic Habits: An Easy & Proven Way to Build Good Habits & Break Bad Ones,-- Everything Is Figureoutable,-- What It Takes: Lessons in the Pursuit of Excellence,-- Rich Dad Poor Dad: What the Rich Teach Their Kids About Money THIS the Poor and Middle Class Do Not!,-- The Total Money Makeover: Classic Edition: A Proven Plan for Financial Fitness,-- Shut Up and Listen!: Hard Business Truths THIS Will Help You Succeed, ......................................................................................................................... .........................................................................................................................
       Antworten 
    Sind Sie sicher, dass Sie …  Ja  Nein
    Ihre Nachricht erscheint hier
  • DOWNLOAD THAT BOOKS INTO AVAILABLE FORMAT (2019 Update) ......................................................................................................................... ......................................................................................................................... Download Full PDF EBOOK here { http://shorturl.at/mzUV6 } ......................................................................................................................... Download Full EPUB Ebook here { http://shorturl.at/mzUV6 } ......................................................................................................................... Download Full doc Ebook here { http://shorturl.at/mzUV6 } ......................................................................................................................... Download PDF EBOOK here { http://shorturl.at/mzUV6 } ......................................................................................................................... Download EPUB Ebook here { http://shorturl.at/mzUV6 } ......................................................................................................................... Download doc Ebook here { http://shorturl.at/mzUV6 } ......................................................................................................................... ......................................................................................................................... ................................................................................................................................... eBook is an electronic version of a traditional print book that can be read by using a personal computer or by using an eBook reader. (An eBook reader can be a software application for use on a computer such as Microsoft's free Reader application, or a book-sized computer that is used solely as a reading device such as Nuvomedia's Rocket eBook.) Users can purchase an eBook on diskette or CD, but the most popular method of getting an eBook is to purchase a downloadable file of the eBook (or other reading material) from a Web site (such as Barnes and Noble) to be read from the user's computer or reading device. Generally, an eBook can be downloaded in five minutes or less ......................................................................................................................... .............. Browse by Genre Available eBooks .............................................................................................................................. Art, Biography, Business, Chick Lit, Children's, Christian, Classics, Comics, Contemporary, Cookbooks, Manga, Memoir, Music, Mystery, Non Fiction, Paranormal, Philosophy, Poetry, Psychology, Religion, Romance, Science, Science Fiction, Self Help, Suspense, Spirituality, Sports, Thriller, Travel, Young Adult, Crime, Ebooks, Fantasy, Fiction, Graphic Novels, Historical Fiction, History, Horror, Humor And Comedy, ......................................................................................................................... ......................................................................................................................... .....BEST SELLER FOR EBOOK RECOMMEND............................................................. ......................................................................................................................... Blowout: Corrupted Democracy, Rogue State Russia, and the Richest, Most Destructive Industry on Earth,-- The Ride of a Lifetime: Lessons Learned from 15 Years as CEO of the Walt Disney Company,-- Call Sign Chaos: Learning to Lead,-- StrengthsFinder 2.0,-- Stillness Is the Key,-- She Said: Breaking the Sexual Harassment Story That Helped Ignite a Movement,-- Atomic Habits: An Easy & Proven Way to Build Good Habits & Break Bad Ones,-- Everything Is Figureoutable,-- What It Takes: Lessons in the Pursuit of Excellence,-- Rich Dad Poor Dad: What the Rich Teach Their Kids About Money That the Poor and Middle Class Do Not!,-- The Total Money Makeover: Classic Edition: A Proven Plan for Financial Fitness,-- Shut Up and Listen!: Hard Business Truths that Will Help You Succeed, ......................................................................................................................... .........................................................................................................................
       Antworten 
    Sind Sie sicher, dass Sie …  Ja  Nein
    Ihre Nachricht erscheint hier
  • How can we seriously speak about REST, which requires to use NOUNs to define ACTIONs (slide 9)? It seems the same mental problem as happened to thousands of developers who took Web Services as services instead of interfaces...
       Antworten 
    Sind Sie sicher, dass Sie …  Ja  Nein
    Ihre Nachricht erscheint hier

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

×