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,119 views

Published on

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

Published in: Technology

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

×