Skip to content

Commit 0c57457

Browse files
ma91nma91n
authored
OpenAPI Specification 3.0.3規約: WebAPI自体の設計は、Web API設計ガイドラインを参照させる (#226)
* WebAPI設計ガイドラインに寄せる * ファイルアップロード/ダウンロード * fix text
1 parent 40a119f commit 0c57457

File tree

2 files changed

+11
-155
lines changed

2 files changed

+11
-155
lines changed

‎documents/forOpenAPISpecification/OpenAPI_Specification_2.0.md‎

Lines changed: 7 additions & 79 deletions
Original file line numberDiff line numberDiff line change
@@ -43,67 +43,13 @@ head:
4343

4444
::: warning 有志で作成したドキュメントである
4545

46-
- フューチャーアーキテクトには多様なプロジェクトが存在し、それぞれの状況に合わせた開発手法が採用されている。本規約はフューチャーアーキテクトの全ての部署／プロジェクトで利用されているわけではなく、有志が観点を持ち寄って新たに整理したものである。相容れない部分があればその領域を書き換えて利用することを想定している
46+
フューチャーアーキテクトには多様なプロジェクトが存在し、それぞれの状況に合わせた開発手法が採用されている。本規約はフューチャーアーキテクトの全ての部署／プロジェクトで利用されているわけではなく、有志が観点を持ち寄って新たに整理したものである。相容れない部分があればその領域を書き換えて利用することを想定している
4747

4848
:::
4949

5050
# API設計
5151

52-
Web API の設計自体はこの規約の範囲外であるが、簡易的な方針を示す。必要に応じて参考にされたい。
53-
54-
## HTTP メソッド
55-
56-
実現したい操作により、以下のような使い分けを想定する。HEAD（リソースの存在チェック）、GET（参照）、POST（新規作成）、PUT（更新）、PATCH（一部更新）、DELETE（削除）。
57-
58-
## HTTP ステータス
59-
60-
[RFC 7231](https://tools.ietf.org/html/rfc7231#section-6)で定義されているレスポンスステータスコードを利用します。
61-
62-
[RFC9205](https://datatracker.ietf.org/doc/html/rfc9205)（[日本語訳](https://tex2e.github.io/rfc-translater/html/rfc9205.html#section-4.6)）の方針に原則則る。ユースケース別に利用すべき HTTP ステータスコードを記載します。
63-
64-
### 共通
65-
66-
- バリデーションエラー：`400 Bad Request`
67-
- 業務エラー：`400 Bad Request`
68-
- 認証エラー：`401 Unauthorized`
69-
- 認可エラー：`403 Forbidden`
70-
- システムエラー：`500 Internal Server Error`
71-
72-
### GET
73-
74-
- 正常系：`200 OK`
75-
- 検索系 API で結果 0 件の場合も、 `200 OK` を返すとする
76-
- パスキー検索系 API で対象リソースが存在しないエラー：`404 Not Found`
77-
78-
### POST
79-
80-
- 正常系（同期）：`201 Created`
81-
- 正常系（非同期）：`202 Accepted`
82-
- 一意制約違反エラー：`409 Conflict`
83-
- 親リソースが存在しないエラー：`404 Not Found`
84-
85-
### PUT
86-
87-
- 正常系（同期）：`200 OK`
88-
- 正常系（非同期）：`202 Accepted`
89-
- 対象リソースが存在しないエラー：`404 Not Found`
90-
91-
### DELETE
92-
93-
- 正常系：`204 No Content`
94-
- もし、削除した項目の情報を応答する場合は `200 OK` とする
95-
- 対象リソースが存在しないエラー：`404 Not Found`
96-
97-
## API バージョン管理
98-
99-
- /v1, /v2 といったパスで表現する
100-
- 型名変更、必須パラメータの追加、レスポンスの桁数変更、などをするときはバージョンを上げることを検討する
101-
102-
## パラメータの命名
103-
104-
boolean 型である場合、 `[a-zA-Z0-9-_]+_flag` という命名は非推奨とする。
105-
106-
`is_[a-zA-Z0-9-_]+` や `has_[a-zA-Z0-9-_]+` などの命名を代わりに検討する
52+
Web API の設計自体は、[Web API設計ガイドライン | Future Enterprise Arch Guidelines](https://future-architect.github.io/arch-guidelines/documents/forWebAPI/web_api_guidelines.html)を参考にすること。
10753

10854
# YAMLファイルフォーマット
10955

@@ -936,25 +882,9 @@ remind_time:
936882
pattern: "^(2[0-3]|[01][0-9]):([0-5][0-9])$"
937883
```
938884

939-
# ファイルアップロード
940-
941-
Web API におけるファイルアップロードのよく利用される実装手段は、大きく分けて以下の 3 手法に分類できます
885+
## ファイルアップロード
942886

943-
1. ファイルのコンテンツを Base64 などにエンコードして、JSON の項目として設定し、リクエストボディで送る
944-
- メリット: 通常の JSON を扱うのとほぼ変わらないため楽。サムネイルなど限定されたユースケースの場合に向く
945-
- デメリット: 巨大なファイルを扱う場合などサーバリソース負荷が懸念。Base64 に変換する分 CPU 負荷は余計にかかる。ペイロードが膨れるためモバイルなどのクライアントでは帯域利用での懸念がある
946-
2. multipart/form-data ファイルを送信する
947-
- メリット: ファイルを Base64 に変換するといった作業が不要
948-
- デメリット: ブラウザ以外のクライアントにとって手間がかかる
949-
3. アップロード用に用いる、オブジェクトストレージの Signed URL を発行し、クライアントから直接ファイルをアップロードしてもらう
950-
- 次の流れを想定（Signed URL を取得 -> ファイルアップロード -> ファイルに紐づかせるキーや属性情報などを登録）
951-
- 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)ため、許容するファイルサイズによってはこの手法一択となる
952-
- メリット: オブジェクトストレージの可用性・信頼性を享受できる
953-
- デメリット: アップロードするために複数の API エンドポイント呼び出しが必要なため、煩雑である
954-
- 2023 年 6 月に AWS ブログでこの方式について解説した記事が出たので、詳細は参照ください。
955-
- [https://aws.amazon.com/jp/blogs/news/large-size-files-transferring-by-serverless-s3presignedurl-and-clientside-javascript/](https://aws.amazon.com/jp/blogs/news/large-size-files-transferring-by-serverless-s3presignedurl-and-clientside-javascript/)
956-
957-
本規約でファイルアップロードについて上記の 3. Signed URL を推奨する。API 呼び出しとしては次のようなフローとする。
887+
[Web API設計ガイドライン>ファイル連携>ファイルアップロード](https://future-architect.github.io/arch-guidelines/documents/forWebAPI/web_api_guidelines.html#%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB%E3%82%A2%E3%83%83%E3%83%95%E3%82%9A%E3%83%AD%E3%83%BC%E3%83%88%E3%82%99) で推奨された「署名付きURL」を用いた手法を採用する場合、次のようなフローとする。
958888

959889
```mermaid
960890
sequenceDiagram
@@ -965,7 +895,7 @@ participant C as オブジェクトストレージ
965895
A->>B: ①アップロード先URL取得
966896
B->>C: Signed URL発行
967897
C-->>B: Signed URL
968-
B-->>A: アップロードURL、受付ID（加えて、アップロードで指定したいHTTP Methodや必要なリクエストヘッダーがあれば応答の項目に追加する）
898+
B-->>A: アップロードURL、受付ID（加えて、アップロードで指定したいHTTP Methodや必要なリクエストヘッダがあれば応答の項目に追加する）
969899
970900
A->>C: ②ファイルアップロード
971901
@@ -977,11 +907,9 @@ A->>B: ③ファイルアップロード完了(受付ID、キー、属性)
977907

978908
上記どちらのケースも OpenAPI 定義としてはシンプルであるため、記述例は割愛する。
979909

980-
# ファイルダウンロード
981-
982-
ファイルアップロードと同様、オブジェクトストレージの Signed URL 経由を経由してのダウンロードさせる手法を推奨する。Web API としてはオブジェクトストレージにダウンロード用のファイルを書き込み、クライアントが取得するための Signed URL をレスポンスの JSON 項目に渡す方式である。
910+
## ファイルダウンロード
983911

984-
もし、サムネイルやアイコン画像など、ファイル容量がごく小さい場合は Base64 にエンコードして JSON に埋め込んで渡しても良い。線引をどこに設置するかは本規約で定義しない。
912+
[Web API設計ガイドライン>ファイル連携>ファイルダウンロード](https://future-architect.github.io/arch-guidelines/documents/forWebAPI/web_api_guidelines.html#%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB%E3%82%BF%E3%82%99%E3%82%A6%E3%83%B3%E3%83%AD%E3%83%BC%E3%83%88%E3%82%99) で推奨された方法は、Signed URL をレスポンスの JSON 項目に渡すか、ファイル容量がごく小さい場合に限り Base64 にエンコードして JSON に埋め込んで渡すかの2つである。
985913

986914
どちらのケースも OpenAPI 定義としてはシンプルであるため、記述例は割愛する。
987915

‎documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md‎

Lines changed: 4 additions & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -44,67 +44,13 @@ head:
4444

4545
::: warning 有志で作成したドキュメントである
4646

47-
- フューチャーアーキテクトには多様なプロジェクトが存在し、それぞれの状況に合わせた開発手法が採用されている。本規約はフューチャーアーキテクトの全ての部署／プロジェクトで利用されているわけではなく、有志が観点を持ち寄って新たに整理したものである。相容れない部分があればその領域を書き換えて利用することを想定している
47+
フューチャーアーキテクトには多様なプロジェクトが存在し、それぞれの状況に合わせた開発手法が採用されている。本規約はフューチャーアーキテクトの全ての部署／プロジェクトで利用されているわけではなく、有志が観点を持ち寄って新たに整理したものである。相容れない部分があればその領域を書き換えて利用することを想定している
4848

4949
:::
5050

5151
# API設計
5252

53-
Web API の設計自体はこの規約の範囲外であるが、簡易的な方針を示す。必要に応じて参考にされたい。
54-
55-
## HTTP メソッド
56-
57-
実現したい操作により、以下のような使い分けを想定する。HEAD（リソースの存在チェック）、GET（参照）、POST（新規作成）、PUT（更新）、PATCH（一部更新）、DELETE（削除）。
58-
59-
## HTTP ステータス
60-
61-
[RFC 7231](https://tools.ietf.org/html/rfc7231#section-6)で定義されているレスポンスステータスコードを利用します。
62-
63-
[RFC9205](https://datatracker.ietf.org/doc/html/rfc9205)（[日本語訳](https://tex2e.github.io/rfc-translater/html/rfc9205.html#section-4.6)）の方針に原則則る。ユースケース別に利用すべき HTTP ステータスコードを記載します。
64-
65-
### 共通
66-
67-
- バリデーションエラー：`400 Bad Request`
68-
- 業務エラー：`400 Bad Request`
69-
- 認証エラー：`401 Unauthorized`
70-
- 認可エラー：`403 Forbidden`
71-
- システムエラー：`500 Internal Server Error`
72-
73-
### GET
74-
75-
- 正常系：`200 OK`
76-
- 検索系 API で結果 0 件の場合も、 `200 OK` を返すとする
77-
- パスキー検索系 API で対象リソースが存在しないエラー：`404 Not Found`
78-
79-
### POST
80-
81-
- 正常系（同期）：`201 Created`
82-
- 正常系（非同期）：`202 Accepted`
83-
- 一意制約違反エラー：`409 Conflict`
84-
- 親リソースが存在しないエラー：`404 Not Found`
85-
86-
### PUT
87-
88-
- 正常系（同期）：`200 OK`
89-
- 正常系（非同期）：`202 Accepted`
90-
- 対象リソースが存在しないエラー：`404 Not Found`
91-
92-
### DELETE
93-
94-
- 正常系：`204 No Content`
95-
- もし、削除した項目の情報を応答する場合は `200 OK` とする
96-
- 対象リソースが存在しないエラー：`404 Not Found`
97-
98-
## API バージョン管理
99-
100-
- /v1, /v2 といったパスで表現する
101-
- 型名変更、必須パラメータの追加、レスポンスの桁数変更、などをするときはバージョンを上げることを検討する
102-
103-
## パラメータの命名
104-
105-
boolean 型である場合、 `[a-zA-Z0-9-_]+_flag` という命名は非推奨とする。
106-
107-
`is_[a-zA-Z0-9-_]+` や `has_[a-zA-Z0-9-_]+` などの命名を代わりに検討する
53+
Web API の設計自体は、[Web API設計ガイドライン | Future Enterprise Arch Guidelines](https://future-architect.github.io/arch-guidelines/documents/forWebAPI/web_api_guidelines.html)を参考にすること。
10854

10955
# YAMLファイルフォーマット
11056

@@ -1107,23 +1053,7 @@ OpenAPI ドキュメントを作成する上でのファイルのアップロー
11071053

11081054
## ファイルアップロード
11091055

1110-
Web API におけるファイルアップロードのよく利用される実装手段は、大きく分けて以下の 3 手法に分類できる。
1111-
1112-
1. ファイルのコンテンツを Base64 などにエンコードして、JSON の項目として設定し、リクエストボディで送る
1113-
- メリット: 通常の JSON を扱うのとほぼ変わらないため楽。サムネイルなど限定されたユースケースの場合に向く
1114-
- デメリット: 巨大なファイルを扱う場合などサーバリソース負荷が懸念。Base64 に変換する分 CPU 負荷は余計にかかる。ペイロードが膨れるためモバイルなどのクライアントでは帯域利用での懸念がある
1115-
2. multipart/form-data ファイルを送信する
1116-
- メリット: ファイルを Base64 に変換するといった作業が不要
1117-
- デメリット: ブラウザ以外のクライアントにとって手間がかかる
1118-
3. アップロード用に用いる、オブジェクトストレージの Signed URL を発行し、クライアントから直接ファイルをアップロードしてもらう
1119-
- 次の流れを想定（Signed URL を取得 -> ファイルアップロード -> ファイルに紐づかせるキーや属性情報などを登録）
1120-
- 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)ため、許容するファイルサイズによってはこの手法一択となる
1121-
- メリット: オブジェクトストレージの可用性・信頼性を享受できる
1122-
- デメリット: アップロードするために複数の API エンドポイント呼び出しが必要なため、煩雑である
1123-
- 2023 年 6 月に AWS ブログでこの方式について解説した記事が出たので、詳細は参照ください
1124-
- [https://aws.amazon.com/jp/blogs/news/large-size-files-transferring-by-serverless-s3presignedurl-and-clientside-javascript/](https://aws.amazon.com/jp/blogs/news/large-size-files-transferring-by-serverless-s3presignedurl-and-clientside-javascript/)
1125-
1126-
本規約でファイルアップロードについて上記の 3. Signed URL を推奨する。API 呼び出しとしては次のようなフローとする。
1056+
[Web API設計ガイドライン>ファイル連携>ファイルアップロード](https://future-architect.github.io/arch-guidelines/documents/forWebAPI/web_api_guidelines.html#%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB%E3%82%A2%E3%83%83%E3%83%95%E3%82%9A%E3%83%AD%E3%83%BC%E3%83%88%E3%82%99) で推奨された「署名付きURL」を用いた手法を採用する場合、次のようなフローとする。
11271057

11281058
```mermaid
11291059
sequenceDiagram
@@ -1148,9 +1078,7 @@ A->>B: ③ファイルアップロード完了(受付ID、キー、属性)
11481078

11491079
## ファイルダウンロード
11501080

1151-
ファイルアップロードと同様、オブジェクトストレージの Signed URL 経由を経由してのダウンロードさせる手法を推奨する。Web API としてはオブジェクトストレージにダウンロード用のファイルを書き込み、クライアントが取得するための Signed URL をレスポンスの JSON 項目に渡す方式である。
1152-
1153-
もし、サムネイルやアイコン画像など、ファイル容量がごく小さい場合は Base64 にエンコードして JSON に埋め込んで渡しても良い。線引をどこに設置するかは本規約で定義しない。
1081+
[Web API設計ガイドライン>ファイル連携>ファイルダウンロード](https://future-architect.github.io/arch-guidelines/documents/forWebAPI/web_api_guidelines.html#%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB%E3%82%BF%E3%82%99%E3%82%A6%E3%83%B3%E3%83%AD%E3%83%BC%E3%83%88%E3%82%99) で推奨された方法は、Signed URL をレスポンスの JSON 項目に渡すか、ファイル容量がごく小さい場合に限り Base64 にエンコードして JSON に埋め込んで渡すかの2つである。
11541082

11551083
どちらのケースも OpenAPI 定義としてはシンプルであるため、記述例は割愛する。
11561084

0 commit comments

Comments
 (0)