LoginSignup
533
513

More than 1 year has passed since last update.

[API] API仕様書の書き方

Last updated at Posted at 2016-06-09

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 突破しました
20万ももしかしたら年内に診てもらえるかも、、、?がんばります。

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


関連記事

About - サンストライプ


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

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

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

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

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

533
513
1

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
533
513