API仕様書の書き方
API仕様書について
本API仕様書では、提供するAPIの機能や使い方をわかりやすく整理しています。APIはシステム間のデータ連携や機能拡張を可能にする重要なツールであり、この仕様書を通じて以下の内容を明確にしています。
-
API一覧
どのような機能がAPIとして提供されているかを簡単に確認できます。 -
詳細な使い方
リクエストやレスポンスのフォーマット、入力パラメータや出力データの仕様について具体的に記載しています。 -
セキュリティと注意点
安全かつ効率的にAPIを利用するためのポイントをまとめています。
このAPI仕様書の書き方を活用することで、APIを正しく理解し、スムーズにシステムやアプリケーションへ統合することが可能になります。それぞれのAPIについて、概要や具体的な使い方を簡潔に説明しているため、初めての方でも安心してお使いいただけます。
API一覧
以下に、提供するAPIの一覧を記載しています。それぞれのAPIがどのような機能を提供するのか、概要を把握するためにご利用ください。
API仕様書について
本仕様書は、システム間の連携や機能拡張を円滑に実現するために提供する API（Application Programming Interface） の詳細な設計情報をまとめたものです。
APIは、データのやり取りや機能の提供を通じて、アプリケーションやサービス間の橋渡しを担います。本仕様書では、開発者がスムーズにAPIを活用できるよう、リクエストやレスポンスの形式、パラメータ仕様、セキュリティ要件を含めた明確なガイドラインを提供しています。
想定読者
- 開発者（APIを実装・利用するエンジニア）
- プロジェクトマネージャー（システム要件を把握するため）
- QAエンジニア（テストケース作成の参考資料として）
本仕様書の目的
-
API利用者が迅速に開発を進められる環境を提供
各APIの機能、入力/出力フォーマット、例外処理を網羅的に記載しています。 -
システム連携の透明性を高める
異なるチーム間や外部ベンダーとの連携時にも、一貫した設計を参照できるように設計されています。 -
運用・保守性を向上させる
長期的な運用を見据え、変更に強い設計を目指しています。
これから記載される内容を通じて、APIが果たす役割を深く理解し、各自のプロジェクトに適切に活用いただけることを目指しています。どうぞご活用ください。
| API一覧 |
|---|
| No. | API機能No. | 種別 | API名 | 機能概要 |
|---|---|---|---|---|
| 0 | HOGE-000 | API | 例 | 例 |
| 1 | HOGE-001 | API | ほげほげ | ほげほげする |
| 2 | HOGE-002 | API | ほげほげ | ほげほげする |
| 3 | HOGE-003 | API | ほげほげ | ほげほげする |
＊ No.の付け方はプロジェクトによって決めておくと後で何のプロジェクトなのか、また共通のAPIなのかなどもわかるようにしておくといいかもですね。
## HOGE-000
＊ 例としてプロフィールに関してのAPIとしてあげる
| API機能No. | HOGE-000 |
|---|---|
| API名 | プロフィールデータの取得 |
| 更新日/更新者 | 20XX.XX.XX 担当者名 |
| 概要 | プロフィールに関してのAPI |
| METHOD | GET or POST |
POSTの例
| 入力 | |
|---|---|
| アクセスURI | api/profile/search |
| POSTデータ（JSON形式） |
|---|
Header設定
| JSON Key | 型 | サイズ | 必須 | 暗号化 | 検索条件 | 値の説明 |
|---|---|---|---|---|---|---|
| Authorization | String | ○ | ＊ | JSON形式で受け取る ＄HOGE_API_KEY | ||
| Content-Type | String | ○ | JSON形式で受け取る場合、例 application/json |
＊ セキュリティを上げる上での注意点、トークンやパスワードをチームやプロジェクト内で管理する際に、暗号化欠けたものを用いることが現場では多い。ここに関しては、要件定義や情報の制限をチームやプロジェクト内で確認するようにしましょう。
Data設定
| JSON Key | 型 | サイズ | 必須 | 暗号化 | 検索条件 | 値の説明 |
|---|---|---|---|---|---|---|
| profile_id | 文字列 | 30 | ○ | 完全一致 | プロフィールID｜ユーザーIDなど | |
| max_page | Int | 10 | 完全一致 | 最大ページ数｜取得内容が多い場合やネットワークの容量を制限する場合に必要になります。 | ||
| その他の例 | ||||||
| name | 文字列 | 30 | ○ | 表示する名前 絵文字も可能 | ||
| description | 文字列 | 200 | ○ | 表示するプロフィール 絵文字も可能 | ||
| ・・・ | ||||||
| hoge_date | 文字列 | 10 | ○ | 完全一致 | 日付 日付形式（YYYY/MM/DD） |
curl https://hogehoge.com/api/{version}/profile/search \
-H 'Content-Type: application/json' \
-H "Authorization: $HOGE_API_KEY" \
-d '{
"profile_id": "HOGEHOGEHOGE",
"max_page": 3
}'
data 型の場合は、以下のような書かれ方をします
例 multipart/form-data
curl https://hogehoge.com/api/{version}/profile/edits \
-H "Authorization: $HOGE_API_KEY" \
-F name="ほげほげ" \
-F description="ほげほげの説明" \
-F profile_id="hogehoge" \
// トークンなどのパスワードを定義しておく
let HOGE_API_KEY = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
/// *注意＊ パスワードや設定する場合セキュリティーや決め事はここで確認しておくこと。
// JSON形式のHeaderを作成する
let headers = [
"Authorization": "\(HOGE_API_KEY)"
"Content-Type": "application/json"
]
// JSON形式のHeaderを作成する
let parameters: [String: Any] = [
"profile_id": "HOGEHOGEHOGE", // String
"max_page": 3 // Int
]
// URLRequestにHeaderを設定する
var request = URLRequest(url: url)
request.allHTTPHeaderFields = headers
request.httpBody = try? JSONSerialization.data(withJSONObject: parameters)
この例では、Content-Typeがapplication/jsonであるJSON形式のHeaderを作成し、URLRequestに設定しています。HTTP通信のHeaderにJSON形式を指定する場合、Content-Typeをapplication/jsonにすることが一般的です。また、セキュリティを上げる時にトークンなどを設定しておくことが今後の鍵になります。情報伝達の際には、セキュリティーのことも考えておくことがよいです。なお、上記の例は、Swiftの場合ですが、他の言語でも同様にHeaderを設定することができます。
＃ 受け取り側の場合は、以下の通り
| 出力 |
|---|
| 返却データ（JSON形式） |
|---|
| JSON Key | 型 | サイズ | 必須 | 繰返 | 値の説明 |
|---|---|---|---|---|---|
| status | 数値 | ○ | 処理結果ステータス | ||
| messages | 配列 | エラーメッセージは配列 | |||
| result | 配列 | 検索結果は配列 | |||
| profile_id | 数値 | 30 | ユーザーのプロフィールID | ||
| user_type | 数値 | 1 | ユーザーのタイプ番号 | ||
| user_name | 文字列 | 30 | ユーザーの名前 | ||
| user_description | 文字列 | 200 | ユーザーの詳細 | ||
| user_display_date | 文字列 | 10 | 表示日時 日付形式（YYYY/MM/DD） |
＊ JSON Keyのインデントを合わせることでどこのそうなのかを把握できるようにしましょう
let task = URLSession.shared.dataTask(with: request) { (data, response, error) in
if let error = error {
print("エラー: \(error.localizedDescription)")
return
}
guard let data = data else {
print("データがありませんでした")
return
}
do {
/// JSON型のデータをdictionary型（[String: Any]）に変換してみる
if let json = try JSONSerialization.jsonObject(with: data, options: []) as? [String: Any] {
print(json)
} else {
print("JSON変換が失敗しました")
}
} catch {
print("JSON パースに失敗しました エラー: \(error.localizedDescription)")
}
}
task.resume()
| メッセージ |
|---|
処理結果ステータスコード例
| ステータス | 共個 | メッセージ内容(messages) |
|---|---|---|
| 1 | 個別 | 検索結果が1件以上の場合 => メッセージなし 検索結果 0 件の場合 => ["該当する情報はありませんでした。", "その他、設定するProfile IDが違います。"] |
| 200 | 共通 | 成功 |
| 300 | 個別 | ["○○○○は必須項目です", "△△△△は数値ではありません"] ※ |
| 404 | 個別 | ["URLが正しくありません、URLの確認してください。"] |
| 500 | 個別 | ["サーバで認証エラーになりました。"] |
| 999 | 共通 | ["システムエラーが発生しました。"] |
※ 項目毎のエラー内容を返却すると良いと思います。
投稿情報
投稿日 2016年06月09日
最終更新日 2023年02月23日
- 2020/12/01 100,000 views 突破しました
- 2023/02/23 170,000 views 突破しました
- 2023/02/23 210,000 views 突破しました
今回は少し、より現場でも使えるような情報を更新してみました。
関連記事
About - サンストライプ
制作チーム：サンストライプ
http://sunstripe.main.jp/
サンストライプについて
制作チームのサンストライプのコンテンツについては以下の通り
月3回のコンテンツをリリースしています。
参加者は、プログラマーやデザイナー、イラストレーター、声優やVTuberなどが募集中です。
関連プロジェクト・支援団体
-
地域情報 THEメディア
地域活性化をテーマに様々な情報を発信しています。 -
ワークショップ情報 THEワークショップ
多様化の時代に向けて他者理解を鍛えることを目的としています。 -
青空プログラミング - 月１だけのプログラミング学習塾
プログラミングワークショップ・ウェブ塾の開講！！！
様々なテーマでプログラミングに取り組むことができます。 -
プログラミングラボ - オンラインプログラミング研究チーム
３ヶ月にコンテンツを作成するAIを活用した実践形式の開発 -
Vの輪 バーチャル促進イベント企画・開発 - メタバースサークル
メタバースに向けた企画やイベントの実施およびメタバースとリアルの融合を目指してます。 -
スクランブルスクール バーチャル学校 - バーチャル学校
VTuberに向けた情報発信とバーチャルイベントの企画と実施およびバーチャル番組制作
その他協力応援 / 支援者の集い
-
トラストヒューマン - 私たちは何よりも信頼､人と考えてます｡
人材戦略パートナーとして、コンサルティングやクリエイティブの両角度からサポートをしています。 - キャリア教育事業 - 広域学習支援プラットフォーム『のびのび日和』