【備忘録】Qiita APIの一覧を作成

## 概要
Qiita API v2の[ドキュメント](https://qiita.com/api/v2/docs)を引用。
APIコールの練習のために下調べしました。`Qiitaチーム`について調べたい場合は、ドキュメントを調べる必要があり、さらに具体的なレスポンスが何であるかを調べたい場合も同様にドキュメントを参照してください。

##### Request
APIとのすべての通信にはHTTPSプロトコルを使用。
アクセス先：
| 利用データ    | アクセス先                          |
|----------|--------------------------------|
| Qiita    | https://qiita.com/             |
| Qiitaチーム | https://{{team_id}}.qiita.com/ |

##### Parameter
Requestは次のHTTPメソッドを使用する。
 * GET
 * POST
 * PUT
 * PATCH
 * DELETE

Requestへのパラメータの付与：
| メソッド  | パラメータ    |
|-------|----------|
| GET   | URIクエリ   |
| GET以外 | リクエストボディ |

##### Limitation
Requestの制限：
| ユーザー            | 1時間ごとのリクエスト数  |
|-----------------|---------------|
| Authenticated   | 1000 (回/user) |
| Un-Autenticated | 60 (回/IP)     |

##### Status Code
Status Codeは`200`, `201`, `204`, `400`, `401`, `403`, `404`, `500`の8種類を使用する。
| メソッド       | Status Code |
|------------|-------------|
| GET/PATCH  | 200         |
| POST       | 201         |
| PUT/DELETE | 204         |
| Error      | 適切なコード      |

##### Data Spec
API都のデータの送受信にはJSON形式のデータを使用する。
JSON形式のデータをリクエストボディに入れる際はリクエストのヘッダー内に`Content-Type: 'application/json'`を含める。なお、PUTまたはDELETEリクエストに対してはレスポンスボディが返却されない。

##### Error Response
エラーが発生した際のレスポンスボディは
```
{
    "message": "Not found",
    "type": "not_found" // pattern: ^[a-z0-9_]+$
}
```
で返却され、それぞれエラー内容とエラーの種類が格納される。

##### Pagination
配列を返すAPIの中にはページを指定できるようになっているものがある。
APIは`page`パラメータ(初期値: 20)と`per_page`パラメータ(最大値: 100)によりそれぞれ開始ページの番号、1ページ当たりの要素数を指定することができる。

##### JSON Schema
APIのインターフェースを定義したJSON-Schemaが提供されている：
 * `https://qiita.com/api/v2/schema`
 * `https://qiita.com/api/v2/schema?locale=en`
 * `https://qiita.com/api/v2/schema?locale=ja`


## Authentication＆Authorization
QiitaのGETリクエスト以外のAPIを利用するためにはリクエストのヘッダー内にアクセストークンを含める必要がある。

##### アクセストークン
```
Authorization: Bearer {{access_token}}
```

##### Scope
個々のアクセストークンには以下のようなスコープを紐づけることができる。
| スコープ             | 説明                                    |
|------------------|---------------------------------------|
| read_qiita       | Qiitaからアクセストークンに紐付いたユーザーに関連したデータを読み出す |
| read_qiita_team  | Qiita Teamからデータを読み出す                  |
| write_qiita      | Qiitaにデータを書き込む                        |
| write_qiita_team | Qiita Teamにデータを書き込む                   |

###### アクセストークンの発行
Qiitaにログインした状態で「設定」- 「アプリケーション」からアクセストークンを発行する。このとき、上記スコープを指定する。
（※一度発行すると、再度確認ができないためメモをしておくこと）


## タグ
記事につけられた個々のタグを表す。

APIからのレスポンスボディに含まれる値：
| タグ              | 説明                   | 凡例                                                                                                            | タイプ          |
|-----------------|----------------------|---------------------------------------------------------------------------------------------------------------|--------------|
| followers_count | このタグをフォローしているユーザーの数  | 100                                                                                                           | integer      |
| icon_url        | このタグに設定されたアイコン画像のURL | "https://s3-ap-northeast-1.amazonaws.com/qiita-tag-image/9de6a11d330f5694820082438f88ccf4a1b289b2/medium.jpg" | null, string |
| id              | タグを特定するための一意な名前      | "qiita"                                                                                                       | string       |
| items_count     | このタグが付けられた記事の数       | 200                                                                                                           | integer      |

##### タグ一覧を取得： GET /api/v2/tags
パラメータ：
| パラメータ    | 説明                         | 凡例      | タイプ    | パターン       |
|----------|----------------------------|---------|--------|------------|
| page     | ページ番号 (1から100まで)           | 1       | string | `/^[0-9]+$/` |
| per_page | 1ページあたりに含まれる要素数 (1から100まで) | 20      | string | `/^[0-9]+$/` |
| sort     | 並び順 (countで記事数順、nameで名前順)  | "count" | string |

##### 特定のタグを取得： GET /api/v2/tags/:tag_id

##### ユーザーがフォローしているタグ一覧を取得（降順）： GET /api/v2/users/:user_id/following_tags
パラメータ：
| パラメータ    | 説明                         | 凡例      | タイプ    | パターン       |
|----------|----------------------------|---------|--------|------------|
| page     | ページ番号 (1から100まで)           | 1       | string | `/^[0-9]+$/` |
| per_page | 1ページあたりに含まれる要素数 (1から100まで) | 20      | string | `/^[0-9]+$/` | 

##### タグのフォローを外す： DELETE /api/v2/tags/:tag_id/following

##### タグをフォローしているかどうかを調べる： GET /api/v2/tags/:tag_id/following

##### タグをフォローする： PUT /api/v2/tags/:tag_id/following


## ユーザー
Qiita上のユーザーを表す。
APIからのレスポンスボディに含まれる値：
| パラメータ                  | 説明                                                      | 凡例                                                                                                                             | タイプ          |
|---------------------|---------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------|--------------|
| description         | 自己紹介文                                                   | "Hello, world."                                                                                                                | null, string |
| facebook_id         | Facebook ID                                             | "qiita"                                                                                                                        | null, string |
| followees_count     | このユーザーがフォローしているユーザーの数                                   | 100                                                                                                                            | integer      |
| followers_count     | このユーザーをフォローしているユーザーの数                                   | 200                                                                                                                            | integer      |
| github_login_name   | GitHub ID                                               | "qiitan"                                                                                                                       | null, string |
| id                  | ユーザーID                                                  | "qiita"                                                                                                                        | string       |
| items_count         | このユーザーが qiita.com 上で公開している記事の数 (Qiita Teamでの記事数は含まれません) | 300                                                                                                                            | integer      |
| linkedin_id         | LinkedIn ID                                             | "qiita"                                                                                                                        | null, string |
| location            | 居住地                                                     | "Tokyo, Japan"                                                                                                                 | null, string |
| name                | 設定している名前                                                | "Qiita キータ"                                                                                                                    | null, string |
| organization        | 所属している組織                                                | "Qiita Inc."                                                                                                                   | null, string |
| permanent_id        | ユーザーごとに割り当てられる整数のID                                     | 1                                                                                                                              | integer      |
| profile_image_url   | 設定しているプロフィール画像のURL                                      | "https://s3-ap-northeast-1.amazonaws.com/qiita-image-store/0/88/ccf90b557a406157dbb9d2d7e543dae384dbb561/large.png?1575443439" | string       |
| team_only           | Qiita Team専用モードに設定されているかどうか                             | FALSE                                                                                                                          | boolean      |
| twitter_screen_name | Twitterのスクリーンネーム                                        | "qiita"                                                                                                                        | null, string |
| website_url         | 設定しているWebサイトのURL                                        | "https://qiita.com"                                                                                                            | null, string |

##### 記事をストックしているユーザー一覧を取得（ストック日時の降順）： GET /api/v2/items/:item_id/stockers
パラメータ：
| パラメータ    | 説明                         | 凡例      | タイプ    | パターン       |
|----------|----------------------------|---------|--------|------------|
| page     | ページ番号 (1から100まで)           | 1       | string | `/^[0-9]+$/` |
| per_page | 1ページあたりに含まれる要素数 (1から100まで) | 20      | string | `/^[0-9]+$/` | 

##### すべてのユーザーの一覧を取得（作成日時の降順）： GET /api/v2/users
パラメータ：
| パラメータ    | 説明                         | 凡例      | タイプ    | パターン       |
|----------|----------------------------|---------|--------|------------|
| page     | ページ番号 (1から100まで)           | 1       | string | `/^[0-9]+$/` |
| per_page | 1ページあたりに含まれる要素数 (1から100まで) | 20      | string | `/^[0-9]+$/` | 

##### 特定のユーザーを取得： GET /api/v2/users/:user_id

##### ユーザーがフォローしているユーザー一覧を取得： GET /api/v2/users/:user_id/followees
パラメータ：
| パラメータ    | 説明                         | 凡例      | タイプ    | パターン       |
|----------|----------------------------|---------|--------|------------|
| page     | ページ番号 (1から100まで)           | 1       | string | `/^[0-9]+$/` |
| per_page | 1ページあたりに含まれる要素数 (1から100まで) | 20      | string | `/^[0-9]+$/` | 

##### ユーザーをフォローしているユーザー一覧を取得： GET /api/v2/users/:user_id/followers
パラメータ：
| パラメータ    | 説明                         | 凡例      | タイプ    | パターン       |
|----------|----------------------------|---------|--------|------------|
| page     | ページ番号 (1から100まで)           | 1       | string | `/^[0-9]+$/` |
| per_page | 1ページあたりに含まれる要素数 (1から100まで) | 20      | string | `/^[0-9]+$/` |  `/^[0-9]+$/` |

##### ユーザーへのフォローを外す： DELETE /api/v2/users/:user_id/following

##### ユーザーをフォローしている場合、ステータスコード204を返す： GET /api/v2/users/:user_id/following

##### ユーザーをフォローする： PUT /api/v2/users/:user_id/following


## 投稿
ユーザーからの投稿を表す。
APIからのレスポンスボディに含まれる値：
| パラメータ                 | 説明                                | 凡例                                                   | タイプ           | フォーマット/パターン      |
|-----------------------|-----------------------------------|------------------------------------------------------|---------------|------------------|
| rendered_body         | HTML形式の本文                         | "&lt;h1&gt;Example&lt;/h1&gt;"                                   | string        |                  |
| body                  | Markdown形式の本文                     | "# Example"                                          | string        |                  |
| coediting             | この記事が共同更新状態かどうか (Qiita Teamでのみ有効) | FALSE                                                | boolean       |                  |
| comments_count        | この記事へのコメントの数                      | 100                                                  | integer       |                  |
| created_at            | データが作成された日時                       | "2000-01-01T00:00:00+00:00"                          | string        | date-time        |
| group                 | Qiita Teamのグループを表します。             |                                                      |               |                  |
| id                    | 記事の一意なID                          | "c686397e4a0f4f11683d"                               | string        | `/^[0-9a-f]{20}$/` |
| likes_count           | この記事への「いいね」の数（Qiitaでのみ有効）         | 100                                                  | integer       |                  |
| private               | 限定共有状態かどうかを表すフラグ (Qiita Teamでは無効) | false                                                | boolean       |                  |
| reactions_count       | 絵文字リアクションの数（Qiita Teamでのみ有効）      | 100                                                  | integer       |                  |
| stocks_count          | この記事がストックされた数                     | 100                                                  | integer       |                  |
| tags                  | 記事に付いたタグ一覧                        | [{"name"=>"Ruby", "versions"=>["0.0.1"]}]            | array         |                  |
| title                 | 記事のタイトル                           | "Example title"                                      | string        |                  |
| updated_at            | データが最後に更新された日時                    | "2000-01-01T00:00:00+00:00"                          | string        | date-time        |
| url                   | 記事のURL                            | "https://qiita.com/Qiita/items/c686397e4a0f4f11683d" | string        |                  |
| user                  | Qiita上のユーザーを表します。                 |                                                      |               |                  |
| page_views_count      | 閲覧数                               | 100                                                  | null, integer |                  |
| team_membership       | Qiita Team のチームメンバー情報を表します。       |                                                      |               |                  |
| organization_url_name | 記事のOrganization の url_name を表します。 | "qiita-inc"                                          | null, integer |

##### 認証済みのユーザーの記事の一覧を取得（作成日時で降順）： GET /api/v2/authenticated_user/items
パラメータ：
| パラメータ    | 説明                         | 凡例      | タイプ    | パターン       |
|----------|----------------------------|---------|--------|------------|
| page     | ページ番号 (1から100まで)           | 1       | string | `/^[0-9]+$/` |
| per_page | 1ページあたりに含まれる要素数 (1から100まで) | 20      | string | `/^[0-9]+$/` | 

##### 記事の一覧を取得（作成日時で降順）： GET /api/v2/items
パラメータ：
| パラメータ    | 説明                         | 凡例      | タイプ    | パターン       |
|----------|----------------------------|---------|--------|------------|
| page     | ページ番号 (1から100まで)           | 1       | string | `/^[0-9]+$/` |
| per_page | 1ページあたりに含まれる要素数 (1から100まで) | 20      | string | `/^[0-9]+$/` | 
| query   | 検索クエリ | "qiita user:Qiita"      | string | `/^[0-9]+$/` | 

##### 新たに記事を作成する： POST /api/v2/items
パラメータ：
| パラメータ                 | 説明                                                    | 凡例                                        | タイプ              |
|-----------------------|-------------------------------------------------------|-------------------------------------------|------------------|
| body                  | Markdown形式の本文                                         | "# Example"                               | string, required |
| coediting             | この記事が共同更新状態かどうか (Qiita Teamでのみ有効)                     | FALSE                                     | boolean          |
| group_url_name        | この投稿を公開するグループの url_name (null で全体に公開。Qiita Teamでのみ有効) | "dev"                                     | null, string     |
| private               | 限定共有状態かどうかを表すフラグ (Qiita Teamでは無効)                     | FALSE                                     | boolean          |
| tags                  | 記事に付いたタグ一覧                                            | [{"name"=>"Ruby", "versions"=>["0.0.1"]}] | array, required  |
| title                 | 記事のタイトル                                               | "Example title"                           | string, required |
| tweet                 | Twitterに投稿するかどうか (Twitter連携を有効化している場合のみ有効)            | FALSE                                     | boolean          |
| organization_url_name | 記事のOrganization の url_name を表します。                     | "qiita-inc"                               | null, string     |

##### 記事を削除する： DELETE /api/v2/items/:item_id

##### 特定の記事を取得する： GET /api/v2/items/:item_id

##### 記事を更新する： PATCH /api/v2/items/:item_id
パラメータ：
| パラメータ                 | 説明                                                    | 凡例                                        | タイプ              |
|-----------------------|-------------------------------------------------------|-------------------------------------------|------------------|
| body                  | Markdown形式の本文                                         | "# Example"                               | string, required |
| coediting             | この記事が共同更新状態かどうか (Qiita Teamでのみ有効)                     | FALSE                                     | boolean          |
| group_url_name        | この投稿を公開するグループの url_name (null で全体に公開。Qiita Teamでのみ有効) | "dev"                                     | null, string     |
| private               | 限定共有状態かどうかを表すフラグ (Qiita Teamでは無効)                     | FALSE                                     | boolean          |
| tags                  | 記事に付いたタグ一覧                                            | [{"name"=>"Ruby", "versions"=>["0.0.1"]}] | array, required  |
| title                 | 記事のタイトル                                               | "Example title"                           | string, required |
| organization_url_name | 記事のOrganization の url_name を表します。                     | "qiita-inc"                               | null, string     |

##### 記事をストックする： PUT /api/v2/items/:item_id/stock

##### ストックされた記事を取り除く： DELETE /api/v2/items/:item_id/stock

##### 記事をストックしているかどうかを調べる： GET /api/v2/items/:item_id/stock

##### タグをもとに記事一覧を取得する（タグをつけた日時の降順）： GET /api/v2/tags/:tag_id/items
パラメータ：
| パラメータ    | 説明                         | 凡例      | タイプ    | パターン       |
|----------|----------------------------|---------|--------|------------|
| page     | ページ番号 (1から100まで)           | 1       | string | `/^[0-9]+$/` |
| per_page | 1ページあたりに含まれる要素数 (1から100まで) | 20      | string | `/^[0-9]+$/` | 

##### 特定ユーザーの記事一覧を取得する（作成日時の降順）： GET /api/v2/users/:user_id/items
パラメータ：
| パラメータ    | 説明                         | 凡例      | タイプ    | パターン       |
|----------|----------------------------|---------|--------|------------|
| page     | ページ番号 (1から100まで)           | 1       | string | `/^[0-9]+$/` |
| per_page | 1ページあたりに含まれる要素数 (1から100まで) | 20      | string | `/^[0-9]+$/` | 

##### 特定ユーザーがストックした記事の一覧を取得する（ストックした日時の降順）： GET /api/v2/users/:user_id/stocks
パラメータ：
| パラメータ    | 説明                         | 凡例      | タイプ    | パターン       |
|----------|----------------------------|---------|--------|------------|
| page     | ページ番号 (1から100まで)           | 1       | string | `/^[0-9]+$/` |
| per_page | 1ページあたりに含まれる要素数 (1から100まで) | 20      | string | `/^[0-9]+$/` | 

## 最後に
今後の展望としては、APIコールをするわけですが、こちらのドキュメントも逐一見やすくなる工夫をしていきたい（そのうち）。