実践API設計:目次 [API仕様を書く]
特集1「実践API設計」の構成が分かるように目次を作成してみました。
第1章 優れたAPI仕様とは何か
特集のはじめに
APIとは
フレームワークや標準ライブラリのAPI仕様
企業内でのAPI仕様
優れたAPI仕様とは
理解が容易
変更が容易
テストが容易
API仕様でよくある問題点
API仕様が書かれていない
エラーの記述がない
自動テストが存在しない
API仕様に書くべきこと
サービスの概要の説明
個々のエンドポイントの説明
エラーの説明
パラメータの不正値
誤った順序での呼び出し
認証と認可のエラー
そのほかのエラー
まとめ
第2章 gRPCにおけるAPI仕様の書き方
gRPCとは
API仕様をどこに書くか
サービスの概要の記述
個々のエンドポイント(RPC)の説明
エラーの説明
パラメータの不正
InvalidArgument ── 不正なパラメータ値
NotFound ── リソースが見つからない
OutOfRange ── 指定された範囲のデータがない
誤った順序での呼び出し
FailedPrecondition ── 事前条件が成立していない
認証や認可のエラー
Unauthenticated ── 認証できない
PermissionDenied ── 認可できない
サービスの概要に書くべきそのほかのエラー
Canceled ── キャンセルされた
DeadlineExceeded ── 処理がタイムアウトした
Unknown ── 不明なエラー
Internal ── 内部エラーが発生した
個々のエンドポイントに書くべきそのほかのエラー
AlreadyExists ── リソースがすでに存在する
ResourceExhaused ── サービス側のリソースの枯渇
Aborted ── 処理が中断された
書く必要がないエラー
Unavailable ── サービスが動作していない
DataLoss ── データが失われた
Unimplemented ── まだ実装されていない
リストオプションの説明
まとめ
第3章 API仕様ファースト開発
開発順序
API仕様の記述
E2Eテストフレームワークの検討と実装
テストコードの作成と機能の実装
リファクタリングとカバレッジの確認
Pull Requestのレビュー
不具合の修正順序
再現テストの作成と実装の修正
リファクタリングとカバレッジの確認
既存のエンドポイントの修正と新たなエンドポイントの追加
まとめ
第4章 E2Eテストフレームワークの構築
テストフレームワークの基本的な考え方
マイクロサービス構成でのテストフレームワーク
書きたいテスト
レスポンスの確認
依存サービスを正しく呼び出しているかの確認
E2Eテストフレームワークのプロセス
E2Eテストのプロセス間シーケンス
依存サービスが外部サービスの場合の解決方法
エラーのテストは簡単
DeadlineExceededとCanceled
Aborted
非マイクロサービス構成でのテストフレームワーク
E2Eテストフレームワークの骨格
Test Suiteプロセスの骨格
テスト対象マイクロサービスの骨格
フェイクマイクロサービスの骨格
テストコードの骨格
そのほかの考慮項目
まとめ
第5章 API仕様の技術的負債の返済
技術的負債とは
API仕様の負債の返済
既存のエンドポイントを修正するケース
ステップ1:既存のAPI仕様の更新(見なおし)
ステップ2:既存のAPI仕様のテストコード作成と実行
ステップ3:新たな修正のためのAPI仕様の再修正
ステップ4:新たな修正に対するテストコードの作成
ステップ5:新たな修正の実装
ステップ6:リファクタリングとカバレッジの確認
新たなエンドポイントを追加するケース
既存のエンドポイントの不具合を修正するケース
返済順序のまとめ
E2Eテストのもう一つの利点:リファクタリング
特集のまとめ
2023-08-21 05:47
コメント(0)
電子版『Go言語100Tips』 [本]
8月18日に発売される『Go言語100Tips』ですが、以下の電子版も発売されます。
Kindle版は固定レイアウトだと思います。
https://book.impress.co.jp/books/1122101133
Kindle版
Go言語 100Tips ありがちなミスを把握し、実装を最適化する (impress top gear)
- 出版社/メーカー: インプレス
- 発売日: 2023/08/18
- メディア: 単行本(ソフトカバー)
Kindle版は固定レイアウトだと思います。
PDF版
出版社のサイトからソーシャルDRM版のPDF版を購入できるようになります。https://book.impress.co.jp/books/1122101133
2023-08-17 11:12
コメント(0)
実践API設計 [API仕様を書く]
4月に発売された「WEB+DB PRESS Vol.134」で特集1「実践API設計」を執筆していますが、そこから部分的に紹介します(目次は、こちらです)。
第1章「優れたAPI仕様とは何か --- よくある問題と記述すべき事柄」の冒頭で次のように述べています。
今日、多くの企業がWeb サービスとしてさまざまなサービスを提供しています。Webサービスは、iOS、Android、ブラウザといったフロントエンドと、それらに対して機能を提供するバックエンドサービスから構成されます。バックエンドサービスが提供するさまざまな機能はAPI (Application Programming Interface)として定義され、フロントエンドから呼び出されます。フロントエンドは、バックエンドサービスが提供する機能を使ってユーザーへ提供する機能を実現します。
定義されたAPI を介することで、フロントエンドとバックエンドサービスが、独立して、異なるプログラミング言語で開発できます。その結果、バックエンドサービスの開発チームは、定義されたAPI どおりにバックエンドサービスが正しく動作することを保証する責任を負います。つまり、API 定義に従って正しく動作することを、フロントエンドを接続することなく、自動テストで確認することが求められます。
Web サービス開発の中で意外と難しいのが、バックエンドサービスのAPI を設計し、そのAPI 仕様を記述し、そしてテストファーストによるテスト駆動開発を行うことです。この特集では、それらが何を意味し、開発者にとって日々の活動で何をしなければならないかを解説します。
(太字で青にしている部分は、このブログで強調するためのものです)
長年、デジタル複合機を中心とした組込システムの開発に従事してきましたが、リコーを退職した後、2017年9月から、ウェブサービス(バックエンド)の開発に従事してきました。
当初から驚いたのが、バックエンドのサービスのAPIは定義するが、そのAPIで定義したエンドポイントを直接呼び出してサービスの機能を確認テストを書くことがほとんどないことです。つまり、さまざまなモジュールの単体テストはあるのですが、すべてを結合して一つの実行バイナリにして、APIで定義されたエンドポイントを外部から呼び出すテストコードがないことです。
この6年間で見られた問題点の多くは、「API仕様でよくある問題点」で次のように述べています。
筆者はこれまで、Web サービス開発だけでなく、組込みシステムを含むさまざまなソフトウェア開発に従事してきました。それらの開発を通してAPI 仕様のさまざまな問題を目にしてきましたが、主なものとしては次の3つが挙げられます。この結果、開発現場でよく起こるのは次のようなことです。
- API仕様が書かれていない
- エラーの記述がない
- 自動テストが存在しない
これらの3つの問題をもう少し詳しく見ていきます。
- 正確な仕様は、実装コードを読まないとわからない
- どのような場合にどのようなエラーが返ってくるかは、実装コードを読まないとわからない
- 自動テストがないため、API がどのように振る舞うのかを簡単に知る方法がない
記事では、これらの問題点をさらに詳しく説明しています。
ここでの問題点は、この6年間で働いてきたソラミツ、メルペイ、カウシェの3社で入社した当初に、私が目にしたバックエンドのサービス開発のほぼすべて(ただし、メルペイで私が最初に担当したマイクロサービスを除く)で目にしてきたものです。
その都度、この特集記事で述べたことを実践して改善していきました。改善は、単に私一人が行うものではなく、同じチームのメンバーが上記の問題を起こさないように開発を行ってくれるように、意識も行動も変わってくるようにするというものです。結果として、上記の問題を残さないようにする開発組織へと変わっています。
3社での経験から、おそらく多くの企業でこの問題は見られるのではないかと思っています。
関連記事:「伸ばすのが難しい能力」
(2023年8月15日追記:下記は、『WEB+DB PRESS, Vol.134』のp.12より引用)
API仕様が書かれていない
API 仕様が書かれていないというのは、次のような状況を指します。Java などの言語で書かれている公開API を構成するクラスやメソッドに、標準のJavadoc形式があるにもかかわらず何も書かれていない。これを、通信方式としてGoogle が開発しているgRPCを使っているバックエンドサービスに当てはめてみます。gRPCでは.protoファイルにprotobufsと呼ばれるAPI の定義を記述しますが、そのファイルの内容が次のような状況になります。
単にサービスのエンドポイント(rpc)の定義やメッセージ構造体の定義が書かれているだけで、説明がほとんど書かれていない。
2023-08-09 05:06
コメント(0)