Skip to content

Commit e3ee5ca

Browse files
ma91nma91n
authored
Merge pull request #6 from future-architect/feature/webapi_openapispec
OpenAPI規約の内容を転記
2 parents 655506a + ad1c507 commit e3ee5ca

File tree

2 files changed

+16
-15
lines changed

2 files changed

+16
-15
lines changed

‎documents/forCodeReview/code_review.md‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -479,15 +479,15 @@ GitHubでのコードレビューは、`Start a review` を行うと `Submit rev
479479

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

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

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

‎documents/forWebAPI/web_api_guidelines.md‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1199,11 +1199,11 @@ sequenceDiagram
11991199

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

1202-
| 手法 | 説明 | Poc/Cons |
1203-
| :-------------------- | :----------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------- |
1204-
| 1.multipart/form-data | RFC 2388でも定義された、古くから利用される方式 | ✅️枯れている ⚠️ブラウザ以外のクライアントからは扱いにくい |
1205-
| 2.Base64 | ファイルをBase64形式にエンコードして、通常のフォームデータとして送信する方法 | ✅️通常のリクエストボディでJSON要素の値として設定できるので楽 ⚠️ファイルサイズが大きくなるため、ファイルサイズによってはオーバーヘッドが大きい |
1206-
| 3.署名付きURL | オブジェクトストレージで特定の期間内にのみ有効な一時的なURLを生成し、そのURLを使用してアップロードを行う方法 | ✅️負荷をクラウドサービス側にオフロードできる ⚠️メタデータ系の登録は、別途Web APIを叩く必要があるなど、クライアント側に手続きが発生 |
1202+
| 手法 | 説明 | Poc/Cons |
1203+
| :-------------------- | :----------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
1204+
| 1.multipart/form-data | RFC 2388でも定義された、古くから利用される方式 | ✅️枯れている<br>⚠️ブラウザ以外のクライアントからは扱いにくい |
1205+
| 2.Base64 | ファイルをBase64形式にエンコードして、通常のフォームデータとして送信する方法 | ✅️通常のリクエストボディでJSON要素の値として設定できるので楽<br>⚠️ファイルサイズが大きくなるため、モバイルなどのクライアントでは帯域の観点で懸念 |
1206+
| 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を叩く必要があるなど、クライアント側に手続きが発生 |
12071207

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

@@ -1253,6 +1253,7 @@ sequenceDiagram
12531253
参考:
12541254

12551255
- [署名付きURLを利用したファイルアップロードWeb API設計の勘所 | フューチャー技術ブログ](https://future-architect.github.io/articles/20240705a/)
1256+
- [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/)
12561257
- [S3 バケットを AWS Lambda を使って、ウィルススキャンしてみた | DevelopersIO](https://dev.classmethod.jp/articles/s3-bucket-antivirus-lambda/)
12571258
- [S3のメタデータを用いた攻撃](https://zenn.dev/p0n/articles/3a6139cce9fa17)
12581259

@@ -1262,7 +1263,7 @@ sequenceDiagram
12621263

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

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

0 commit comments

Comments
 (0)