［API］ API仕様書の書き方 #Swift

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などが募集中です。

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

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

［API］ API仕様書の書き方