Skip to main content

REST APIの概要

ベース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を操作するにはアクセストークンが必要です。 アクセストークンについては認証の概要ページをご参照ください。

アクセストークンの付与​

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

  1. リクエストヘッダに付与する
  2. 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

レスポンス例​

{
  "works": [
    {
      "id":1129,
      "title":"精霊の守り人",
      "title_kana":"せいれいのもりびと",
      "media":"tv",
      ...
    }
  ]
}

HTTPステータスコード​

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

ステータスコード条件
200 (OK)リクエストが成功し、同時に処理が正常に完了したとき。
201 (Created)リクエストが成功し、新しいリソースが作られたとき。
202 (Accepted)リクエストは成功したが、処理は非同期で実行されるとき。
204 (No Content)リクエストが成功し、レスポンスボディが存在しないとき。DELETE メソッドでリソースが削除されたときに使用します。
400 (Bad Request)リクエストの内容が正しくないとき。
401 (Unauthorized)リソースへのアクセスに認証が必要なとき。リクエストを送ったクライアントが特定できないときに使用します。
403 (Forbidden)リソースへのアクセスが禁止されているとき。リクエストを送ったクライアントは特定したものの、指定されたリソースへのアクセスを禁止しているときに使用します。
404 (Not Found)指定されたリソースが存在しないとき。
500 (Internal Server Error)Annictのサーバ内部に問題があり正常にレスポンスが返せないとき。
503 (Service Unavailable)Annictのサーバが一時的に停止しているとき。

ページネーション​

作品一覧など、複数のリソースを返すAPIにはページを指定して取得するリソースを分割するようになっています。ページを指定する場合は page パラメータを、1ページあたり何件のリソースを取得するかを指定する場合は per_page パラメータを使用します。デフォルト値などの情報は各エンドポイントのドキュメントに記載しています。

レスポンスデータには 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以上の値にしてください",
  "url": "http://example.com/docs/api/validations"
}]
キー名概要
type発生したエラーのタイプ。全てのタイプは下記の表にまとめています。
messageアプリケーションの利用者向けのエラーメッセージ。
developer_messageAPIを利用している開発者向けのエラーメッセージ。
type概要
invalid_paramsリクエスト時に渡したパラメータに不備がある。