RESTful#とは勉強会13 2016.02.23

https://rubychildren.doorkeeper.jp/events/39034

質問はTwitterへ #RESTudy をつけてどうぞ。

ワークショップ RESTfulなAPIとは

「駅すぱあとWebサービス」を題材に、どこがRESTfulか、どうしたらRESTの規約に近づけるかなどグループで話し合いましょう。

駅すぱあとWebサービス

今回の勉強会用にアクセスキーを提供していただいています。ありがとうございます！

グループで考えてみよう

今回はWebサイトではなくWeb APIなので、ドキュメントがリソースのリストになっています。
例：駅情報リソース、経路探索リソース、…

実際にAPIを使ってみましょう。（調べ方のヒント参照）
リソースのURLはどんな名前でどういう規則になっているでしょうか？
このAPIを使って、どのようなアプリケーションが作れるでしょうか？そのアプリケーションでは、どのAPIをどんな順番で使いますか？
「Webを支える技術」の郵便番号検索サービス（ricollab 郵便番号検索）と比較すると、似ているところ、違うところはどこでしょうか？
ここはRESTfulだ、ここはRESTfulじゃない、と思うところはどこでしょうか？どうすればよりRESTfulにできるでしょうか？

調べ方のヒント

curlやhttpieを使って実際にAPIにアクセスしてみましょう。

例：APIで「高円寺」の駅情報を取得

まず「高円寺」をURLエンコードします。

encodeURIComponent('高円寺'); // => "%E9%AB%98%E5%86%86%E5%AF%BA"

require 'uri'
URI.encode_www_form_component('高円寺') # => "%E9%AB%98%E5%86%86%E5%AF%BA"

URLのパラメータに文字列を加えて、curlやhttpieでアクセスします。

$ curl -v "http://api.ekispert.jp/v1/json/station?name=%E9%AB%98%E5%86%86%E5%AF%BA&type=train&key=xxx"⏎

*   Trying 54.92.14.234...
* Connected to api.ekispert.jp (54.92.14.234) port 80 (#0)
> GET /v1/json/station?name=%E9%AB%98%E5%86%86%E5%AF%BA&type=train&key=xxx HTTP/1.1
> Host: api.ekispert.jp
> User-Agent: curl/7.43.0
> Accept: */*
> 
< HTTP/1.1 200 OK
< Access-Control-Allow-Origin: *
< Content-Type: text/plain;charset=utf-8
< Date: Tue, 23 Feb 2016 06:11:31 GMT
< Status: 200 OK
< X-Content-Type-Options: nosniff
< Content-Length: 365
< Connection: keep-alive
< 
* Connection #0 to host api.ekispert.jp left intact

{"ResultSet":{"apiVersion":"1.26.0.0","max":"1","offset":"1","engineVersion":"201602_03a","Point":{"Station":{"code":"22671","Name":"高円寺","Type":"train","Yomi":"こうえんじ"},"Prefecture":{"code":"13","Name":"東京都"},"GeoPoint":{"longi":"139.39.10.89","lati":"35.42.7.59","longi_d":"139.653027333333344","lati_d":"35.702110444444444","gcs":"tokyo"}}}}

$ http -v GET "http://api.ekispert.jp/v1/json/station?name=%E9%AB%98%E5%86%86%E5%AF%BA&type=train&key=xxx" Accept:application/json⏎

GET /v1/json/station?name=%E9%AB%98%E5%86%86%E5%AF%BA&type=train&key=xxx HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Connection: keep-alive
Host: api.ekispert.jp
User-Agent: HTTPie/0.9.2


HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Connection: keep-alive
Content-Length: 365
Content-Type: application/json;charset=utf-8
Date: Tue, 23 Feb 2016 06:02:11 GMT
Status: 200 OK
X-Content-Type-Options: nosniff

{
    "ResultSet": {
        "Point": {
            "GeoPoint": {
                "gcs": "tokyo", 
                "lati": "35.42.7.59", 
                "lati_d": "35.702110444444444", 
                "longi": "139.39.10.89", 
                "longi_d": "139.653027333333344"
            }, 
            "Prefecture": {
                "Name": "東京都", 
                "code": "13"
            }, 
            "Station": {
                "Name": "高円寺", 
                "Type": "train", 
                "Yomi": "こうえんじ", 
                "code": "22671"
            }
        }, 
        "apiVersion": "1.26.0.0", 
        "engineVersion": "201602_03a", 
        "max": "1", 
        "offset": "1"
    }
}

httpieのほうが見やすいのでおすすめです。

GUIソリューションのサンプルを使う

GUIソリューションのサンプルページではブラウザからAPIにアクセスすることができるので、デベロッパーツールでリクエストを見ることができます。

例：駅情報の取得サンプル
http://ekispertwebservice.github.io/GUI/sample/stationInfo.html

デベロッパーツールの起動

Windows: F12 か Ctrl+Shift+i
Mac: command+option+i

リクエスト／レスポンスを見て、HTTPのルールに沿っているかどうか、RESTfulかどうかを調べましょう。

REST復習の参考スライド

「Webを支える技術」も活用しましょう。

西谷さんによる公開レビュー

質問・ディスカッション

tkawa/restful-towa-13.md