Session Notes – RESTful Grails

Posted on by Matt Woodward

Presenter: Scott Davis
Author:

  • Groovy Recipes
  • GIS for Web Developers (all open source, REST based)
  • Groovy/Grails articles on IBM developerworks
    • Google “Mastering Grails” or “Practically Groovy”
  • Getting Started With Grails, 2d edition — free PDF on InfoQ available soon

RESTful Web Services in Grails

  • ebay
    • obviously have the web site, but have RESTful services as well
    • how much revenue comes in via web services?
      • 70%
      • only 30% comes through web site itself
      • big point here–allowing people to write third-party apps that interface with your “web site” will open up access/revenue
  • twitter
    • twitter.com only accounts for about 15% of traffic
    • 85% of traffic coming through APIs
  • programmableweb.com
    • list of APIs for major web properties
    • important to allow people to access the model without dealing with the view
    • more and more, SOAP-based APIs are going away
  • It’s all about the data
    • don’t bound up the data in a proprietary silo
    • view/web site is really just an implementation detail
  • web services
    • knee-jerk reaction is still to think about SOAP
    • SOAP is one implementation of web services
      • wasn’t even the first–had XML-RPC
      • many successors (RSS, ATOM, REST, etc.)
      • technologies have a lifecycle and SOAP is on the decline–been around for 10 years
    • Dave Winer, creator of SOAP, said in an interview on ITConversations that SOAP is a failure
      • “how long are we supposed to wait for the magic of soap to happen?”
      • “With SOAP we tried really hard to create a level playing field for small developers and large developers”
      • wanted SOAP to fade into the woodwork and just be how things are done, but never happened
    • amazon.com has both SOAP and REST
      • REST accounts for 85% of the web service calls
      • democracy in action–developers can choose either and they choose REST
    • simpler technologies win over time–XML over HTTP much simpler than SOAP
    • 12/06 — google officially deprecated their SOAP API
  • the ui is important, but don’t ignore the value of the raw data
  • question: with REST how do you handle authentication?
    • it’s all HTTP with REST so you handle it the same way you would with any other HTTP resource
    • SOAP was supposed to be protocol agnostic, but everyone uses HTTP so this is kind of pointless
      • only real example is using SOAP over JMS since it’s asynchronous, also guarantees delivery
      • but here again, if the web service will never be used on anything OTHER than JMS, why use SOAP instead of straight JMS?
  • REST is …
    • REpresentational State Transfer
    • SOAP used to be “Simple Object Access Protocol”
      • acronym has been deprecated–“no longer simple”
    • Roy Fielding coined REST term in doctoral dissertation (2000)
    • SOAP is a specification
      • one implementation of a service-oriented architecture
      • RPC, verb-oriented
      • not really dealing with objects but actions taken on data
    • REST is a set of architectural principles
      • resource-oriented, noun-oriented — object oriented
      • payload could be in XML, JSON, etc.–format of payload doesn’t matter
    • wikipedia has a great comparison between SOAP and REST
    • HTTP already has the right verbs available for CRUD
      • get, post, put, delete
      • REST is the SQL of the internet
      • URIs are unique identifiers for resources on the web
  • GETful Grails
    • lots of REST APIs only support get
    • important thing is to make sure you only expose idempotent requests via get
      • idempotent — repeat calls can’t change state of data on server
    • get requests get cached, bookmarked, etc.
      • e.g. using google maps–can pick a point on the map, set zoom level, etc. and email a link that contains the exact state of the map as a get request
    • can render objects as XML or JSON easily
      • render Airport.list() as XML
      • render Airport.list() as JSON
      • can also easily customize XML with Groovy Markup Builder
  • Content negotiation and the HTTP header
    • MIME types used to uniquely identify data types in internet calls
    • curl very handy tool for working with REST APIs
    • if you grab xml and output to a file, can use tidy to cleanup/indent the xml
    • accept header by default is */*
      • if want to get back resources in different formats, URI stays the same, but the return type could be text, html, xml, mp3, whatever
    • in conf/Config.groovy file can specify whether or not to pay attention to accept header passed by client
      • can also specify mime types
      • rather common to specify format type in URI (e.g. twitter.com/search.atom returns atom)
      • withFormat block used in controller to correspond to data types specified as action.format in url
        • e.g. list.xml would return whatever is specified in the withFormat/xml block in the controller
  • RESTful Grails
    • URI remains the same for resources
    • in Grails, can map closures to various HTTP verbs as actions
      • e.g. action = [POST:’create’, GET:’retrieve’, PUT:’update’, DELETE:’delete’]
      • this is still an XML-RPC approach since we’re still customizing things and saying “they’re asking for this, but this is what they really want”
    • can also hijack the index method and switch based on the request type
      • switch (request.method) and then have cases for each request type
    • can specify the allowed methods by action
      • static allowedMethods = [delete:’POST’, save:’POST’]
    • goal is to keep uri identical but vary the verb
    • can post XML and still use params as long as the xml node names match the domain class property names
    • good practice to get into is to always include the response.status code in the response
      • 200 for succesful get, 201 for successful create, etc.
      • also common to send back a representation of the created resource in 201 responses
    • if you have to post custom XML, have to go line-by-line and map nodes and attributes from XML to the domain class properties
      • e.g. airport.iata = request.XML.@iata
    • check out Castor — like Hibernate for XML
      • can set up mapping files to map between XML and POGOs
  • Summary
    • ui is important, but it’s the raw data that’s important
    • owe it to our constituency not to wrap data in a proprietary UI
      • future-proofs the application
    • nothing wrong with SOA and SOAP, but make sure this is what you really need
      • SOAP is on its way out–downside of adoption curve
      • REST is the way things are done today

Leave a Reply

Your email address will not be published. Required fields are marked *