［API］ 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日
更新日 2022年02月23日
確認日 170,027 views

• 2020/12/01 100,000 view 突破しました
• 2023/02/23 170,000 view 突破しました

こちらの記事 100,000 views 突破しました
２０万ももしかしたら年内に診てもらえるかも、、、？がんばります。

今回は少し、より現場でも使えるような情報を更新してみました。

---

関連記事

About - サンストライプ

---

制作チーム：サンストライプ

http://sunstripe.main.jp/
サンストライプについて
制作チームのサンストライプのコンテンツについては以下の通り

月3回のコンテンツをリリースしています。
参加者は、プログラマーやデザイナー、イラストレーター、声優やVTuberなどが募集中です。

関連プロジェクト・支援団体

• 地域情報 THEメディア
  地域活性化をテーマに様々な情報を発信しています。

• ワークショップ情報 THEワークショップ
  多様化の時代に向けて他者理解を鍛えることを目的としています。

• 青空プログラミング　　- 月１だけのプログラミング学習塾
  プログラミングワークショップ・ウェブ塾の開講！！！
  様々なテーマでプログラミングに取り組むことができます。

• プログラミングラボ - オンラインプログラミング研究チーム
  ３ヶ月にコンテンツを作成するAIを活用した実践形式の開発

• Vの輪 バーチャル促進イベント企画・開発 - メタバースサークル
  メタバースに向けた企画やイベントの実施およびメタバースとリアルの融合を目指してます。

• スクランブルスクール バーチャル学校 - バーチャル学校
  VTuberに向けた情報発信とバーチャルイベントの企画と実施およびバーチャル番組制作

その他協力応援 / 支援者の集い

• トラストヒューマン - 私たちは何よりも信頼､人と考えてます｡
  人材戦略パートナーとして、コンサルティングやクリエイティブの両角度からサポートをしています。
• キャリア教育事業 - 広域学習支援プラットフォーム『のびのび日和』