【Django】掲示板アプリの Web API 仕様【参考】

このページにはプロモーションが含まれています

このページでは、下記ページの掲示板アプリで Web API を公開するで開発する API の仕様について解説していきます。

【Django入門１９】Web APIを開発

開発する API は下記の７つであり、これらの仕様について解説していきます。

ログイン API
ログアウト API
コメントの投稿 API
コメントの一覧取得 API
コメントの詳細取得 API
コメントの更新 API
コメントの削除 API

Contents

ログイン API
ログアウト API
コメントの投稿 API
コメントの一覧取得 API
コメントの詳細取得 API
コメントの更新 API
コメントの削除 API

まずは、ログイン API の仕様について解説していきます。

ログイン API：URL とメソッド

ログイン API は、下記の URL・メソッドの HTTP リクエストを送信することで実行することができます。

URL：/api/login/
メソッド：POST

ログイン API：リクエストのボディ

ログイン API を実行する際には、HTTP リクエストのボディで登録済みのユーザーの情報を指定するようにしてください。具体的には、下記のようなフィールドを持つ JSON 形式のボディでユーザー情報を指定してください。

*Name ( 必須)**	Type	Description
`username` *	文字列	ユーザー名
`password` *	文字列	パスワード

まだユーザー登録を行っていない場合は、下記ページでウェブブラウザからユーザー登録を実施し、その時に登録した情報をボディにセットしてログイン API を実行するようにしてください。

http://localhost:8000/forum/register/

ログイン API：クエリパラメーター

ログイン API に指定可能なクエリパラーメーターはありません。

ログイン API：ステータスコード

ログイン API は、ログインの成功 / 失敗に応じて下記をステータスコードとする HTTP レスポンスを返却します。

成功時：200
失敗時：401

ログイン API：レスポンスのボディ

ログイン API は、ログインの成功 / 失敗に応じて下記をボディとする HTTP レスポンスを返却します。ボディのデータフォーマットは JSON です。

成功時：{'success': 'ログインに成功しました'}
失敗時：{'detail': 'ログインに失敗しました'}

ログイン API：認証用のデータ

ログインに成功した場合、ログイン API は「セッション ID を含むクッキー」をセットした HTTP レスポンスを返却します。このクッキーをセットした HTTP リクエストを送信することで、セッション認証を実施する API を実行することができるようになります。

ログアウト API

まずは、ログアウト API の仕様について解説していきます。

ログアウト API：URL とメソッド

ログアウト API は、下記の URL・メソッドの HTTP リクエストを送信することで実行することができます。

URL：/api/logout/
メソッド：POST

ログアウト API：リクエストのボディ

ログアウト API を実行する際に送信する HTTP リクエストにボディは不要です。ボディを含む HTTP リクエストが送信されて来たとしても、ウェブアプリはボディを無視することになります。

ログアウト API：クエリパラメーター

ログアウト API に指定可能なクエリパラーメーターはありません。

ログアウト API：ステータスコード

ログアウト API は、下記をステータスコードとする HTTP レスポンスを返却します。

成功時：200

ログアウト API：レスポンスのボディ

ログアウト API は、下記をボディとする HTTP レスポンスを返却します。ボディのデータフォーマットは JSON です。

成功時：{'success': 'ログアウトに成功しました'}

コメントの投稿 API

次は、コメントの投稿 API の仕様について解説していきます。

コメントの投稿 API：URL とメソッド

コメントの投稿 API は、下記の URL・メソッドの HTTP リクエストを送信することで実行することができます。

URL：/api/comments/
メソッド：POST

コメントの投稿 API：リクエストのボディ

コメントの投稿 API 実行時には、HTTP リクエストのボディで投稿するコメントの本文を指定する必要があります。具体的には、下記のようなフィールドを持つ JSON 形式のボディでコメントの本文を指定してください。

*Name ( 必須)**	Type	Description
`text` *	文字列（文字数：`1` ～ `256`）	コメントの本文

コメントの投稿者は、クッキーにセットされたセッション ID に応じて自動的に設定されます。また、コメントの投稿日時に関しても、API を実行したタイミングに応じて自動的に設定されます。

コメントの投稿 API：クエリパラメーター

コメントの投稿取得 API に指定可能なクエリパラーメーターはありません。

コメントの投稿 API：ステータスコード

コメントの投稿 API は、コメントの投稿の成功 / 失敗、さらには失敗した原因に応じて下記をステータスコードとする HTTP レスポンスを返却します。

成功時：201
失敗時：
- 400 (ボディが不正)
- 401 (認証に失敗)

コメントの投稿 API：レスポンスのボディ

コメントの投稿 API は、コメントの投稿に成功した場合、投稿したコメントのレコードの情報をボディとする HTTP レスポンスを返却します。具体的には、下記フィールドを持つボディの HTTP レスポンスを返却します。ボディのデータフォーマットは JSON です。

Name	Type	Description
`id`	整数	コメントの ID
`user`	文字列	投稿者名
`text`	文字列	本文
`date`	文字列（ISO 8601 形式）	投稿日時

また、コメントの投稿に失敗した場合、コメントの投稿 API は下記フィールドを持つボディの HTTP レスポンスを返却します。ボディのデータフォーマットは JSON です。

Name	Type	Description
`detail`	文字列	エラーの原因

コメントの投稿 API：認証

コメントの投稿 API を利用できるのは、セッション認証に成功した場合、すなわち既にログインに成功している場合のみとなります。

コメントの投稿 API を利用する場合は、ログイン API で示したログイン API で事前にログインをしてセッション ID を含むクッキーを取得し、そのクッキーをセットした HTTP リクエストを送信する必要があります。

コメントの一覧取得 API

次は、コメントの一覧取得 API の仕様について解説していきます。

コメントの一覧取得 API：URL とメソッド

コメントの一覧取得 API は、下記の URL・メソッドの HTTP リクエストを送信することで実行することができます。

URL：/api/comments/
メソッド：GET

コメントの一覧取得 API：リクエストのボディ

コメントの一覧取得 API 実行時には、HTTP リクエストのボディは不要です。

コメントの一覧取得 API：クエリパラメーター

コメント一覧取得 API では、基本的には投稿済みの全コメントの取得が行われることになります。

ただし、下記のクエリパラメーターを指定することで、取得するコメントの範囲を ID で指定することが可能です。これらは、どちらか一方のみを指定することも可能ですし、両方指定することも可能です。

Key Name	Type	Description
`min_id`	整数	取得するコメントの範囲（開始 ID）
`max_id`	整数	取得するコメントの範囲（終了 ID）

コメントの一覧取得 API：ステータスコード

コメントの一覧取得 API は、コメントの取得の成功 / 失敗、さらには失敗した原因に応じて下記をステータスコードとする HTTP レスポンスを返却します。

成功時：200
失敗時：
- 401 (認証に失敗)

コメントの一覧取得 API：レスポンスのボディ

コメントの一覧取得 API は、コメントの取得に成功した場合は、配列をボディとする HTTP レスポンスを返却します。そして、その配列の各要素は、下記フィールドを持つオブジェクトとなります。ボディのデータフォーマットは JSON です。

Name	Type	Description
`id`	整数	コメントの ID
`user`	文字列	投稿者名
`text`	文字列	本文
`date`	文字列（ISO 8601 形式）	投稿日時

また、コメントの一覧の取得に失敗した場合、コメントの一覧取得 API は、下記フィールドを持つボディの HTTP レスポンスを返却します。ボディのデータフォーマットは JSON です。

Name	Type	Description
`detail`	文字列	エラーの原因

コメントの一覧取得 API：認証

コメントの一覧取得 API を利用できるのは、セッション認証に成功した場合、すなわち既にログインに成功している場合のみとなります。

コメントの一覧取得 API を利用する場合は、ログイン API で示したログイン API で事前にログインをしてセッション ID を含むクッキーを取得し、そのクッキーをセットした HTTP リクエストを送信する必要があります。

コメントの詳細取得 API

次は、コメントの詳細取得 API の仕様について解説していきます。

コメントの詳細取得 API：URL とメソッド

コメントの詳細取得 API は、下記の URL・メソッドの HTTP リクエストを送信することで実行することができます。{id} 部分で、取得するコメントの ID を指定する必要があります。

URL：/api/comments/{id}/
メソッド：GET

コメントの詳細取得 API：リクエストのボディ

コメントの一覧取得 API 実行時には、HTTP リクエストのボディは不要です。

コメントの詳細取得 API：クエリパラメーター

コメントの詳細取得 API に指定可能なクエリパラーメーターはありません。

コメントの詳細取得 API：ステータスコード

コメントの詳細取得 API は、コメントの取得の成功 / 失敗、さらには失敗した原因に応じて下記をステータスコードとする HTTP レスポンスを返却します。

成功時：200
失敗時：
- 401 (認証に失敗)
- 404 (URL で指定された ID のコメントが存在しない)

コメントの詳細取得 API：レスポンスのボディ

コメントの詳細取得 API は、コメントの取得に成功した場合、下記フィールドを持つオブジェクトをボディとする HTTP レスポンスを返却します。ボディのデータフォーマットは JSON です。

Name	Type	Description
`id`	整数	コメントの ID
`user`	文字列	投稿者名
`text`	文字列	本文
`date`	文字列（ISO 8601 形式）	投稿日時

また、コメントの一覧の取得に失敗した場合、コメントの詳細取得 API は、下記フィールドを持つボディの HTTP レスポンスを返却します。ボディのデータフォーマットは JSON です。

Name	Type	Description
`detail`	文字列	エラーの原因

コメントの詳細取得 API：認証

コメントの詳細取得 API を利用できるのは、セッション認証に成功した場合、すなわち既にログインに成功している場合のみとなります。

コメントの詳細取得 API を利用する場合は、ログイン API で示したログイン API で事前にログインをしてセッション ID を含むクッキーを取得し、そのクッキーをセットした HTTP リクエストを送信する必要があります。

コメントの更新 API

次は、コメントの更新 API の仕様について解説していきます。

コメントの更新 API：URL とメソッド

コメントの更新 API は、下記の URL・メソッドの HTTP リクエストを送信することで実行することができます。{id} 部分で、更新するコメントの ID を指定する必要があります。

URL：/api/comments/{id}/
メソッド：PATCH

コメントの更新 API：リクエストのボディ

コメントの更新 API 実行時には、HTTP リクエストのボディで更新後のコメントの本文を指定する必要があります。具体的には、下記のようなフィールドを持つ JSON 形式のボディでコメントの本文を指定してください。

*Name ( 必須)**	Type	Description
`text` *	文字列（文字数：`1` ～ `256`）	コメントの本文

コメントの更新 API：クエリパラメーター

コメントの更新 API に指定可能なクエリパラーメーターはありません。

コメントの更新 API：ステータスコード

コメントの更新 API は、コメントの更新の成功 / 失敗、さらには失敗した原因に応じて下記をステータスコードとする HTTP レスポンスを返却します。

成功時：200
失敗時：
- 400 (リクエストのボディが不正)
- 401 (認証に失敗)
- 403 (権限がない [他のユーザーが投稿したコメントの更新])
- 404 (URL で指定された ID のコメントが存在しない)

コメントの更新 API：レスポンスのボディ

コメントの更新 API は、コメントの更新に成功した場合、更新したコメントのレコードの情報をボディとする HTTP レスポンスを返却します。具体的には、下記フィールドを持つボディの HTTP レスポンスを返却します。ボディのデータフォーマットは JSON です。

Name	Type	Description
`id`	整数	コメントの ID
`user`	文字列	投稿者名
`text`	文字列	本文
`date`	文字列（ISO 8601 形式）	投稿日時