API設計書の書き方

Question

railsで開発をしています。勉強中なのでIT系の知識もまだあまりないです。

API設計書を作成したいのですが、書き方が全く分からなかったので質問させていただきます。

いくつかAPI設計書に関しての記事など読んでみたものの、結局なにをどうやって書いたらいいのかわかりませんでした。

やることはAPI設計書の①共通仕様②API一覧③画面毎のリクエストとレスポンス。の３つを.mdでエディター使って作成です。
一応上記３種類のサンプルをいただきまして、そこでようやく少しわかったのですが、①に関してのみサンプルみても全く理解できなかったので、こちらの記入方法を教えていただきたいです。

まず先にサンプルを載せます。↓

# API共通仕様 サンプル

# API共通仕様
## I APIの概要
  + プロトコル: HTTPS
  + 入力/出力データ形式：JSON
  + 文字コード：UTF-8

送信するリクエストに応じて以下のリクエストヘッダを指定します。

| ヘッダー名 | 必須 | 値 |
| --- | --- | --- |
| Host | 必須 | Server name |
| X-ApiToken | 必須 | {token} |
| Accept | 必須 | application/json |


## II リクエストのフォーマット
リクエストパラメータは JSON形式で送信してください。  
(HTTP リクエストのリクエストボディに JSON データをセットしてください。)
URL : https: //domain/api / ...

エラーコード

| Request Status | HTTP Status code |
| --- | --- |
| 処理成功時 | 200 |
| リソース状態の変更等 | 300 |
| クライアントエラー | 400 |
| サーバーエラー | 500 |





レスポンスフォーマット
正常時、失敗時のレスポンスBODYの共通部分です。
正常時は下記BODYに加えて、API毎に異なるデータが含まれます。



正常時

‘‘‘
{
　"status":  “success”,
}
‘‘‘

失敗時
‘‘‘
{
    "status": "error",
    "error_messages": [
        "emailアドレスもしくはパスワードが間違っています"
    ]
}
‘‘‘

サンプルの中の##　I　APIの概要と　##　II リクエストのフォーマットを作成するのだと思うのですが、
I　の　【送信するリクエストに応じて以下のリクエストヘッダを指定します。】ですが、こちらはどうやって調べたらいいのでしょうか？
ヘッダー名や、必須、値、どれも全くわからないので、それぞれどうやってしらべたらいいでしょうか？

　II
こちらもどこかのファイルに記載があるのでしょうか？

質問としては以上です。

調べている過程で【Rails でリクエストの HTTP ヘッダを取得してログに出力する】とかも読んでみたのですが、記事の意味がわからず試せていません。
vagrant使っているのですが、こちらで何かしらのコマンドで必要なデータが引き出せるということだったのでしょうか？
request.headers.sort.map { |k, v| logger.info "#{k}:#{v}" }とターミナルで打ってみてもエラーにしかなりませんでした。
このような質問で本当に申し訳ないのですが、少しでもアドバイスいただけると助かります。宜しくお願いいたしますm(__)m

Answer 1

まずは「APIとはなんぞや？」ということを調べたほうが良いかと思います。
この場合は「Web API」ですかね。

I　の　【送信するリクエストに応じて以下のリクエストヘッダを指定します。】ですが、こちらはどうやって調べたらいいのでしょうか？

まずは「リクエストヘッダ」を調べるべきかと。
聞いたことない用語、聞いたことあるけどよくわからない用語は調べましょう。

II

こちらもどこかのファイルに記載があるのでしょうか？

用語を調べた上で、Web通信の仕組みを調べたほうが良いでしょう。

---

一応上記３種類のサンプルをいただきまして

とあるので仕事とかでしょうか？
であれば現場ごとに細部が異なるので現場の人に聞いた方が的確です。

Answer 2

残念ながらあなたの質問は全く答えようのないものです。

たとえ話ですが、建築物の設計図が手に入ったので、自分も勉強するために、設計図を書いてみようと思った、しかし手に入れた設計図のここかしこに、よく分からない記述があって、自分で新たな設計図を書くことができない、どうすればよいですか、と質問しているのに等しいです。
新たな設計図を書くのは新しい建築物を建てるためです。あなたはどんな新たな"建築物"を建てようとしていますか？ 設計図はあくまで青写真であって、目的は"建築物"です。その目的とするものが存在しなければ、設計図を書くことすらできません。他の設計書を参考にするのは、逐一の文言ではなく、その構成です。どういった構成を組んで物事が示されているかを学ぶものです。

別の言い方をすると、設計書とは、ある程度のある範囲の人に的確に伝えたい内容が伝わればよいわけで、逐一の文言はさして問題ではありません（不明瞭な文言は困りますが）。必要十分な内容が設計書に盛り込まれていれば、誰が読んでも建築物、製作物、プログラムが構築できるはずで、設計書はそういうものです。

質問の趣旨を取り違えていたら失礼。