API仕様書に書いて欲しい内容

TwitterのAPI仕様書みたいに、仕様書を書いて欲しいなと感じた。 「いい感じの仕様書を書いて」と頼んでも出てこないので文章にして依頼しようと思ってまとめてみた。

含めて欲しい内容

• メソッド(GET/POST/DELETE/...)
• エントリーポイント(URL)
• 処理の内容(何をして何を返すAPIなのか)
• 認証の有無(ログインが必要か、どのroleの人が利用可能か。など)
• リクエストパラメータの内容(キー名、値の説明(何をどのフォーマットで)と例、必須/任意)
• レスポンス(どんなときにどんなレスポンス、ステータスコードを返すのか。)
• リクエスト、レスポンスのContent-Type
• 例(リクエスト/レスポンスが各パターンにあればより良い)

例(Twitterのstatuses/destroyより欲しいものを抜粋)

POST statuses/destroy/:id

Destroys the status specified by the required ID parameter. The authenticating user must be the author of the specified status. Returns the destroyed status if successful.

Resource URL

https://api.twitter.com/1.1/statuses/destroy/:id.json

Resource Information

information	description
Requires authentication?	Yes (user context only)

Parameters

name	required/optional	description	example
id	required	The numerical ID of the desired status.	Example Values: 123
trim_user	optional	When set to either true, t or 1, each tweet returned in a timeline will include a user object including only the status authors numerical ID.	Example Values: true

Example Request

POST https://api.twitter.com/1.1/statuses/destroy/240854986559455234.json

Example Result

{
  "coordinates": null,
  "favorited": false,
  "created_at": "Wed Aug 29 16:54:38 +0000 2012",
  "truncated": false,
  "id_str": "240854986559455234",
  "entities": {
    "urls": [
      {
        "expanded_url": "http://venturebeat.com/2012/08/29/vimeo-dropbox/#.UD5JLsYptSs.twitter",
        "url": "http://t.co/7UlkvZzM",
        "indices": [
          69,
          89
        ],
        "display_url": "venturebeat.com/2012/08/29/vim\u2026"
      }
    ],
    "hashtags": [
 
    ],
    "user_mentions": [
 
    ]
  },
  "in_reply_to_user_id_str": null,
  "text": "\"Vimeo integrates with Dropbox for easier video uploads and shares\": http://t.co/7UlkvZzM",
  "contributors": null,
  "retweet_count": 1,
  "id": 240854986559455234,
  "in_reply_to_status_id_str": null,
  "geo": null,
  "retweeted": false,
  "in_reply_to_user_id": null,
  "possibly_sensitive": false,
  "place": null,
  "user": {
    "name": "Jason Costa",
    "profile_sidebar_border_color": "86A4A6",
    "profile_sidebar_fill_color": "A0C5C7",
    "profile_background_tile": false,
    "profile_image_url": "http://a0.twimg.com/profile_images/1751674923/new_york_beard_normal.jpg",
    "created_at": "Wed May 28 00:20:15 +0000 2008",
    "location": "",
    "is_translator": true,
    "follow_request_sent": false,
    "id_str": "14927800",
    "profile_link_color": "FF3300",
    "entities": {
      "url": {
        "urls": [
          {
            "expanded_url": "http://www.jason-costa.blogspot.com/",
            "url": "http://t.co/YCA3ZKY",
            "indices": [
              0,
              19
            ],
            "display_url": "jason-costa.blogspot.com"
          }
        ]
      },
      "description": {
        "urls": [
 
        ]
      }
    },
    "default_profile": false,
    "contributors_enabled": false,
    "url": "http://t.co/YCA3ZKY",
    "favourites_count": 883,
    "utc_offset": -28800,
    "id": 14927800,
    "profile_image_url_https": "https://si0.twimg.com/profile_images/1751674923/new_york_beard_normal.jpg",
    "profile_use_background_image": true,
    "listed_count": 150,
    "profile_text_color": "333333",
    "protected": false,
    "lang": "en",
    "followers_count": 8760,
    "time_zone": "Pacific Time (US & Canada)",
    "profile_background_image_url_https": "https://si0.twimg.com/images/themes/theme6/bg.gif",
    "verified": false,
    "profile_background_color": "709397",
    "notifications": false,
    "description": "Platform at Twitter",
    "geo_enabled": true,
    "statuses_count": 5531,
    "default_profile_image": false,
    "friends_count": 166,
    "profile_background_image_url": "http://a0.twimg.com/images/themes/theme6/bg.gif",
    "show_all_inline_media": true,
    "screen_name": "jasoncosta",
    "following": false
  },
  "possibly_sensitive_editable": true,
  "source": "<a href="//twitter.com/tweetbutton\"" rel="\"nofollow\"">Tweet Button</a>",
  "in_reply_to_screen_name": null,
  "in_reply_to_status_id": null
}