トップ > API > API仕様書の項目を考える

API仕様書の項目を考える

API

API仕様書を書くことになったものの、外部のツールは規定で使えない。
これといったテンプレートも用意されていないため、どうしたもんかなあ。API開発したことないし…。
ってことで、いろいろと調べてから考えてみた。


はてなブックマーク済み

そういえばはてなブックマーク済みの中にAPIに関するものがあった。

speakerdeck.com
speakerdeck.com
speakerdeck.com

すでに作成されているAPIは、取得でも全部POSTメソッドだったから、REST思考ではないってことを理解した。
内部向けのAPIだからなんだろうな。


「api 叩く url」でググる

"GET /search/API仕様書"と"/search?q=API仕様書"は同じ呼び出し方？？？とかこの辺で混乱したので「api 叩く url」でググった。

下記の記事、内容が充実してた。
WebAPIについての説明 - Qiita

あと、HTTPの知識が弱いってことを自覚した。雰囲気しか分かってない。アカン…。


「api 仕様書 サンプル」でググる

そして本題をググった。

下記の記事がパッと見で分かりやすかった。
API仕様書に書いて欲しい内容 - @peccul is peccu


API仕様書の項目

これでイケるかなあ。

  • 処理概要
  • アクセスURL
  • (プロトコル)
  • メソッド(GET/POST/PUT/DELETE)
  • リクエスト
    • (形式(JSON など))
      • No.
      • 名前(例:article_id)
      • 型(数値/文字列 など)
      • 長さ
      • 必須(必須/任意)
      • 内容(例:記事ID)
      • 備考
  • レスポンス
    • 形式(JSON など)
      • No.
      • 名前(例:author)
      • 型(数値/文字列 など)
      • 長さ
      • 繰返し(○/回数/空欄 など)
      • 内容(例:記者)
      • 備考
    • (サンプル)

URLとURIの違いも調べたけどぼんやりとした感じ。
積んでる「Webを支える技術」と、「Web API: The Good Parts」を読んで知識を身につけるべきだな…。