はじめに

新しいAPIや関数を使用する際に、
自分だと、そのAPIや関数をググって、誰かが書いたわかりやすい解説記事を使ってみることが多い。

しかし、記事には一部情報がピックアップされていたりして、欲しい情報が思うように得られないことが多々ある。

そんな時は公式ドキュメントを見れば全て書いてあるということに最近気づいた。
きっとそういう人は自分だけではないはず。（と、信じている。）

何を書いたか

今回はSlackのfiles.uploadを例に読み方を紹介した。

多くの公式ドキュメントには渡すべき、必須あるいは任意の引数や、返値が書いてある。
また、APIなら使うのに必要な設定も書かれており、困ったら一度公式に立ち返ってみることをお勧めする。

files.upload公式ドキュメント

今回は"files.upload"の公式ドキュメントを元に、
構築に必要な情報を抜粋して（というか、自分が全部読めていないだけなのだが）紹介する。

ドキュメントは下記URLを参照のこと
https://api.slack.com/methods/files.upload

Facts

ドキュメント上にある"Facts"には対象のAPIの基本情が記載されている。

• MethodURL
  プログラムが投げるべきURLが記載されている。プログラムはMethodURLをもとにクエリを作成する。

• Preferred HTTP method
  推奨されるHTTPメソッドが記載されている。"POST"と記載されていれば、
  推奨通りにPOSTメソッドでリクエストを送ろう。

• Accepted content types
  受け入れ可能なコンテンツのタイプが記載されている。
  content typesを指定する際はどちらかを使えば良い。

• rate limiting
  レート制限のことらしい（この項目に関しては特に必要としたことがない）
  "Tier2"の場合、２０回/minのリクエストが保証されるらしい。
  ※項目をクリックすれば、詳細が見れる

• works with
  構築するAPI Appに付与する権限が記載されるている。Bot/User のどちらで構築する際でも"files:write"の権限の付する必要がある。

　　API Appへの権限付与にはOAuthスコープを指定すればよい。
　　詳細な設定方法は以下がわかりよい。　
　　http://dotnsf.blog.jp/archives/1074688701.html

Arguments

Argumentsには引数が記載されている。
数が多いので全ての紹介は避けるが、これ等のうち、少なくとも"Required"を指定する。

例えば、tokenは必ず必須でchannelsにはチャンネル名もしくはIDを、（複数指定なら、コンマ区切りで）引数として設定できる

Response

Responseには返値の形式と中身の例が記載されている。
引値で必要な値がある時はここを参照するとよい。

ちなみに、エラーが発生したときの返値については下記のように帰ってくる
"ok":false にはリクエストが失敗したこと、
また、"error"にはその内容が記載されている。

Error

最後に、Errorの説明をする。
Errorには文字通り、エラー内容が記載されている。
リクエストに失敗する場合、返値の”error”から該当する内容を
探すと解消方法のヒントになるだろう。

最後に

以上がfiles.upload公式ドキュメントの読み方の紹介である。
公式を読めば全てが解決するとは限らないが、
少なくとも足掛かりにはなると思うので、
つまったら公式ドキュメントを一度見ることを推奨した。