Qiita の記事一覧 API でも検索クエリに絞り込みオプションが使える

Qiita の「投稿」に関する API のドキュメントは、こちらです

認証なしでも利用できる API と、認証が必要な API があるので、まずそれぞれ以下の表にまとめます

認証なしでも利用できる API

以下のようなレートリミットがつきますが、認証していない状態でも利用できる API があります。

認証している状態ではユーザーごとに1時間に1000回まで、認証していない状態ではIPアドレスごとに1時間に60回までリクエストを受け付けます。

エンドポイントは以下のとおりです

エンドポイント	説明
GET /api/v2/items	記事の一覧を作成日時の降順で返します。
GET /api/v2/items/:item_id	記事を取得します。
GET /api/v2/tags/:tag_id/items	指定されたタグが付けられた記事一覧を、タグを付けた日時の降順で返します。
GET /api/v2/users/:user_id/items	指定されたユーザーの記事一覧を、作成日時の降順で返します。
GET /api/v2/users/:user_id/stocks	指定されたユーザーがストックした記事一覧を、ストックした日時の降順で返します。

認証なしでも利用できるということで、これらの API はブラウザから誰でもアクセスできます。たとえば、いま見ているこの記事についての情報取得 API はこちら の URL からブラウザでレスポンスを確認できます。

• https://qiita.com/api/v2/items/d3ade7c1ae9897536b28

また、レートリミットに関する情報はレスポンスヘッダーによって返される仕様です。たとえば、上記 URL を開いた Chrome のデベロッパーツールを使うと、以下のスクリーンショットのように Rate-Limit（適用されているリミット回数）, Rate-Remaining（単位時間あたりの残り回数）, Rate-Reset（残り回数が回復する予定時刻の UNIX タイムスタンプ）を確認できます。

なお、レートリミットはエンドポイントごとに管理されているわけではなく、すべての API にまたがって共通のカウントになっているようです。たとえば、まず記事の一覧を取得したら残り 59、そしてまた別の API にリクエストしたら残り 58、という具合です。

認証が必要な API

一方で、アクセストークンによる認証が必要で、アクセストークンに紐づくユーザーに関する投稿関連の API は以下のとおりです。（「Qiita Team」専用の API については除外しています）

エンドポイント	説明
GET /api/v2/authenticated_user/items	認証中のユーザーの記事の一覧を作成日時の降順で返します。
POST /api/v2/items	新たに記事を作成します。
DELETE /api/v2/items/:item_id	記事を削除します。
PATCH /api/v2/items/:item_id	記事を更新します。
DELETE /api/v2/items/:item_id/like	記事への「いいね」を取り消します。
PUT /api/v2/items/:item_id/like	記事に「いいね」を付けます。
PUT /api/v2/items/:item_id/stock	記事をストックします。
GET /api/v2/items/:item_id/stock	記事をストックしているかどうかを調べます。
GET /api/v2/items/:item_id/like	記事に「いいね」を付けているかどうかを調べます。
DELETE /api/v2/items/:item_id/stock	記事をストックから取り除きます。

記事を投稿することから、いいねやストックの操作までできる、かなり色々と夢の広がる API になっています。認証が必要な API の利用方法については 公式ドキュメントの認証認可の項目 に書かれています。

アクセストークンを発行する手順と Node.js の fetch() を使って認証つきのリクエストを実行する方法は以下の記事に書きましたので、よかったら参考にしてみてください。

記事一覧 API で検索クエリを試す

認証なしでも利用できる、記事一覧 API GET /api/v2/items のパラメータは、以下の3種類です。

• page：ページ番号 (1から100まで)
• per_page：1ページあたりに含まれる要素数 (1から100まで)
• query：検索クエリ

今回試したかったことは、Qiita の検索で使えるオプション が、API の検索クエリにもそのまま使えるのか、ということです。つまり、API でも記事の作成日時やストック数などによる絞りこみができると嬉しいです。

たとえば、ブラウザから Qiita の検索で、去年のアドベントカレンダー初日（2022年12月1日）に投稿された記事のうちストックが100以上のものだけを絞りこむと、こうなります

• https://qiita.com/search?q=created:>=2022-12-01 created:<=2022-12-01 stocks:>=100

これをそのまま記事一覧 API の query に当てはめてみると……

• https://qiita.com/api/v2/items?query=created:>=2022-12-01 created:<=2022-12-01 stocks:>=100

レスポンスは同じ結果でした！Qiita の検索で使えるオプションは、API でも同様に有効なようです。

なお、このレスポンスが何件の記事を含んでいるかというカウントは、Total-Count ヘッダーを利用して取得できます。

次の記事では、これらの機能を利用して何か作ってみたいと思います