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

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

https://qiita.com/api/v2/docs#%E6%8A%95%E7%A8%BF

認証なしでも利用できる 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 はこちら :point_down: の URL からブラウザでレスポンスを確認できます。

- [`https://qiita.com/api/v2/items/d3ade7c1ae9897536b28`](https://qiita.com/api/v2/items/d3ade7c1ae9897536b28)

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

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/27471/5add8df6-7b97-e8f7-3940-5e5a2d937653.png)

なお、レートリミットはエンドポイントごとに管理されているわけではなく、すべての 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 の利用方法については [公式ドキュメントの認証認可の項目](https://qiita.com/api/v2/docs#%E8%AA%8D%E8%A8%BC%E8%AA%8D%E5%8F%AF) に書かれています。

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

https://qiita.com/yonex/items/ce8c38e75efeaf13a07c

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

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

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

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

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/27471/bbafa66d-d65e-36ed-481a-aac96080fef2.png)

https://help.qiita.com/ja/articles/qiita-search-options

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

- [`https://qiita.com/search?q=created:>=2022-12-01 created:<=2022-12-01 stocks:>=100`](https://qiita.com/search?q=created%3A%3E%3D2022-12-01+created%3A%3C%3D2022-12-01+stocks%3A%3E%3D100)

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

- [`https://qiita.com/api/v2/items?query=created:>=2022-12-01 created:<=2022-12-01 stocks:>=100`](https://qiita.com/api/v2/items?query=created%3A%3E%3D2022-12-01+created%3A%3C%3D2022-12-01+stocks%3A%3E%3D100)

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

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

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/27471/4c030008-f29d-92e9-77a0-958caf7c2448.png)

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