Creating RESTful Web Services with Grails 3

@jennstrater
#Devoxx #restwithgrails3
Creating RESTful Web Services
with Grails 3
Jennifer Strater
Object Partners, Inc.

View Slide

@jennstrater
About Me
• Senior Consultant at Object Partners, Inc.
• Co-Founder of Gr8Ladies

View Slide

@jennstrater
Agenda
• Getting Started
• Resource Annotation
• RESTful Controllers
• Key Features
• Supporting Multiple Media Types
• Custom Response Formats
• Versioning

View Slide

@jennstrater
New in Grails 3
• Based on Spring Boot
• Switched to Gradle for build system
• Major structural changes
• conﬁguration
• tests
• scripts directory

View Slide

@jennstrater
Web API profile
• Introduced in Grails 3.0.5
• Removes Unnecessary Features
• no GSPs
• New Features
• Grails Command line support
• domain classes with resource annotation
• RESTful controllers
• json/gson views* (Grails 3.1+)

View Slide

@jennstrater
Getting Started
• gvm use grails 3.0.9
• grails create-app gr8data --proﬁle=web-api

View Slide

@jennstrater

View Slide

@jennstrater
• grails>run-app

View Slide

@jennstrater

View Slide

@jennstrater
The Task - Gr8Data
• Capture and display gender ratios at companies using Groovy
and related technology around the world
• Currently available at: http://jlstrater.github.io/gr8ladies-d3/
• Data stored in a json ﬁle with contributions via github pull
requests
• Demo for this talk: http://github.com/jlstrater/gr8data

View Slide

@jennstrater
Data Model
• Company
• name
• Country
• name
• abbreviation
• continent
• various stats

View Slide

@jennstrater
First Endpoint
grails> create-domain-resource gr8data.Country
| Created grails-app/domain/gr8data/Country.groovy
| Created src/test/groovy/gr8data/CountrySpec.groovy

View Slide

@jennstrater
package gr8data 
 
import grails.rest.* 
 
@Resource(readOnly = false, formats = ["json", "xml"]) 
class Country { 
 
}
Country.groovy

View Slide

@jennstrater
package gr8data 
 
 
@Resource(+ uri="/countries", readOnly = false, formats = ["json", "xml"]) 
class Country { 
+ String name 
+ String abbreviation 
+ String continent 
}

View Slide

@jennstrater
GET
• curl http://localhost:8080/countries
• []

View Slide

@jennstrater
POST (with errors)
curl -H "Content-Type: application/json" -X POST \
—data "{"name": "Belgium"}" http://localhost:8080/countries
Status: 422 Unprocessable Entity

View Slide

@jennstrater
POST (successful)
curl
-H "Content-Type: application/json"
-X POST
-d "{"name": "Belgium", "abbreviation": "BE", "continent":
"Europe"}" http://localhost:8080/countries
Status: 201 Created

View Slide

@jennstrater
PUT
curl
-X PUT
-d "{"name": "United States of America", "abbreviation": "USA",
"continent": "North America"}"
http://localhost:8080/countries

View Slide

@jennstrater
PUT
curl
-X PUT
-d "{"name": "United States of America", "abbreviation": "USA",
"continent": "North America"}"
http://localhost:8080/countries/2
status: 200 OK

View Slide

@jennstrater
PATCH
curl
-X PATCH
-d "{"abbreviation": "US"}"
http://localhost:8080/countries/2
status: 200 OK

View Slide

@jennstrater
GET
curl http://localhost:8080/countries

View Slide

@jennstrater
Resource Annotation Recap
• Automatic Mappings
• No controllers created
• URLMappings.groovy not updated
• HTTP Status Codes
• HTTP Methods

View Slide

@jennstrater
RESTful Controllers
New Domain Class
grails> create-domain-class gr8data.Company
| Created grails-app/domain/gr8data/Company.groovy
| Created src/test/groovy/gr8data/CompanySpec.groovy

View Slide

@jennstrater
package gr8data 
 
class Company { 
 
static constraints = { 
} 
} 
RESTful Controllers

View Slide

@jennstrater
package gr8data 
 
class Company {
+ String name
+ Country country 
 
static constraints = { 
} 
} 
RESTful Controllers

View Slide

@jennstrater
RESTful Controllers
grails> create-restful-controller gr8data.Company
| Created grails-app/controllers/gr8data/CompanyController.groovy
*REMEMBER* to update UrlMappings.groovy
+ "/companies"(controller: "company", action: "index", method: "GET") 
+ "/companies"(controller: "company", action: "save", method: "POST") 
+ "/companies/$id"(controller: "company", action: "update", method: "PUT") 
+ "/companies/$id"(controller: "company", action: "patch", method: "PATCH") 
+ "/companies/$id"(controller: "company", action: "delete", method: "DELETE")
…

View Slide

@jennstrater
package gr8data 
 
import grails.converters.* 
 
class CompanyController extends RestfulController { 
static responseFormats = ["json", "xml"] 
CompanyController() { 
super(Company) 
} 
} 

View Slide

@jennstrater
URI Customization
• Resource Annotation
• parameters
• i.e. @Resouce(uri="/countries", readOnly=true)
• UrlMappings.groovy
• resources
• uri
• methods
• response formats
• etc

View Slide

@jennstrater
"/$controller/$action?/$id?(.$format)?"{
constraints {
// apply constraints here
}
}
Default Mapping

View Slide

@jennstrater
URL Mappings Report
grails>url-mappings-report

View Slide

@jennstrater
HTTP Methods
• via mappings
• "/custom"(controller="custom", action=“index”, method=“GET")
• via controllers
• static allowedMethods = [save: "POST", update: "PUT"]

View Slide

@jennstrater
Default Media Types
• xml if not speciﬁed
• on mappings and controllers
• formats = ["json","xml"]
• extension
• /countries.xml
• /countries.json
• Requesting a format not included returns 406 Not Acceptable

View Slide

@jennstrater
Custom Media Types
• Add to Mime Types

View Slide

@jennstrater
Custom Response Formats
• Marshallers/Renderers
• registration
• bootstrap.groovy
• beans
• JSON views*

View Slide

@jennstrater
import grails.converters.JSON
class Bootstrap {
def init = { servletContext ->
JSON.registerObjectMarshaller(Country) {
return [
id: it.id,
name: it.name,
abbrev: it.abbreviation,
continent: it.continent
]
}
}
}
grails-app/init/Bootstrap.groovy

View Slide

@jennstrater
import grails.converters.JSON
import gr8data.CompanyJsonRenderer
beans = {
companyJsonRenderer CompanyJsonRenderer
}
conf/spring/resources.groovy

View Slide

@jennstrater
class CompanyJsonRenderer extends AbstractRenderer { 
CompanyJsonRenderer() { 
super(Company, [MimeType.JSON, MimeType.TEXT_JSON] as MimeType[]) 
} 
 
void render(Company company, RenderContext context) { 
context.contentType = MimeType.JSON.name 
 
JsonBuilder builder = new JsonBuilder(id: company.id, name: company.name,
country: company.country.name) 
builder.writeTo(context.writer) 
} 
}
Json Renderer

View Slide

@jennstrater
class CompanyCollectionJsonRenderer implements ContainerRenderer { 
Class getTargetType() { List } 
 
Class getComponentType() { Company } 
 
MimeType[] getMimeTypes() { [MimeType.JSON] as MimeType[] } 
 
void render(List companies, RenderContext context) { 
…
} 
}
Json Collection Renderer

View Slide

@jennstrater
JSON view*
• JSON views replace GSPs in web-api proﬁle
• Convention Based
• index.gsp -> index.gson
*Grails 3.1+

View Slide

@jennstrater
json {
message "Not Found"
error 404
}
JSON views*

View Slide

@jennstrater
Versioning
• URI
• http://api.example.com/v1/resource/{id}
• http://example.com/api/v1/resource/{id}
• Custom Header
•
• Content Type

View Slide

@jennstrater
Versioning in Grails
• URI
• "/hello/v1"(controller="hello", namespace: "v1")
• "/hello/v2"(controller="hello", namespace: "v2")
• Accept Header
• "/hello"(version:"1.0", controller="hello", namespace: "v1")
• "/hello"(version:"2.0",controller="hello", namespace: "v2")

View Slide

@jennstrater
Version By Namespace
package gr8data.v1
class HelloController {
static namespace = "v1"
def index() {
render "Hello, World (v1)"
}
}
package gr8data.v2
class HelloController {
static namespace = "v2"
def index() {
render "Hello, World (v2)"
}
}

View Slide

@jennstrater
Security
• Spring Security Rest Plugin by Álvaro Sánchez Mariscal
• Token based authentication
• Greach 2014 Video
• Grails 2 only
• Spring Security Plugin for Grails 3
• OAuth for Spring Boot
• Screencast by Bobby Warner of Agile Orbit

View Slide

@jennstrater
Conclusion
• Grails web-api proﬁle streamlines API creation.
• Grails defaults support HTTP status codes, HTTP methods,
custom media types, custom response formats, and versioning
fairly easily.
• More exciting changes coming to the web-api proﬁle with
Grails 3.1!

View Slide

@jennstrater
To Learn More
• Restful Web Services in Grails 3 at Gr8Conf US
• YouTube / Slides
• Restful Grails 3 at SpringOne2GX by Jeff Brown
• Grails 3.X Update at SpringOne2GX by Graeme Rocher
• Grails Documentation
• REST

View Slide

Creating RESTful Web Services with Grails 3

Creating RESTful Web Services with Grails 3

jlstrater

More Decks by jlstrater

Other Decks in Technology

Featured

Transcript