はじめに
フリーワード検索のRESTFullなAPIを作るにあたって、そういえば有名どころはみんなどんな風に作っているんだろうと思って調べた際のメモ。
確認したサービス
- connpass
- Spotify
- Github
確認のポイント
- APIエンドポイント
- 検索条件の指定方法(AND/OR/NOT)
- ソートの提供
- ページング方法
- レンジ指定での検索方法
- キーワードマッチング(対応してれば)
connpass
ドキュメント
APIエンドポイント
クエリパラメータでkeywordを指定するパータン
GET https://connpass.com/api/v1/event/?keyword=...
検索条件の指定方法(AND/OR/NOT)
- AND/OR毎にクエリパラメータを用意している
- AND条件での検索には「keyword」
?keyword=value1,value2OR条件での検索には「keyword_or」
?keyword_or=value3,value4ANDとORを組み合わせた検索条件の指定はこんな感じ
keyword=value1,value2&keyword_or=value3,value4
ソートの提供
orderパラメータで指定し、区分値を指定して指定する。なお複数指定は不可。
1: 更新日時順
2: 開催日時順
3: 新着順
(初期値: 1)
更新日時順でソートしたい時はこんな感じで指定する
?order=1
ページング
- countパラメータで取得数を指定
- startパラメータで検索開始位置を指定可能
- レスポンスの「results_available」に検索結果の総件数が含まれているため、この件数と取得した件数をもとにstartパラメータを使ってクライアント側でページング
レンジ指定での検索
できない
Spotify
ドキュメント
APIエンドポイント
searchを別のエンドポイントとしているパターン
GET https://api.spotify.com/v1/search
search用の別のエンドポイントとしているパターン
検索条件の指定方法(AND/OR/NOT)
* 「q」パラメータで指定
* スペースを16進数エンコーディングした%20を利用するか、+を利用する
* ただ単語を並べた際はAND条件となる
* AND/OR/NOTのオペレータはいずれも大文字で指定する必要があり。小文字だと検索キーワードとして認識されてしまう。
* AND条件のとき
q=roadhouse%20blues.
- NOT条件のとき
q=roadhouse%20NOT%20blues
- OR条件のとき
q=roadhouse%20OR%20blues
ソートの提供
ない？
レンジ指定での検索
yearフィールとでレンジ指定が可能
q=bob%20year:2014
q=bob%20year:1980-2020
キーワードマッチング
q=roadhouse&20blues だと"Blues Roadhouse"と"Roadhouse of the Blues"がヒット
q="roadhouse&20blues" だと"My Roadhouse Blues"がヒットし"Roadhouse of the Blues"はヒットしない
GitHub
ドキュメント
APIエンドポイント
searchを別のエンドポイントとしているパターン
GET /search/{検索対象}
検索条件の指定方法(AND/OR/NOT)
- 「q」パラメータで指定。 q=tetris+language:assembly といった具合に、条件を繋いでいく。
- フリーワード検索部分は基本ANDで繋がっていく？
- NOT/-での除外が可能。
- 検索方法の詳細は 別途ここにある https://help.github.com/articles/understanding-the-search-syntax/
ソートの提供
- sortパラメータで並び替えるフィールドを指定。デフォルトは検索マッチのスコア。
- orderパラメータで昇順か降順かを指定。asc/desc
ページング
- ヘッダに後続のページへのリンクが入っているHETEOS形式。
レンジ指定での検索方法
- 大なり小なり記号を利用
- ?pushed:>=2017-07-01+pushed:<2017-08-30