皆さんは普段、WEBでAPIを作っていますでしょうか？ 最近はリッチなUIやスマートフォンアプリの開発が当たり前になってきたので、 APIを作ることが多いのではないでしょうか。
APIの開発を楽にするために、GraphQLを使ってみませんか？
現状のAPI開発の悩み
現在APIを作るときは、REST設計で開発を行うことが多いと思います。 実際開発中に以下のような悩みを持ったことはないでしょうか？
- API多すぎ
- 仕様がよく変わる
- ドキュメントがメンテできない
- もうRESTのAPI作るの飽きたよ…
そんなあなたにぜひGraphQLを！ GraphQLを使えば楽しいAPI開発が待っているかも！
GraphQLって何？
答: A query language for your API. (出典: GraphQL )
以上です！(^o^)
……要するに、SQLみたいにクエリを書いて、サーバにリクエストして、 自分が欲しいデータを取って来たり、変更するということができるものです！
GitHub GraphQL API を試そう！
GraphQLがどういうものなのかを知るためには、GitHubが公開しているGraphQL APIを試してみるのがわかりやすいと思います。
そこで、GitHubのAPIを使ってGraphQLがどのようなものなのか試してみましょう！
GraphQL API Explorer | GitHub Developer Guide
上のURLにアクセスして、右上の Sign in With GitHub からログインしましょう。
ログインするとすぐに使用できるようになります。
左上がクエリエディタになっていて、ここにサーバにリクエストするクエリを書いていきます。 右側は、サーバからのレスポンスが表示されます。
自分のアカウント情報を取得する
ではクエリエディタに下のものをコピーして貼り付けて、実行してみましょう！
- クエリ
query {
viewer {
name
}
}
実行は 再生ボタン みたいなのがあるので押すと実行されます。
実行すると下の様なレスポンスが返ってくると思います。
- レスポンス
{
"data": {
"viewer": {
"name": "masa"
}
}
}
ここにさらに、アバターURLを取ってみましょう！
- クエリ
query {
viewer {
name
avatarUrl
}
}
- レスポンス
{
"data": {
"viewer": {
"name": "masa",
"avatarUrl": "https://avatars2.githubusercontent.com/u/47341025?v=4"
}
}
}
追加で登録してあるアバターのURLが取得できました！
このように自分が欲しい情報に合わせて、クエリを書くことでレスポンスを調整することができるのがGraphQLの特徴になります。 SQLのSELECT文をイメージしていただくと、わかりやすいのではないかと思います。
query とは？
ここで、先程からエディタに書いてたものは、どのような構造をしているのかを見ていきましょう。
まず query についてです。
query {
viewer {
name
}
}
query はデータを取得するリクエストであることを示しています。
SQLではデータを取得する時に必ず SELECT を書くと思いますが、GraphQLでは必ず query を書くことになります。
この query の中には viewer という指定がありますが、
これは viewer というデータを返してくれというリクエストになります。
上の query をSQLで書くと下のような感じになります。
SELECT name FROM viewer
viewer の中身
viewer の中には name や avatarUrl など指定ができましたが、他にはどんなものが指定できるのか気になると思います。
これを調べるために、このAPIコンソールには便利なドキュメントビューワーが付属されています。
エディタの右端に Docs というボタンがあるので押すとドキュメントを見ることができます。
開いたら、viewer を検索してみましょう！
すると Query.viewer が出てくると思います。
これをクリックすると、詳細が見れます。
認証中のユーザ情報が返ってくることがわかりました！
その下に TYPE で User! というのがあるので、TYPEについて説明します。
Type
型の指定のことです。これはClassのようなものとイメージするとわかりやすいです。 ルールは以下のようになっています。
type 型名 {
名前: 型
}
型を構成する Field を書くことができます。
先程の User! の中身を見てみましょう。
FIELDS にどんなデータなのかの指定があります。
先程指定した name , avatarUrl だけ定義してみると下の形になります。
type User {
name: String
avatarUrl: URI!
}
後ろに ! があるのは NULL不許可 を示しています。
avatarUrl を指定すると必ず URI型 のデータが返ってきます。
URI型 もドキュメントからどんな型なのか見ることができます。URIの定義に則った文字列が返ってくることがわかると思います。
データを更新する
APIではデータを作成、更新、削除したりすることがありますが、
GraphQLではこれらは mutation で指定する形になります。
mutation {
ここにどの操作を行うかを書く
}
リポジトリにスターを付けてみる
addStar というスキーマが用意されているので、これを使うとGitHubのリポジトリにスターを付けることができます。
まずドキュメントを使って仕様を確認してみましょう。
Mutation.addStar が表示されます。
ARGUMENTS に指定する引数が書かれています。
addStar には input に AddStarInput! が必須であるとわかります。
(AddStarInputの後ろに ! が付いているからです)
AddStarInput の中身を見ていくと、starrableId が ID型 で必須ということがわかります。
ID型 はGraphQLの組み込み型で、通常はbase64エンコードされた文字列が使われるようです。
このIDはリポジトリごとにユニークなものが振られています。 スターを付けるためには、このリポジトリのIDを取得する必要があります。
以下のクエリで取ってこれます。
query {
viewer {
repository(name: "pokemon") {
id
}
}
}
このクエリは自分が所持しているリポジトリの名前が pokemon であるものを取得するものになります。
レスポンスは以下になります。
{
"data": {
"viewer": {
"repository": {
"id": "MDEwOlJlcG9zaXRvcnkxODAyNTUzNDk1="
}
}
}
}
ここで取ってこれたIDを使います。 スターを更新する構文は以下になります。
mutation {
addStar(input: { starrableId: "MDEwOlJlcG9zaXRvcnkxODAyNTUzNDk1=" }) {
clientMutationId
}
}
これを実行するとスターが付くかと思います！
仕様通りに addStar の引数に input: { starrableID: "ID" } の形式で指定を行っています。
GraphQLでは addStar のような構文でも 必ず返り値を指定する ことになっています。
しかし更新系のスキーマでは返り値が不要なこともあるかと思います。
そこで、clientMutationId という指定をすることで、NULL の返り値をレスポンスとして受け取ることができるようになっています。
このスキーマのレスポンスは以下の様になります。
{
"data": {
"addStar": {
"clientMutationId": null
}
}
}
この他にも、スターを外したり、PullRequestにコメントを付けたりするスキーマなどが用意されています。 ドキュメントを調べて実際に使ってみると、GraphQLが何となくわかってくるかと思います。
実装するには
各プログラミング言語用のライブラリが用意されているので、これを使うことでGraphQLの実装を行うことができます。
また、Applo Engine や AWS AppSyn のようにGraphQLを使う環境が既に用意されていて、後はデータやスキーマを用意するだけで簡単に利用することができるサービスもあります。
まとめ
GitHubが公開しているGraphQLを使ったAPIのご紹介をしました。 GraphQLはまだまだWEB上で知見があまりなく、自分でGraphQLを作る時にどうやって実装して良いのか悩むことがあるかと思います。
そんな時には既に GitHubのAPIの仕様を参考にして開発してみるといい感じに実装ができるのではないかと思います！