WEB上で簡単にAPI仕様書の作成・管理を行えるツール「NotePM」
→API仕様書のテンプレをNotePMで使う（無料）
開発者が利用するAPIの仕様を記述したドキュメントのテンプレートと例文をご紹介します。
WEB上で簡単にAPI仕様書の作成・管理を行えるツール「NotePM」
API仕様書とは
APIはApplication Programming Interfaceの略で、あるソフトウェアやWebサービスを外部のプログラミングから利用するための仕組みになります。APIを利用することで、開発者はソフトウェアやWebサービスをプログラマブルに、システムから操作できるようになります。システム連携や、自動化と言った目的で利用されることが多いです。
API仕様書はそんなAPI利用に関する手順を記述した文書になります。APIエンドポイントや渡すべきパラメータ、得られる結果などが記述されており、API利用する上で必須のドキュメントになります。
WEB上で簡単にAPI仕様書の作成・管理を行えるツール「NotePM」
API仕様書の目的
API仕様書はあるソフトウェアやWebサービスにおけるインプット（入力値）とアウトプット（出力値）を記述した文書になります。API仕様書があることで、ソフトウェアやWebサービス開発元が保証した範囲において、安全にシステム連携が行えるようになります。もしAPI仕様書がなければ、開発者はAPIの存在に気付かず、もし気付いたとしても手探りで調べなければなりません。これは時によって不正アクセスに繋がる可能性があったり、システムへ予期せぬアクセスを行ってしまう可能性があるでしょう。
APIを公開する場合にはAPI仕様書を必ず用意し、API利用者が安全にシステムを活用できるよう情報を提供しなければなりません。
API仕様書の書き方
API仕様書のフォーマットはいくつかあります。
今回はMarkdownで記述するAPI Blueprintをベースに解説します。
タイトル
API仕様書のタイトルです。サービス名 + APIといった記述などになるでしょう。
概要
APIに関する概要です。どのサービスに関するAPIであるのか、APIを使ってどんなことができるのか（取得系のみなのか、追加や更新も行えるのかなど）などを記述します。
共通仕様
APIが複数ある場合に共通する仕様を記述します。エンドポイントであったり、認証の仕組み、レスポンス（JSONまたはXMLなど）などを記述します。
APIグループのタイトル
ユーザ管理系やメッセージ系、ファイル管理系など、操作するリソースごとにグルーピングするのがAPI仕様書の基本になります。
操作内容
多くのAPIはRESTfulであり、新規作成と更新、取得、削除と言ったCRUD操作に分かれて記述します。メッセージの取得、ユーザの削除など操作する内容に応じたタイトルを記述します。
操作概要
個々の操作に関する説明、注意点などを記述します。
HTTPメソッドとパス
RESTful APIの場合、リソースへのパスとHTTPメソッドで操作内容を定義します。GET /messages であればメッセージの一括取得を意味したり、PATCH /messages/{id} であるメッセージの更新処理を意味します。
送信するパラメータ
APIリクエスト時に送信するパラメータを記述します。これはクエリーストリングに関わるものを記述します。
送信する要素
APIリクエスト時に送信するパラメータを記述します。これはbodyで送信する内容を記述します。
レスポンス
レスポンスはHTTPステータスコードごとに分けて記述します。200系であれば正常終了、400か500系であればエラーに関する内容を記述します。レスポンスは表を使って構造的に記述す場合もあれば、サンプルになるJSONを記述する場合もあります。
