Webservices: The RESTful Approach

Webservices: The RESTful Approach

• 1.
  Webservices: The RESTful Approach MushfekurRahman Associate Software Engineer Therap BD Ltd.
• 2.
  Outline • Intro toWebservice • What is REST • API Designing Good Practices • A Simple RESTful Webservice using Spring
• 3.
  Webservice • Software componentsthat 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.) • Thewhole 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.) • ImplementationArchitectures • SOAP • Simple Object Access Protocol • Old school • REST • REpresentational State Transfer • This is how ‘cool kids’ do it nowadays!
• 7.
  REST • What isit? • 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.) • Whatit’s not • A framework • A technology • A standards specification Yep, remember it’s just an architectural STYLE
• 9.
  REST (cont.) • Keyproperties • 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.) • URLas resource locators • HTTP methods as verbs • GET • POST • PUT • DELETE • Media Types • XML • application/xml • JSON (JavaScript Object Notation) • application/json
• 11.
  API Designing GoodPractices • 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 GoodPractices (cont.) • Two base URLs per resource 1. One for collections • /movies 2. Another for a specific element • /movies/123
• 13.
  API Designing GoodPractices (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 GoodPractices (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 GoodPractices (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 GoodPractices (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 GoodPractices (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 GoodPractices (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 webAPI design guide http://apigee.com/about/resources/ebooks/web-api-design • Spring REST tutorial http://spring.io/understanding/REST