Webservices: The RESTful Approach

1. Webservices: The RESTful
Approach
Mushfekur Rahman
Associate Software Engineer
Therap BD Ltd.

2. Outline
• Intro to Webservice
• What is REST
• API Designing Good Practices
• A Simple RESTful Webservice using Spring

3. Webservice
• Software components that interact with one another via standard
protocols (i.e. HTTP)
• Applications running on webservers that exposes
1. Functionality
2. Data
• Example
• Those ‘Powered by Google’ search boxes in websites (functionality)
• Facebook Graph API (data)
• Webservices ≈ Web APIs

4. Webservice (cont.)
• The whole scene
• Web application
• APIs
• HTTP
• Clients

5. Try to visualize
Browser
CLI (wget, curl)
Web Apps
Mobile (iOS, Android)
Network Web Application
A
P
I

6. Webservice (cont.)
• Implementation Architectures
• SOAP
• Simple Object Access Protocol
• Old school
• REST
• REpresentational State Transfer
• This is how ‘cool kids’ do it nowadays!

7. REST
• What is it?
• An architectural style to implement web APIs
• Introduced in 2000 by Roy T. Fielding
• His PhD thesis (Ch. 5)
• http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

8. REST (cont.)
• What it’s not
• A framework
• A technology
• A standards specification
Yep, remember it’s just an architectural STYLE

9. REST (cont.)
• Key properties
• Statelessness
• State resides on client-end
• Improves portability, scalability
• Resource oriented
• Everything that can be named is a resource
• Every resource is mapped with an unique URL (so be careful when choosing one)
• Uniform interface
• Interface is same for any operation (GET, POST, PUT, DELETE)

10. REST (cont.)
• URL as resource locators
• HTTP methods as verbs
• GET
• POST
• PUT
• DELETE
• Media Types
• XML
• application/xml
• JSON (JavaScript Object Notation)
• application/json

11. API Designing Good Practices
• Let’s design some APIs for http://www.imdb.com/
• Our resources
• Movies 
• A possible ‘subset’ of URLs can be
/getMovie/{id}
/newMovie
/updateMovie/{id}
/deleteMovie/{id}
/getAllMovies
/updateAllMovies
/deleteAllMovies
/updateMovie/{id}/actors
/getAllMoviesReleasedInYear/{year}
/getAllMoviesActedBy/{actorName}
/getAllMoviesDirectedBy/{dirName}
/updateAllMoviesReleasedInYear/{year}
/updateAllMoviesActedBy/{actorName}
/updateAllMoviesDirectedBy/{dirName}
/deleteAllMoviesReleasedInYear/{year}
/deleteAllMoviesActedBy/{actorName}
/deleteAllMoviesDirectedBy/{dirName}
We are really on a slippery-slope!

12. API Designing Good Practices (cont.)
• Two base URLs per resource
1. One for collections
• /movies
2. Another for a specific element
• /movies/123

13. API Designing Good Practices (cont.)
• Verbs or nouns?
• Nouns are good, verbs are bad
• Singular or plural?
• Plurals are better
• Forsquare /checkins
• GroupOn /deals
• Abstract or concrete
• Concretes are more specific (/movies better than /things)

14. API Designing Good Practices (cont.)
Resource GET POST PUT DELETE
/movies get all movies create a new movie bulk update movies delete all movies
/movies/123 get the movie with
id 123
error If exists update,
otherwise error
delete it

15. API Designing Good Practices (cont.)
• What about association?
• Maintain hierarchy
• /movies/123/actors
• What about complex variations?
• Use the good old ‘?’ (URL parameters)
• /movies?releasedIn=2004&actedBy=Natalie%20Portman
• Use CamelCasing for URL parameter naming
• Should not use GET for any operation that causes state change in server
side
• No create/update/delete operation using GET

16. API Designing Good Practices (cont.)
• The world we live in is not so perfect
• There are errors (and exceptions)
• How should we act on such times?
• Handle ‘em
• Why it’s important
• Ensures robustness
• Easier for developers (API users) to understand what’s going wrong

17. API Designing Good Practices (cont.)
• How should we do it?
• HTTP Status Codes
• 200 OK
• 404 Not Found
• There are about 70 status codes so how many we should use?
• Google GData uses 10
• 200 201 304 400 401 403 404 409 410 500
• Netflix uses 9
• 200 201 304 400 401 403 404 412 500

18. API Designing Good Practices (cont.)
• What are the very basic possible situations?
• Everything went smooth (200 - OK)
• You messed up (400 - Bad Request)
• Server messed up (500 - Internal Server Error)
• Ultimately it all boils down to 3
• Start with these 3
• Don’t go over 8

19. Let’s Code!

20. Components
Serialization/Deserialization
Jackson
ExceptionHandlerController
MovieController
MovieService

21. References
• apigee web API design guide
http://apigee.com/about/resources/ebooks/web-api-design
• Spring REST tutorial
http://spring.io/understanding/REST