🔥

API設計書についてChatGPTに色々聞いてみた。

2023/06/04に公開

業務で初めてAPI設計書を書くことになりそうなので
ChatGPTに色々聞いてみました。
初めて、API設計書を書く方の参考になれば幸いです。

そもそもAPI設計書とは

API設計書は、ソフトウェア開発プロジェクトにおいて、API(Application Programming Interface)の設計に関する詳細な情報を提供する文書です。API設計書は、APIの機能、エンドポイント、パラメータ、リクエストとレスポンスの形式、認証方法、エラーハンドリングなど、APIの仕様や動作に関する情報をまとめたものです。
API設計書は、開発者やAPIの利用者に対して、APIの利用方法や動作を明確に伝えるための重要なドキュメントです。

↓以下のような情報が含まれることが一般的です。
1.エンドポイントとHTTPメソッド:APIが提供する各機能やリソースにアクセスするためのエンドポイントと
HTTPメソッド(GET、POST、PUT、DELETEなど)の一覧。

2.パラメータとペイロード:APIリクエストで使用されるパラメータや
ペイロード(リクエストボディ)の形式、データ型、制約などの詳細。

3.レスポンスとエラーハンドリング:APIの応答(レスポンス)の形式、データ型、
ステータスコード、成功と失敗のハンドリング方法に関する情報。

4.認証とセキュリティ:APIへのアクセス制御や認証方法、トークンの生成・管理などのセキュリティ関連の情報。

5.使用例やコードサンプル:開発者や利用者がAPIを使用する際の具体的な使用例やコードサンプル。

エンドポイントとは??

外部からアクセス可能な特定のURL(Uniform Resource Locator)や
URI(Uniform Resource Identifier)のことを指します。
リソースや機能の識別子として機能し、HTTPメソッド(GET、POST、PUT、DELETEなど)と
組み合わせて使用されます。

例)
GET /api/users➡︎ユーザーの一覧を取得するために使用される。
POST /api/users➡︎新しいユーザーの作成に使用される。
GET /api/users/{id}➡︎特定のIDを持つユーザーの詳細情報を取得するために使用される。

パラメーターの種類は??

APIにおけるパラメーターの種類は、使用するAPIやコンテキストに
よって異なりますが、一般的に以下のような種類があります。

1.クエリパラメーター:URLのクエリ文字列として渡されるパラメーターです。主にGETメソッドで使用され、
リソースの絞り込みやフィルタリング、ソート、ページングなどのために使用されます。
例えば、?key1=value1&key2=value2といった形式でURLに追加されます。

■javaで受け取るためのサンプルコード

@GetMapping("/example")
public String exampleMethod(@RequestParam("parameterName") String parameterValue) {
    // parameterValueを使用して必要な処理を行う
    return "response";
}

2.パスパラメーター:URLの一部として直接指定されるパラメーターです。主にURL内の変数や識別子として使用され、特定のリソースやサブリソースを指定するために使用されます。
例えば、/users/{id}のように、{id}がパスパラメーターとして扱われます。

■javaで受け取るためのサンプルコード

@GetMapping("/example/{parameterName}")
public String exampleMethod(@PathVariable("parameterName") String parameterValue) {
    // パスパラメーターの値を使用して必要な処理を行う
    return "response";
}

3.ヘッダーパラメーター(Header Parameters):HTTPリクエストヘッダー内に含まれるパラメーターです。リクエスト全体に関連する情報や認証情報、コンテンツタイプなどを指定するために使用されます。一般的なヘッダーパラメーターには、Content-Type、Authorization、Acceptなどがあります。

■javaで受け取るためのサンプルコード

@GetMapping("/example")
public String exampleMethod(@RequestHeader("HeaderName") String parameterValue) {
    // ヘッダーパラメーターの値を使用して必要な処理を行う
    return "response";
}

4.ボディパラメーター:HTTPリクエストボディに含まれるパラメーターです。主にPOSTやPUTメソッドで使用され、データの作成や更新に使用されます。リクエストボディ内のデータ形式には、JSON、XML、フォームデータ(multipart/form-data)などが一般的です。

■javaで受け取るためのサンプルコード

@PostMapping("/example")
public String exampleMethod(@RequestBody String requestBody) {
    // リクエストボディの値を使用して必要な処理を行う
    return "response";
}

5.フォームパラメーター(Form Parameters):HTMLフォームを介して送信されるパラメーターです。主にWebブラウザでフォームからデータを送信する場合に使用されます。リクエストボディ内にエンコードされ、application/x-www-form-urlencodedやmultipart/form-data形式で送信されます。

■javaで受け取るためのサンプルコード

@PostMapping("/example")
public String exampleMethod(@RequestParam("parameterName") String parameterValue) {
    // フォームパラメーターの値を使用して必要な処理を行う
    return "response";
}

これらは一般的なパラメーターの種類の例ですが、API設計や仕様によっては、
独自のパラメータータイプを使用する場合もあります。

パラメーターの使い分けは??

パラメーターの送り方は、APIの要件やデザインに基づいて使い分ける必要があります。
一般的には、以下のような要素を考慮してパラメーターの送り方を決定します。

1.パラメーターの目的と意味:
パラメーターがどのような情報を表しているかを考慮します。例えば、リソースの一意の識別子である場合は、パスパラメーターを使用することが一般的です。検索クエリやフィルタリング条件である場合は、クエリパラメーターやリクエストボディを使用することが適しています。

2.パラメーターの複雑さとデータのサイズ:
パラメーターが単純な値(文字列、数値など)である場合は、クエリパラメーターやヘッダーパラメーターを使用することが一般的です。一方、複雑なオブジェクトや大量のデータを送信する必要がある場合は、リクエストボディを使用することが適しています。

3.セキュリティとプライバシー:
パラメーターにはセンシティブな情報が含まれる場合、リクエストボディやヘッダーパラメーターの使用を検討することが重要です。これにより、情報がURLやクエリパラメーターに露出しないようにすることができます。

4.プラットフォームの制約:
使用しているプラットフォームやツールによって、特定のパラメーターの送信方法が制限される場合があります。例えば、一部のプラットフォームでは、クエリパラメーターやリクエストボディの制約がある場合があります。

5.慣例と業界のベストプラクティス:
同じドメインや業界で一般的に受け入れられているパラメーターの送り方に従うことも重要です。業界のベストプラクティスや標準に準拠することで、APIの互換性や理解しやすさを向上させることができます。

レスポンスとは??

レスポンス(Response)は、クライアントからのリクエストに対するサーバー側の応答を指します。

1.ステータスコード:レスポンスの状態を表す3桁の数字です。一般的なステータスコードには、200(成功)、400(不正なリクエスト)、404(見つからない)、500(サーバーエラー)などがあります。

2.レスポンスヘッダー:HTTPレスポンスのメタデータや追加情報を含む部分です。例えば、Content-Type(レスポンスのデータ形式)、Content-Length(レスポンスのデータサイズ)、Cache-Control(キャッシュ制御)などが含まれます。

例)

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-cache
X-Custom-Header: Custom Value

3.レスポンスボディ:実際のレスポンスデータを含む部分です。APIからクライアントに送信されるデータや結果がここに含まれます。レスポンスボディの形式は、APIの仕様や要求に応じて異なる場合があります。一般的な形式には、JSON、XML、HTML、画像などがあります。

例)JSON形式

{
  "name": "John Doe",
  "age": 30,
  "email": "johndoe@example.com"
}

Discussion