Skip to content

Commit

Permalink
Merge pull request #6 from future-architect/feature/webapi_openapispec
Browse files Browse the repository at this point in the history 
OpenAPI規約の内容を転記
  • Loading branch information
@ma91n
ma91n authored Jan 20, 2025
2 parents 655506a + ad1c507 commit e3ee5ca
Show file tree
Hide file tree
Showing 2 changed files with 16 additions and 15 deletions.
16 changes: 8 additions & 8 deletions documents/forCodeReview/code_review.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -479,15 +479,15 @@ GitHubでのコードレビューは、`Start a review` を行うと `Submit rev

以下にプレフィックスを利用した例を示す。

| プレフィクス | 説明 | 例 |
| :----------- | :------------------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------- |
| LGTM | Look Good To Me（良さげです） | \[LGTM\] 責務分解が明瞭で、良い実装です！💯 |
| ASK | 質問 | \[ASK\] この実装意図が理解できず、どうして必要なのか教えてもらえますか❓️🤔 |
| Q | ASKと同じ意味 | \[Q\] 同上 |
| MUST | 必須 | \[MUST\] ソート処理が漏れているため、順序が不正になってしまう可能性があります！ |
| SHOULD | 提案 | \[SHOULD\] 愚直なループではなく、□□□の書き方の方が可読性および性能が良いです。書き換えを検討してください。 |
| プレフィクス | 説明 | 例 |
| :----------- | :------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------- |
| LGTM | Look Good To Me（良さげです） | \[LGTM\] 責務分解が明瞭で、良い実装です！💯 |
| ASK | 質問 | \[ASK\] この実装意図が理解できず、どうして必要なのか教えてもらえますか❓️🤔 |
| Q | ASKと同じ意味 | \[Q\] 同上 |
| MUST | 必須 | \[MUST\] ソート処理が漏れているため、順序が不正になってしまう可能性があります！ |
| SHOULD | 提案 | \[SHOULD\] 愚直なループではなく、□□□の書き方の方が可読性および性能が良いです。書き換えを検討してください。 |
| IMO | In My Opinion（自分ならこうしますが、どうでしょうか？） | \[IMO\] スコープの広さの割に変数名が短いため、 `name` ではなく `pre_ordered_product_name` などが良いかと思いました |
| NITS | Nitpick（枝葉ですが直して欲しい） | \[NITS\] この変数名は、単数形よりも複数形 `users` または `usersList` が適しているかと思います。 |
| NITS | Nitpick（枝葉ですが直して欲しい） | \[NITS\] この変数名は、単数形よりも複数形 `users` または `usersList` が適しているかと思います。 |

それぞれの定義は以下。特に「ASK（Q）」と「MUST」はレビューコメントが解決しないと、プルリクエストの承認を行うべきではない。

Expand Down
15 changes: 8 additions & 7 deletions documents/forWebAPI/web_api_guidelines.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1199,11 +1199,11 @@ sequenceDiagram

業務システムにおいても点検結果の写真や動画、WordやPDFなど非構造データをアップロードすることがしばしば求められる。クラウド環境ではアップロードされたコンテンツは、最終的に通常オブジェクトストレージに格納することとするが、手法については以下のようにいくつかパターンがある。

| 手法 | 説明 | Poc/Cons |
| :-------------------- | :----------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------- |
| 1.multipart/form-data | RFC 2388でも定義された、古くから利用される方式 | ✅️枯れている ⚠️ブラウザ以外のクライアントからは扱いにくい |
| 2.Base64 | ファイルをBase64形式にエンコードして、通常のフォームデータとして送信する方法 | ✅️通常のリクエストボディでJSON要素の値として設定できるので楽 ⚠️ファイルサイズが大きくなるため、ファイルサイズによってはオーバーヘッドが大きい |
| 3.署名付きURL | オブジェクトストレージで特定の期間内にのみ有効な一時的なURLを生成し、そのURLを使用してアップロードを行う方法 | ✅️負荷をクラウドサービス側にオフロードできる ⚠️メタデータ系の登録は、別途Web APIを叩く必要があるなど、クライアント側に手続きが発生 |
| 手法 | 説明 | Poc/Cons |
| :-------------------- | :----------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 1.multipart/form-data | RFC 2388でも定義された、古くから利用される方式 | ✅️枯れている<br>⚠️ブラウザ以外のクライアントからは扱いにくい |
| 2.Base64 | ファイルをBase64形式にエンコードして、通常のフォームデータとして送信する方法 | ✅️通常のリクエストボディでJSON要素の値として設定できるので楽<br>⚠️ファイルサイズが大きくなるため、モバイルなどのクライアントでは帯域の観点で懸念 |
| 3.署名付きURL | オブジェクトストレージで特定の期間内にのみ有効な一時的なURLを生成し、そのURLを使用してアップロードを行う方法 | ✅️負荷をクラウドサービス側にオフロードできる<br>✅️ Amazon API Gateway を利用する場合は、2023 年 6 月時点で[ペイロード上限が 10MB](https://docs.aws.amazon.com/apigateway/latest/developerguide/limits.html)、[AWS Lambda でもペイロード制限がある](https://docs.aws.amazon.com/ja_jp/lambda/latest/dg/gettingstarted-limits.html#api-requests)ため、許容するファイルサイズによってはこの手法一択となる<br>⚠️メタデータ系の登録は、別途Web APIを叩く必要があるなど、クライアント側に手続きが発生 |

本規約の推奨は以下の通り。

Expand Down Expand Up @@ -1253,6 +1253,7 @@ sequenceDiagram
参考:

- [署名付きURLを利用したファイルアップロードWeb API設計の勘所 | フューチャー技術ブログ](https://future-architect.github.io/articles/20240705a/)
- [AWS のサーバーレスと Amazon S3 署名付き URL、クライアントサイド JavaScript で大きなサイズの複数ファイルの一括アップロード・ダウンロード機能を実現する方法 | Amazon Web Services ブログ](https://aws.amazon.com/jp/blogs/news/large-size-files-transferring-by-serverless-s3presignedurl-and-clientside-javascript/)
- [S3 バケットを AWS Lambda を使って、ウィルススキャンしてみた | DevelopersIO](https://dev.classmethod.jp/articles/s3-bucket-antivirus-lambda/)
- [S3のメタデータを用いた攻撃](https://zenn.dev/p0n/articles/3a6139cce9fa17)

Expand All @@ -1262,7 +1263,7 @@ sequenceDiagram

- サムネイルなど小さなデータの場合（数KB程度を想定）は、Base64でエンコードし、JSON項目の値に設定して返す
- この場合は、URIでそのままimageタグに埋め込めるようにデータURIスキームで返す
- 例えば、`\<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA..." alt="サムネイル画像"\>` srcに設定されるような形式である
- 例えば、`<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA..." alt="サムネイル画像">` srcに設定されるような形式である
- 上記以外の場合は、署名付きURLを利用してダウンロード

### 署名付きURLの処理フロー
Expand Down Expand Up @@ -1436,7 +1437,7 @@ sequenceDiagram
| :----------- | :----------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------- |
| 説明 | サーバー側で更新があるまで待機し、更新があったタイミングで応答。再びクライアント側から再接続してもらう | HTTPプロトコルを使用し、クライアント側からサーバへHTTPリクエストを送り、その接続を維持することで、サーバから継続的にデータをストリーム送信する | 双方向通信が可能で、サーバ／クライアント間でメッセージを送受信できる。バイナリ送信も可能で効率が良い |
| 通信方向 | 一方向 | 双方向 | 双方向 |
| 即時性 | ❌️1度のやり取りでヘッダなどが付与されるためオーバーヘッドあり | ⚠️高いが | ✅️最も低レイテンシ |
| 即時性 | ❌️1度のやり取りでヘッダなどが付与されるためオーバーヘッドあり | ⚠️高い | ✅️最も低レイテンシ |
| プロキシ対応 | ✅️高い | ✅️高い | ⚠️ブロックされる可能性がほかと比較すると高い |
| 接続維持 | ❌️自前実装（再接続実装） | ✅️自動再接続機能がある | ⚠️クライアント側で再接続ロジックを実装 |
| 保守運用性 | ⚠️古い手法である | ✅️比較的低い | ⚠️WebSocketの扱いをサーバ／クライアントで慣れる必要がある |
Expand Down

0 comments on commit e3ee5ca

Please sign in to comment.