Overview

WikiHub APIは、WikiHubで利用できる機能を外部のプログラムから利用可能な形で提供しています。WikiHub APIでは、WebブラウザでWikiHubを利用するのとほぼ同等の機能が提供されています。

WikiHub APIは、HTTPを利用するRESTfulなインターフェースを持ち、基本的にJSONを利用してデータをやり取りします。GitHubやTwitterなどのAPIを利用したことがある場合は、それと似たような感覚で利用できると思います。WikiHub APIはOAuth 2.0に従って認可を行います。そのため、リクエストにはアクセストークンが必要になります。

プロトコルとホスト

URLのプロトコルにはHTTPSを利用してください。URLのホストには、*.wikihub.io や wikihub.io など、操作するデータに応じて適切なホストを利用してください。以下は利用できるURLの例です:

HTTPメソッド

WikiHub APIでは、以下の5つのHTTPメソッドを利用します。

  • DELETE
  • GET
  • PATCH
  • POST
  • PUT

入力値

以下の3種類の入力値を利用します。

  • URLのパスに埋め込まれた値
  • URLクエリ
  • リクエストボディ

リクエストボディを利用する場合は、JSON形式でエンコードし、Content-Typeリクエストヘッダに application/json を指定してください。

レスポンスボディ

WikiHub APIから返されるレスポンスボディはJSON形式でエンコードされています。なお、ステータスコードが204の場合のみ、リクエストボディが含まれません (PUTとDELETEを利用するエンドポイントで204が返ります)。また、レスポンスに日時を表すデータが含まれる場合、ISO 8601形式で表現されます。

ステータスコード

以下のステータスコードを利用します。

  • 200 (GET, PATCH)
  • 201 (POST)
  • 204 (PUT, DELETE)
  • 400
  • 401
  • 403
  • 404
  • 500

ページネーション

配列を返すエンドポイントでは、全ての要素を一度に返すようにはなっておらず、代わりにページを指定できるようになっています。これらのエンドポイントには、ページ番号を表すpageパラメータと、1ページあたりに含まれる要素数を表すper_pageパラメータを渡すことができます。pageの初期値は1、pageの最大値は100に設定されています。また、per_pageの初期値は20、per_pageの最大値は100に設定されています。

ページを指定できるエンドポイントでは、Linkヘッダ を含んだレスポンスを返します。Linkヘッダには、最初のページと最後のページへのリンクに加え、存在する場合には次のページと前のページへのリンクが含まれます。個々のリンクにはそれぞれ、first、last、next、prevという値を含んだrel属性が紐付けられます。

Link: <https://help.wikihub.io/api/v1/articles?page=1>; rel="first",
      <https://help.wikihub.io/api/v1/articles?page=2>; rel="prev",
      <https://help.wikihub.io/api/v1/articles?page=4>; rel="next",
      <https://help.wikihub.io/api/v1/articles?page=5>; rel="last"

また、ページを指定できるエンドポイントでは、要素の合計数が Total-Count レスポンスヘッダに含まれます。

Total-Count: 6

エラーレスポンス

エラー時のレスポンスには、以下のようにdescriptionとtypeプロパティが含まれます。

{
  "description": "Not found",
  "type": "not_found"
}

認証

すべてのリクエストにおいて、アカウントの認証・認可のためにアクセストークンを要求します。アクセストークンは、個人用アクセストークンのページ から発行してください。アクセストークンをリクエストに含めるには、以下のようにAuthorizationヘッダに含めます。

Authorization: Bearer 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcd

あるいは、以下のようにURLクエリとして渡します。

https://wikihub.io/api/v1/users?access_token=1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcd

スコープ

それぞれのアクセストークンには、幾つかのスコープが紐付いています。スコープは、アクセストークンを利用して行える操作を制限するためのものです。これは、アクセストークン発行時に選択できます。

read_public   - 公開されているコミュニティからデータを読み込む
read_private  - 非公開のコミュニティからデータを読み込む
write_public  - 公開されているコミュニティにデータを書き込む
write_private - 非公開のコミュニティにデータを書き込む

なお、サブドメインを利用しない wikihub.io ドメインへのアクセスには read_public と write_public のスコープが適用されます。ユーザ情報を取得するエンドポイントなどがこのケースに当てはまります。