Grails 3でWeb APIを簡単に作ろう!

G* Workshop G*なWeb API での資料です
https://jggug.doorkeeper.jp/events/22473

1. Grails 3でWeb APIを簡単に作ろう! 2015/4/17 #jggug
2. 山本 和樹 yamkazu
3. 祝 Grails 3 リリース
4. Grails 3 ✓ Gradleでビルドシステムを一新 ✓ Spring Boot上でアプリケーショ ンを再構築
5. 今日はWeb API
6. GrailsにおけるWeb API ✓ Grails 2.3からREST関係のサポートが強化 ✓ @Resouce ✓ RestfulController ✓ Renderers
7. @Resource
8. @Resource ✓ Domainクラスにアノテーションを指定 ✓ REST対応コントローラの生成 ✓ URLマッピングへの設定の追加
9. import grails.rest.Resource
 
 @Resource(uri = '/books')
 class Book {
 String title
 }
10. Endpoints HTTP Method URI Controller Action GET /books index POST /books save GET /books/${id} show PUT /books/${id} update DELETE /books/${id} delete
11. データフォーマットの指定 ✓ クエリパラメータを使う ✓ 拡張子を使う ✓ メディアタイプを使う
12. クエリパラメータを使う http://api.example.com/books?format=json
13. 拡張子を使う http://api.example.com/books.json
14. メディアタイプを使う GET /books Host: api.example.com Accept: application/json
15. DEMO: 1
16. 各社サポートのデータフォーマット Twitter JSON Github JSON Flickr JSON, XML Amazon XML 出典: Web API: The Good Parts
17. XMLとJSONのトレンド http://www.google.com/trends/explore?q=xml+api#q=xml%20api%2C%20json%20api&cmpt=q XML JSON
18. LSUDsとSSKDs ✓ LSUDs(large set of unknown developers) ✓ 未知のたくさんの開発者 ✓ FacebookやTwitterをはじめ、パブリックにAPIをドキュメントともに 公開し、誰でもが登録して使えるようにしたもの ✓ SSKDs(small set of known developers) ✓ 既知の小数の開発者 ✓ 一方でSSKDsをターゲットとしたAPIとは、たとえば自社サービスのス マートフォンクライアント向けのAPIなど、APIを利用する開発者が限 られている http://thenextweb.com/dd/2013/12/17/future-api-design-orchestration-layer/ http://techblog.netflix.com/2014/03/the-netflix-dynamic-scripting-platform.html http://techblog.netflix.com/2012/07/embracing-differences-inside-netflix.html
19. RestfulController
20. RestfulController ✓ Domainクラスを指定するだけで 簡単にRESTfulなコントローラ を作成できる
21. import grails.rest.RestfulController
 
 class BookController extends RestfulController<Book> {
 
 static responseFormats = ['json', 'xml']
 
 BookController() {
 super(Book)
 }
 }
22. class UrlMappings {
 
 static mappings = { …
 '/books'(resources: 'book')
 }
 }
23. DEMO: 2
24. $ grails url-mapping-report
25. レンダリングの カスタマイズ
26. レンダリングの流れ Controller Renderer Converter Marshaller render as JSON/XML marshalObject render respond
27. レンダリングするプロ パティを指定する
28. import grails.rest.render.json.JsonRenderer
 
 beans = {
 bookRenderer(JsonRenderer, Book) {
 includes = ['title']
 }
 }
29. DEMO: 3
30. レスポンスレンダリン グを細かく制御する
31. import grails.converters.JSON
 
 class BootStrap {
 
 def init = { servletContext ->
 JSON.registerObjectMarshaller Book, { Book book, JSON converter ->
 converter.build {
 id book.id
 title book.title
 }
 // MapでもOK
 //[id: book.id, title: book.title]
 }
 } …
 }
32. DEMO: 4
33. ユーザがプロパティを指定可能にする http://api.example.com/books?fields=title
34. class BookController extends RestfulController<Book> {
 … @Override
 def show() {
 respond queryForResource(params.id), includes: includeFields
 }
 
 private List<String> getIncludeFields() {
 params.fields?.split(',') as List<String> ?: Collections.emptyList()
 }
 }
35. 注意 CustomMarshallerを登録している場合は 自分でincludesを制御しなければならない
36. DEMO: 5
37. レスポンスグループを定義する http://api.example.com/books?detail=short http://api.example.com/books?detail=full { "id": 1, "title": "My Book" } { "id": 1, "title": "My Book", "isbn": "…", …}
38. class BootStrap {
 
 def init = { servletContext ->
 JSON.createNamedConfig('short') {
 it.registerObjectMarshaller Book, { Book book, JSON converter ->
 [id: book.id, title: book.title]
 }
 }
 JSON.createNamedConfig('full') {
 it.registerObjectMarshaller Book, { Book book, JSON converter ->
 [id: book.id, title: book.title, isbn: book.isbn]
 }
 }
 …
 } …
 }
39. import grails.rest.render.RenderContext
 import org.grails.plugins.web.rest.render.json.DefaultJsonRenderer
 
 class MyJsonRenderer<T> extends DefaultJsonRenderer<T> {
 
 MyJsonRenderer(Class<T> targetType) {
 super(targetType)
 }
 
 @Override
 protected void renderJson(T object, RenderContext context) {
 def namedConfiguration = context.arguments.detail ?: 'short'
 
 JSON.use(namedConfiguration) {
 renderJson(object as JSON, context)
 }
 }
 }
40. DEMO: 6
41. エンベロープを使いたい { books: [ { "id": 1, "title": "Groovy"}, { "id": 2, "title": "Grails"} ] }
42. import grails.converters.JSON
 class MyJSON extends JSON {
 
 String key
 
 @Override
 void render(Writer out) throws ConverterException {
 …
 if (key) {
 writer.object()
 writer.key(key)
 value(target)
 writer.endObject()
 } else {
 value(target)
 }
 …
 } …
 }
43. class MyJsonRenderer<T> extends DefaultJsonRenderer<T> {
 
 String key
 
 @Override
 protected void renderJson(T object, RenderContext context) {
 …
 JSON.use(namedConfiguration) {
 def converter = object as MyJSON
 converter.key = key
 converter.prettyPrint = context.arguments.pretty
 renderJson(converter, context)
 }
 } …
 }
44. DEMO: 7
45. ページネーションしたい { "books": [ { "id": 1, "title": "Groovy"}, { "id": 2, "title": "Grails"} ], "paging": { "total-count": 2, "current-max": 10, "current-offset": 0 } } http://api.example.com/books? max=10&offset=0&order=desc&sort=title
46. class MyJSON extends JSON {
 
 Map paging
 
 @Override
 void render(Writer out) throws ConverterException { …
 if (paging) {
 writer.key('paging')
 value(paging)
 } …
 } …
 }
47. DEMO: 8
48. Versioning
49. バージョンの指定 ✓ URLに埋め込む ✓ Accept-Versionヘッダを使う ✓ メディアタイプを使う
50. URLに埋め込む http://api.example.com/v1/books
51. Accept-Versionヘッダを使う GET /books Host: api.example.com Accept-Version: v1
52. メディアタイプを使う GET /books Host: api.example.com Accept: application/vnd.example.v1+json
53. // sample/v1/BookController.groovy package sample.v1
 
 class BookController extends RestfulController<Book> {
 
 static String namespace = 'v1'
 …
 }
 // sample/v2/BookController.groovy package sample.v2
 
 class BookController extends RestfulController<Book> {
 
 static String namespace = 'v2'
 …
 }
54. class UrlMappings {
 
 static mappings = {
 '/v1/books'(resources: 'book', namespace: 'v1')
 '/v2/books'(resources: 'book', namespace: 'v2') …
 }
 }
55. DEMO: 9
56. Testing!
57. テスト ✓ Integrationテストを使うとサーバ立ち上 がってテストできる ✓ 適当なHTTPのクライアント使ってテスト ✓ TestRestTemplateがオススメ
58. def "GET /books/{id}"() {
 when:
 def entry = template.getForEntity("${baseUrl}/v2/books/${book.id}", Map)
 
 then:
 entry.statusCode == HttpStatus.OK
 entry.body.title == 'test book'
 entry.body.isbn == '1234'
 }
59. DEMO: 10
60. まとめ ✓ @Resouce,RestfulController,Render erのカスタマイズで簡単に柔軟に Web APIが作れる ✓ フルスタックなのでDBの連携も簡単
61. 参考書籍 http://www.amazon.co.jp/dp/4873116864 http://www.amazon.co.jp/dp/4774166278
62. 参考URL ✓ Best Practices for Designing a Pragmatic RESTful API ✓ http://www.vinaysahni.com/best-practices- for-a-pragmatic-restful-api ✓ GrailsGoodness ✓ http://mrhaki.blogspot.com/search/label/ GrailsGoodness%3AREST
63. おまけ
64. web-micro
65. Enjoy Grails 3!