Grails RESTful APIの設定方法についてまとめてみた

Grails REST API

GrailsでRESTful APIを使用するためにコントローラー使ったり、ドメインに@Resourceアノテーションつけたりいろいろ設定方法があって混乱してたのでまとめました。

はじめに

RESTful APIを使用するために設定すべきことは以下の1つだけです。

  • 公開するurlとそれに対応するコントローラーを指定

公開するurlとそれに対応するコントローラーを指定するには

grails-app/conf/UrlMappings.groovy で指定します。

以下の3行目で指定しています。resourcesの'todo'がTodoControllerに対応するのは規約です。

class UrlMappings {
  static mappings = {
        "/todos"(resources:'todo') // urlとして/todosを公開し、対応するコントローラーとしてTodoControllerを指定

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

        "/"(view:"/index")
        "500"(view:'/error')
    }
}

このようにUrlMappingsに指定することで、HTTPメソッド+リクエストURIで呼び出されるコントローラーのアクションメソッドが対応付けられます。

HTTPメソッド リクエストURI コントローラーのアクションメソッド
GET /todos TodoController#index
GET /todos/create TodoController#create
POST /todos TodoController#save
GET /todos/${id} TodoController#show
GET /todos/${id}/edit TodoController#edit
PUT /todos/${id} TodoController#update
DELETE /todos/${id} TodoController#delete

じゃあドメインクラスに@Resourceアノテーションをつけた場合の動作は？

以下のようにドメインクラスにuriパラメータ有りで@Resourceアノテーションをつければ、UrlMappings.groovyに記述しなくてもRESTful APIを公開可能です。

import grails.rest.Resource
@Resource(uri = "/todos") // urlを指定
class Todo {
    String title
}

@Resource:http://grails.org/doc/latest/api/index.html?grails/rest/Resource.html

これはGrailsが裏側で

  1. ドメイン名Controller(この場合はTodoController)を自動生成
  2. uri パラメータに指定した"/todos"を公開するurlとして、1.で自動生成したコントローラーをurlに対応するコントローラーとしてUrlMappingsに登録

してくれています。

そのため2.のUrlMappingsへの登録は、アノテーションのuri指定を省略して直接UrlMappings.groovyに記述することも可能です。

ちょっと話が変わりますが、1.のコントローラーの自動生成についてすでに同名のコントローラーが存在していないかは注意が必要です。

TodoControllerがすでに存在している状態で、Todoドメインに@Resourceアノテーションをつけても正しく動作しません。

これは基本的にGrailsはパッケージが異なる同名のコントローラーの存在を許さないからです。

例外としてGrails2.3.3からnamespaceが導入されてパッケージ違いの同名コントローラーが存在できるようになりました

http://grails.org/doc/latest/guide/theWebLayer.html#namespacedControllers

が、@Resourceアノテーションで自動生成されるコントローラーに対してnamespaceを設定する方法が現状(Grails2.3.4)では無いためやはり正しく動作しません。

従って、すでにHTMLを返すコントローラーを作り込んでいる場合に、コントローラーに触りたくないからドメインに@ResourceアノテーションをつけてラクしてRESTful APIを公開しよう！というのは難しいと思います。(タブン・・・)

HTML、JSON、XMLなどを適切に返せるようにコントローラーを修正しましょう。

まとめ - RESTful API設定方法

RESTful APIを使用するために設定すべきことは以下の1つだけと書きました。

  • 公開するurlとそれに対応するコントローラーを指定

設定すべきことは1つですが、設定方法としては3種類あります。

urlとコントローラーの対応 コントローラー 選択基準 注意点
1 UrlMappings.groovyに記述 手動で作成 アクションメソッドをカスタマイズ、ネストしたリソースを公開したい 特になし
2 UrlMappings.groovyに記述 @Resourceアノテーションによる自動生成 ネストしたリソースを公開したい 自動生成されるコントローラーと同名のコントローラーが存在していないこと
3 @Resourceアノテーションのuriパラメータとして指定 @Resourceアノテーションによる自動生成 1,2に該当しない 自動生成されるコントローラーと同名のコントローラーが存在していないこと

ネストしたリソースをあつかう場合はアクションメソッドをカスタマイズしたいことが多いと思うので 、1を選択するのが良いんじゃないでしょうか。

単純なCRUDに対応するAPIを提供するだけなら3の@Resourceアノテーションを使いましょう。

さいごに

RESTful APIの設定方法について調べてまとめてみました。

気になるところ、間違っているところがあればコメントください。