Skip to content

OpenAPI規約の内容を転記 #6

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ma91n merged 2 commits into from
Jan 20, 2025
+16 −15
Merged

OpenAPI規約の内容を転記 #6

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ddc9573
OpenAPI規約の内容を転記
ma91n Jan 20, 2025
ad1c507
npm run format
ma91n Jan 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 8 additions & 8 deletions documents/forCodeReview/code_review.md
View file
Open in desktop
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
Open in desktop
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
Loading