APIドキュメント(テンプレート)

REST APIドキュメントのサンプル。APIドキュメントの作り方を解説し、共有します。できるだけ短く簡素でわかりやすい、APIドキュメントを作成してみましょう。

APIドキュメント(テンプレート) 's Header Image

06/28/2018

こんにちは、所長の下田です。外は急に暑くなりましたが、クーラーの効いた室内に引きこもってブログ記事を更新しています。

本日は、普段開発時に使っているAPIドキュメントテンプレートを共有します(今後様々なドキュメントテンプレートを共有していく予定です)。

サービス開発の際にドキュメントはないがしろにしがちですが、大切なプロセスなので面倒でもきちんと書き起こしましょう。特にチームで開発する場合、ドキュメントが中心となりチーム全員の理解が統率されていきます。仕様変更時は、ドキュメントも随時更新して常に正しいものにしていく運用も大切です。設計時に書き起こした仕様書が全く(よくも悪くも進化した)システムと合っていなくて意味がない・・・、なんていうシーンはあるあるですね・・ ・

APIドキュメントに関しては、他の人に利用されるものなのでレベルの高いドキュメントが必要とされます。レベルが高いといっても複雑なものではなく、むしろ、できるだけ短く簡素かつわかりやすく書く必要があります。


(API名を記載)

APIの説明文を記載。APIの利用シーンと目的を記載すると、使う人にもわかりやすい。

URL(APIの相対パス)

メソッド

GET | POST | DELETE | PUT のいずれかを記載。

URLパラメター

リクエスト時に使えるパラメターを記載。

必須パラメター

必須となるパラメターを記載。 パラメターは

  • パスで渡すもの
  • クエリーで渡すもの
  • クッキーで渡すもの

があります。明記してAPI利用者にわかりやすくしましょう。

オプションパラメター

必須パラメターと基本同じフォーマットで記載。

データ

POST時に渡すデータを記載。データのタイプとしては

  • application/json
  • application/xml
  • application/x-www-form-urlencoded
  • text/plain
  • multipart/form-data

があります。入力値エラーがおきないように各値のタイプや制限を明記しましょう。

正常レスポンス

コード200

エラーレスポンス

エラーレスポンスの一覧を記載。エラーコード一覧はこちらを参照: https://docs.microsoft.com/en-us/rest/api/storageservices/common-rest-api-error-codes

サンプルコード

サンプルコードを記載。cURLを使ってAPIを使う方法はこちらを参照:https://docs.oracle.com/cloud/latest/marketingcs_gs/OMCAB/Developers/GettingStarted/API%20requests/curl-requests.htm

備考

備考を記載 。


以上になります。最近ではドキュメントをオンラインで管理していますが、便利なワードファイルテンプレートもこちらからダウンロードしていただけるようになっていますので、ご利用ください。


API REST API ドキュメント サンプル
シェア シェア
下田 昌平
株式会社トランスコスモス技術研究所、代表取締役兼最高技術責任者、トランスコスモス株式会社執行役員。アメリカ・日本・中国企業の経営を得て2017年にトランスコスモスに入社。米大学にて数学・統計学専攻から開発歴20年、C、C#、データ設計・管理を中心に多くの開発案件を完遂。

お問合せ