フロントエンドの視点からより良いGraphQL APIを作ってもらうためにフィードバックする話をした

hatena.connpass.com

昨日発表しました。株式会社はてなという会社でWebアプリケーションエンジニアとして働いています。

発表資料はこちら。前半だけ読むとGraphQLとRelayの概要をさらっと流せる資料になっています。全部読んでください。

作ってもらったAPIをもとに開発を進める、というとAPIを作ってもらってフロントエンドを実装したら終わり、という感じが出るかもしれません。そうではなくて、最高のGraphQL APIにしてもらえるようにフィードバックして、開発体験やロジックの一貫性を高めましょう、という話をしました。

他のフィードバックの話題

せっかくなので、発表中には紹介しなかったスキーマフィードバックの話題についても書いておきます。

コメントにいろいろ書いてもらう

フィールドがnullableになる条件、という文脈でちょっと触れていましたが、一般には、スキーマ定義だけから読み取れない情報をスキーマのコメントに書いてもらえると実装しやすいです。たとえば、percentage という値の範囲が0〜100なのか0.0〜1.0なのか、ということを書いてもらえると、とりうる値の範囲のほかにも、どう整形して表示したらよいかが分かりやすくなります。

enumを使い倒す

クエリの引数、オブジェクトの状態、などなど整数や文字列ではなくenumを使うと値の範囲を絞れるところではenumを使うとよいです。enumにしておくと、TypeScriptの文字列リテラル型が使えて場合分けを網羅しやすい、という利点もあります。

排他な状態を isX isY isZ のような真偽値のフィールドで表すのではなく X Y Z の値をとるenumのフィールドで表してもらえると、排他であることが明確になって最高ですね。

mutationのレスポンス

Relayを使うと、mutationのレスポンスをもとにクライアントキャッシュのデータを更新することができます。したがって、mutationを発行した後に更新する必要がある画面要素を逆算した上でレスポンスを返してもらえるようにすると、1リクエストでサーバー上のデータの更新からクライアントキャッシュの更新もできるのでお得です。