REST API V1の概要

REST API V1のベースURIとアクセストークンの渡し方、すべてのエンドポイントに共通する約束事をまとめています。
各エンドポイントの詳細は開発者向けヘルプから個別のページを参照してください。

ベースURI

Annict APIのベースURIは下記になります。

https://api.annict.com

Annictが提供する全てのAPIには、このベースURIの後にエンドポイントのパスを記述してアクセスすることができます。
例えば作品情報を取得する場合は、パス /v1/works を繋げて下記のようにリクエストを送ります。

GET https://api.annict.com/v1/works

日付

フォーマットはISO 8601 (YYYY-MM-DDTHH:MM:SSZ) で返します。
よってタイムゾーンはUTCとなります。

アクセストークン

REST API V1を操作するにはアクセストークンが必要です。
アクセストークンについてはAnnict APIの認証をご参照ください。

アクセストークンの付与

Annict APIを通じてリソースを取得するためには、個人用アクセストークンやOAuthによって作成されたアクセストークンをリクエストに付与する必要があります。
付与の仕方は2種類あります。

1. リクエストヘッダに付与する
2. URIのパラメータに付与する

URIのパラメータに付与する方法は手軽ですが、アクセストークンがアクセスログやブラウザの履歴に残ります。
どちらでも構わない場面ではリクエストヘッダに付与してください。

リクエスト例 (リクエストヘッダに付与する)

$ curl -H "Authorization: Bearer 35372b2d866222ed33e355c36d86be498076e037a810ee72963819339c781f32" \
-X GET https://api.annict.com/v1/works

リクエスト例 (URIのパラメータに付与する)

$ curl -X GET https://api.annict.com/v1/works?access_token=35372b2d866222ed33e355c36d86be498076e037a810ee72963819339c781f32

HTTPステータスコード

Annict APIでは下記の条件でHTTPステータスコードを返します。

ページネーション

作品一覧など、複数のリソースを返すAPIにはページを指定して取得するリソースを分割するようになっています。
ページを指定する場合は page パラメータを、1ページあたり何件のリソースを取得するかを指定する場合は per_page パラメータを使用します。
page のデフォルトは 1、per_page のデフォルトは 25 件で、per_page には 50 件まで指定できます。

レスポンスデータには total_count, next_page, prev_page の3つのフィールドが付加されます。
total_count にはページを跨いだ全リソース数、next_page, prev_page には次のページ数、前のページ数が格納されています。
次のページ、前のページが存在しない場合は null が格納されます。

以下は全8件の作品情報の4ページ目を2件取得する例です。
5ページ目は存在しないため、next_page が null になっています。

GET https://api.annict.com/v1/works?per_page=2&page=4&access_token=(access_token)

{
  "works": [
    ...
  ],
  "total_count": 8,
  "next_page": null,
  "prev_page": 3
}

エラー

Annict APIがエラーを返すときは、基本的に以下の形式でレスポンスボディを返します。

{
  "errors": [
    {
      "type": "invalid_params",
      "message": "リクエストに失敗しました",
      "developer_message": "per_pageは1以上の値にしてください"
    }
  ]
}

type には次の値が入ります。

関連する項目

• Annict APIの認証
• REST API V1の作品
• REST API V1のエピソード
• 開発者向けヘルプ