Subscribed unsubscribe Subscribe Subscribe

@peccul is peccu

(love peccu '(emacs lisp cat outdoor bicycle mac linux coffee))

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

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

含めて欲しい内容

  • メソッド(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
}