5月30日(火)にAPIStudy #8が、江戸川橋にある株式会社アプレッソにて開催されました。
1か月経つ勢いですけど、その様子をご報告します。
對馬です。
前回の報告記事はこちらからご覧いただけます。
今回はアプレッソ?
APIStudyの会場は毎月変わります。
聞いたことがある方もいると思いますが、「12回目、つまり1周年記念はアプレッソでやるんだー!」と、運営の脇野はよく話していました…。
なので今回の会場を聞いたとき、私は耳を疑いました。
だってまだ8回目、8か月目なんですもの。
でも1周年をアプレッソで開催するというのはまだ挫けていないようなので、あと3か月ほど、楽しみに待っておきましょう…。
私の話をしますと、4月からセゾン情報システムズに移籍となったので、約2か月ぶりのアプレッソ。2か月じゃそんなに変化を遂げることもなく、Facebookでアプレッソにチェックインしたことくらいが、なんか変な感じ。
第1部:LTタイム
今回もたくさんのみなさんにご参加いただきました!
ありがとうございます!
まずは運営の脇野、そして市川さんからこの1か月で起こったIT的出来事の共有、それとIT小噺。
佐藤さん
そして今回はSendGrid 佐藤さんからLTをしていただきました!
「SendGridにおけるStopLightを活用したAPI管理」
構造計画研究所 佐藤さん
StopLightはAPIを管理するサービスで、4つ機能が提供されています。
API Designer:API設計するためのUI
Hosted Dogs:ユーザー向けのドキュメント管理のツール
Scenarios:テストを管理するためのツール
Prism:Proxy Server
また、SendGridはメールに関するAPIを提供するサービスです。
メール送信のほかにもいろんな機能があるそうです!
そして、SendGridでのStopLightの活用方法をご紹介いただきました。
StopLightは3つのポイントで活用!
- Swagger SpecにAPIのI/Oを出力するため。
- APIライブラリのテストに。
- ドキュメントのため。
脇野さん
続いて、今回の会場枠でアプレッソ脇野より。
「PIMSYNC WebAPI設計の悩み」
PIMSYNCとは、異なるスケジューラにあるスケジュールを同期することができるアプレッソの製品です。
このスケジュール連携を行うことで、複数のスケジューラを入力・変更しなければいけない場面でも、2度の入力を省いたり、変更ミス・入力漏れを防いだりすることができます。
そんなPIMSYNCでもWebAPIを開発したのですが、なかなかうまく活用方法を説明できないもので、APIはどんな粒度で開発すればよいのだろうかという悩みを抱えていると話していました。
求ム!ベストプラクティス!!
第2部:ディスカッションタイム
それではお待ちかねのディスカッションのお時間です!
今回もまずはチームを作ってもらい、掘り下げたい話題をチーム内で決定して、ベストプラクティスを追及していきます!
ディスカッションが終わったら、チームで話し合った内容を全体に共有します。
APIのすみわけ
脇野さんのお悩み相談室!
API設計において、ユーザーの声をどこまで聞くのか?というお悩みでした。
開発したAPIとユーザーがAPIに求める内容にズレがあった、というお悩み。
しかしAPIはリソースに対しての単機能として提供するべきで、将来性を考えると、「要望に応じた作りこみ」は避けた方がよいものです。
そこでAPIを組み合わせて、ユーザーの要望を解決するのですが、その組み合わせどうのこうのに関しては外部でやるべき、という結論になりました。
要するに、
第1フェーズ:APIをシンプルに提供(プロバイダ)
第2フェーズ:APIを組み合わせていく(SIer)
というようなすみ分けが重要なのです。
△すみ分け図
エンドポイントの設計について
pathでバージョンを表現するのが好きじゃない!
バージョンの書き方に悩んで三日三晩寝れない…!
どうしよう!という話。
RESTでは名詞をつなげてpathを作る。
これは、業務的に扱うものをpathで表現する方がわかりやすいから。
一方でバージョンというのは、APIで作るうえの都合でしかないので、pathに含めていいのか悩ましい。
pathとバージョンはうまく分けた方がいいのではないか?
ではバージョンをどこに書くか? という回答としてヘッダーに書くのが良いのでは、という提案。
これによって、バージョンを知って制御をしたい人はヘッダーを使う、
APIを使って実際に作る人達はpathだけを見る、という切り分けができる。
このように分けることで、開発が大きくなった時も統制しやすくなるのでは。
また、Getで検索クエリを渡す必要があるので扱いどうする?という話では、pathに無理やり書く or クエリに書くという方法があるが、この2つも論争が起きそう…と話していました。
HTTPのメソッドにSearchがあればいいのに…という意見も。
StopLightの有効活用
StopLightとSwaggerとどう使い分けるのか
ツールを使うか使わないか?という前提的な質問。
→これは使った方がよい
理由:ミスがない、ドキュメントと実装の乖離を防げる。
StopLightとSwaggerの使い分けについて
チーム開発になってきたら、ツール使った方がいい。
・使い分けの基準
API開発だと5人くらいだと思うので3人くらいで考える必要がある。
エンドポイントの数も基準にできる。
1人20個くらい見れるかな…。
・差
Swagger:自前で用意しなければいけない。
Prism:通しておけば、ほぼそのままテストデータできる。
Prismいいね!
△粗くてごめんなさい…
おわりに
APIStudyは、APIのベストプラクティスを追及する勉強会です。
参加者みなさんの「これこそがベストプラクティスだ!」というお話もどんどんしていただきたいですし、それだけでなく、今回みたいに実際に困っていることをディスカッションして、ベストプラクティスに導いてもらうこともできます。
あなたのベストプラクティスをお待ちしています!
今回のグラフィックレコードはこちら!
いつも丁寧で素敵なグラレコありがとうございます!
第8回の「8」がスパイダー柄になってて可愛い(≧▽≦)
そして
次回開催が決定しました!
APIStudy #9は、#8でもLTをしていただきました構造計画研究所さんにお邪魔します!
さらなる深みが聞けるかも…!?
もう来週の話ですが、お時間のある方はぜひ足を運んでいただけると嬉しいです!
そして周辺のAPIStudy初心者!という方も誘っていただけるとさらに嬉しいです…。
散々開催報告を書いてきましたが、実際に参加して、LTを聞いて、ディスカッションしてみないと伝わらないことがたくさんあります!
ぜひ体験してみてください!
よろしくお願いします。