# 基本情報

本システムのAPIはHTTP RPCスタイルです。

• メソッドのURLは以下のフォーマットです。 https://customdomain.com/api/{method}
• メソッドをコールするときにHTTPSとTLS1.2以上を使用します。
• 全てのリクエストをHTTP POSTとして送信します。
• Content-type HTTPヘッダーを application/json に設定し、 認証tokenのリクエストを例外として全てのArgumentをJSONとして送ります。
• Tokenをbearer tokenとしAuthorizationのHTTPヘッダーに送信します。Tokenは用意されたBearerという文字列を持っていますので注意が必要です。BearerはOAuth 2.0の認証スキームを意味しています。

リクエストの例:

POST /api/example.method
Content-type: application/json
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA

{"example":"request"}

全てのレスポンスは常にトップレベルstatusプロパティを含んだJSONオブジェクトとなります。このプロパティはsuccessあるいはerrorとなります。errorのステータスは、システムが読み込むことができるエラーコードのerrorプロパティです。 success のステータスには、dataプロパティも存在します。dataプロパティの形はそれぞれのメソッドの説明に記載されています。

{
  "status": "success",
  "data": {
    "property": "value"
  }
}

{
  "status": "error",
  "error": "not_found"
}

# ページ分割

各メソッドの説明に、ページ分割を利用していると書かれていた場合、データのArrayにそのページの結果と次のページへのカーソル（レスポンスのdata部分にあるnextというプロパティ）が戻されます。デフォルトでは、全てのページ分割のレスポンスは100件の結果を返します。

ページ分割を使用する全てのメソッドは以下に沿って動作します。

• リクエストにはnextは任意です。リクエストのbodyにnextプロパティが含まれていない場合、最初のページが返されます。
• レスポンスにはnextは任意です。nextの属性として、レスポンスがnullを返した場合は、これ以上取得するページがないことを意味しています。
• 次のページのデータを取得するためには、同じパラメーターと前のレスポンスで受け取ったnextカーソルを新しいリクエストとして送ります。もし同じパラメーターではない場合、正確な結果を受け取ることができない可能性があります。
• 最後のページは各ページの結果の最大数よりも少ない結果となることがあります。
• 最初のページが最後のページとなることがあります。
• 特定の条件では最後のページが空欄のArrayとなる可能性があります。
• カーソルは短期間で失効します。保管したり、再利用することはできません。

# 例

# 最初のページを取得するリクエスト

{
  "search": "検索する語句"
}

# 次のページのカーソルが存在する場合のレスポンス

{
  "status": "success",
  "data": {
    "results": ["結果1", "結果2"],
    "next": "RGVRt1m9DRWp"
  }
}

# 次のページのカーソルを含めたリクエスト

{
  "search": "検索する語句",
  "next": "RGVRt1m9DRWp"
}

# 最後のページのレスポンス

{
  "status": "success",
  "data": {
    "results": ["結果1", "結果2"],
    "next": null
  }
}

# 空欄のページのレスポンス

{
  "status": "success",
  "data": {
    "results": [],
    "next": null
  }
}

各メソッドの説明では、何のパラメーターが受け入れられるのか、そして何のデータが返されるのかを表しています。

# レート制限

全てのメソッドはユーザーに最良のエクスペリエンスを提供するためにレート制限に依存します。全てのレート制限はクライアントIDごとになっています。デフォルトでは、10秒間で100リクエストに制限されています。

レート制限を超えた場合、HTTP 429 Too Many RequestsのHTTPステータスコードとRetry-AfterのHTTPヘッダーが返されます。Retry-AfterのHTTPヘッダーには再度リクエストが可能になるまでの秒数が含まれています。

上記と同時に以下のレスポンスも返されます。

{
  "status": "error",
  "error": "rate_limit_exceeded"
}

# ペイロード制限

全てのメソッドはリクエストbodyに長さの制限があります。もしペイロードが100KBを超えた場合、400 Bad Requestが以下のレスポンスと共に返されます。

{
  "status": "error",
  "error": "payload_limit_exceeded"
}

# 共通エラー

各メソッドの説明にはそのメソッド特有のエラーが記載されています。以下のエラーは各メソッドで発生する可能性のある共通エラーです。

# 認証エラー

認証に関わるエラーのレスポンスは以下に記載されているOAuth 2.0の仕様に従います。https://tools.ietf.org/html/rfc6750#section-3.1