概要

Qiita API v2のドキュメントを引用。
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]+$/`

ユーザーへのフォローを外す： 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形式の本文	"<h1>Example</h1>"	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コールをするわけですが、こちらのドキュメントも逐一見やすくなる工夫をしていきたい（そのうち）。